repository·main·Indexed 41 days ago
https://github.com/vuelessjs/vuelessAn open-architecture UI library for Vue.js 3 and Nuxt.js 3/4 powered by Tailwind CSS v4. It features 65+ customizable components, a runtime theme builder, and a flexible system using CSS variables and Class Variance Authority (CVA) for styling. Supports SSR, i18n, and accessibility, with dedicated integration for Storybook v10.
Vueless provides several specialized packages to extend its functionality:
vueless-quickstart (JavaScript) and vueless-quickstart-ts (TypeScript).Vueless UI provides the following capabilities:
Vueless uses a layered styling approach powered by Class Variance Authority (CVA) and Tailwind CSS. Customization can be applied at four levels:
config.ts.vueless.config.{js,ts} file.:config prop on the component.class attribute.In config.ts, you define base classes, variants (e.g., size, color), and compound variants (combinations of props).
export default /*tw*/ {
button: {
base: "flex items-center justify-center font-medium rounded-medium transition cursor-pointer",
variants: {
size: {
"2xs": "px-2 py-1 text-small gap-0.5",
sm: "px-4 py-2 text-medium gap-1.5",
},
variant: {
solid: "bg-{color} border-transparent text-inverted hover:bg-{color}-lifted",
ghost: "text-{color} bg-transparent border-transparent",
},
},
},
defaults: {
color: "primary",
variant: "solid",
size: "md",
},
};Vueless exposes all primary and neutral shades as CSS variables, allowing for dynamic color changes at runtime.
Available variables follow the pattern:
--vl-primary-{shade} (e.g., --vl-primary-500)--vl-neutral-{shade} (e.g., --vl-neutral-500)You can use these directly in your HTML/Vue templates using Tailwind's custom property syntax.
<UButton
class="
text-(--vl-primary-600) dark:text-(--vl-primary-400)
bg-(--vl-neutral-200) dark:bg-(--vl-neutral-800)
"
/>When you extend a key that contains conditional styling (such as variants or compoundVariants), Vueless resolves the conditional classes fully before applying the extension. The resulting resolved class string is then merged with the key where the extension is applied.
export default {
component: {
UTable: {
headerCellBase: {
base: "p-4 text-sm ...",
variants: {
compact: {
true: "px-4 py-3 ...",
},
},
},
headerCellCheckbox: "{>headerCellBase} w-10 ...",
stickyHeaderCell: "{>headerCellBase} flex-none ...",
}
}
};Vueless uses a design system that enhances Tailwind CSS theming through color aliases and CSS variables. Instead of using specific Tailwind colors (like blue-500) directly in components, Vueless uses semantic aliases (like primary or success). This allows you to change your entire brand aesthetic by simply remapping these aliases in your Vueless configuration without changing component code.
| Color Alias | Default Tailwind Color | Description |
|---|---|---|
neutral | gray | Regular neutral color. |
grayscale | gray | Contrasted neutral color. |
primary | grayscale (alias) | The primary color, used as the default for components. |
secondary | gray | A secondary color that complements the primary color. |
success | green | A color used for success states. |
error | red | A color used for danger states or form error validation. |
warning | orange | A color used for warning states. |
notice | violet | A color used for highlighted informational states. |
info | blue | A color used for informational states. |
Color Alias | Default
------------|----------
neutral | gray
grayscale | gray
primary | grayscale
secondary | gray
success | green
error | red
warning | orange
notice | violet
info | blueVueless components use a structured configuration object (often exported as default /*tw*/) to manage conditional styling. This pattern allows you to define styles that react to component props without manual class manipulation in the template.
Key elements of the configuration:
base: Classes applied to every instance of the component.variants: A mapping of prop names to their possible values and corresponding classes. You can use runtime placeholders like {color} to inject values from the defaults or current props.compoundVariants: An array of objects defining classes that apply only when a specific combination of props is met (e.g., variant: 'solid' AND disabled: true).defaults: The fallback values for props if they are not explicitly provided.export default /*tw*/ {
button: {
base: "flex items-center justify-center rounded-medium transition cursor-pointer",
variants: {
variant: {
solid: "bg-{color} border-transparent text-inverted hover:bg-{color}-lifted",
outlined: "text-{color} border-{color} hover:text-{color}-lifted",
},
size: {
sm: "text-medium px-4 py-2",
md: "text-medium px-5 py-2.5",
},
loading: {
true: "gap-0 pointer-events-none",
},
},
compoundVariants: [
{
variant: "solid",
disabled: true,
class: "bg-gray-300 hover:bg-gray-300",
},
],
},
defaults: {
color: "primary",
variant: "solid",
size: "md",
},
};Vueless uses Tailwind CSS for styling and CVA (Class Variance Authority) to handle conditional styles based on props.
Each HTML tag within a component is mapped to a specific configuration key. When you provide new classes, Vueless uses tailwind-merge to intelligently merge them with the component's default styles, preventing class duplication and conflicts.
When multiple styles are applied, they follow this priority order (from highest to lowest):
class attribute: Applied to the top-level HTML tag.config prop: Used for fine-tuning specific internal parts.vueless.config.{js,ts}: Project-wide component overrides.light and dark modes. These tokens are applied across all components and can be customized globally via the Vueless configuration or your main CSS file. These tokens serve as the foundation for the entire theming system.All Vueless components follow a standardized internal file organization. While the folder name and location change based on the context (project-wide, local, or internal to the Vueless repo), the internal files remain consistent:
config.ts: Styling configuration, default prop values, and component settings.constants.ts: Component constants and identifiers.types.ts: TypeScript types and props interface.U[component].vue: The main component file.U[component][child].vue: Optional child components.use[composable].ts: Optional component-specific composables.util[service].ts: Optional component-specific utility functions.storybook/: Contains docs.mdx and stories.ts for documentation and visualization.tests/: Contains component, utility, and composable tests.