Vuecs 📦

A Vue 3 component library providing reusable UI components with TypeScript support, CSS extraction, and composable theming.

Table of Contents

• Overview
• Getting Started
• Components
• Themes
• Contributing
• License

Overview

Vuecs splits into two kinds of packages:

• Components — render logic, props, slots, and structural vc-* classes. Visually unstyled by default.
• Themes — pure data objects mapping component slots (e.g. listItem.root, pagination.link) to CSS class strings. Swap, compose, or override themes without touching component code.

Themes are resolved at runtime by @vuecs/core's theme manager through four layers: component defaults → themes (in array order) → global overrides → per-instance themeClass prop.

Getting Started

npm install @vuecs/core @vuecs/theme-bootstrap @vuecs/icon @vuecs/icons-lucide

import vuecs, { extend } from '@vuecs/core';
import bootstrap from '@vuecs/theme-bootstrap';
import lucide from '@vuecs/icons-lucide';

app.use(vuecs, {
    themes: [bootstrap()],
    icons:  [lucide()],
    overrides: {
        elements: { listItem: { classes: { root: extend('border-bottom') } } },
    },
});

See @vuecs/core for the full theme API (installThemeManager, useComponentTheme, extend(), variant system).

Components

@vuecs/core

Theme resolution engine and component infrastructure. Exports installThemeManager, useComponentTheme, extend(), resolveComponentTheme, and shared types. Required by every component and theme package.

Full documentation

@vuecs/list-controls

List display with loading, empty state, header/footer/body, and per-item event handling (created/updated/deleted).

<VCList :data="items" :busy="loading" :total="total">
    <template #item="{ data, deleted }">
        <span>{{ data.name }}</span>
        <button @click="deleted(data)">Remove</button>
    </template>
</VCList>

Full documentation

@vuecs/forms

Form inputs on Reka UI primitives, with validation support: Checkbox + CheckboxGroup, Switch, Radio + RadioGroup, Input, Number, Pin, Select + SelectSearch, Slider (single + range), Tags, Textarea.

<VCFormGroup label-content="Email" :validation-messages="errors">
    <VCFormInput v-model="form.email" type="email" />
</VCFormGroup>

Full documentation

@vuecs/pagination

Pagination component with page calculation utilities and Iconify-backed icon props.

<VCPagination :total="100" :limit="10" :offset="0" @load="onPageChange" />

Full documentation

@vuecs/navigation

Multi-level navigation with NavigationManager, path-based active matching, and vue-router integration.

Full documentation

@vuecs/countdown

Countdown timer with auto-start, visibility handling, and a scoped slot for custom display.

Full documentation

@vuecs/gravatar

Gravatar avatar component.

Full documentation

@vuecs/link

Router-aware link with automatic detection of vue-router or Nuxt.

Full documentation

@vuecs/timeago

Relative time display with locale support and auto-update.

Full documentation

Themes

Themes are functions returning { elements, classesMergeFn? }. Multiple themes compose in array order. Themes resolve CSS class strings only — icon glyphs are provided separately by icon presets (@vuecs/icons-lucide, @vuecs/icons-font-awesome, …) configured under icons:. Themes only depend on @vuecs/core; the class strings they provide target whichever component packages the consumer has installed.

@vuecs/theme-bootstrap

Bootstrap class defaults (form-control, btn btn-primary, d-flex, …) for every component. Currently targets Bootstrap 5; renamed from @vuecs/theme-bootstrap-v5 in 3.0 (clean break — no shim). The previous @vuecs/theme-bootstrap-v4 package was removed in the same release; Bootstrap 4's Sass-compiled stylesheet didn't benefit from the design-token bridge.

import bootstrap from '@vuecs/theme-bootstrap';

app.use(vuecs, { themes: [bootstrap()] });

@vuecs/theme-tailwind

Tailwind CSS utility-class defaults for every component. Ships with tailwind-merge pre-wired as the theme's classesMergeFn so extend() calls in overrides merge cleanly, and exports a typed merge: ClassesMergeFn helper for reuse at the global overrides layer.

import tailwind, { merge } from '@vuecs/theme-tailwind';

app.use(vuecs, {
    themes: [tailwind()],
    overrides: { classesMergeFn: merge },
});

Icons

Icon vocabularies are configured separately from themes. Pick an Iconify-backed preset (@vuecs/icons-lucide, @vuecs/icons-font-awesome) to populate the semantic icon-prop slots on VCPagination, VCButton, etc.

import vuecs from '@vuecs/core';
import bootstrap from '@vuecs/theme-bootstrap';
import lucide from '@vuecs/icons-lucide';

app.use(vuecs, {
    themes: [bootstrap()],
    icons:  [lucide()],
});

See @vuecs/icon for the runtime component (<VCIcon>) and the icon delivery options (Nuxt, Vite, SPA).

Contributing

npm ci
npm run build
npm run test
npm run lint

License

Made with 💚

Published under Apache 2.0 License.