Nuxt UI: look and theme reference for a non-Vue component kit

Source snapshot: github.com/nuxt/ui, branch v4 default, commit 9c4e33b7e076aa6bd59b5bd99d8621d9dc1bcf60 (2026-10-08), package.json version 4.11.3. It is built on Tailwind CSS v4, Reka UI and tailwind-variants. Every value below comes from that tree unless a URL says otherwise. Docs live at https://ui.nuxt.com/docs.

Notation used throughout:

• Tailwind v4 spacing unit is --spacing: 0.25rem, so p-2.5 is 10px and size-5 is 20px (at 16px root).
• text-xs is 12px with 16px line height, text-sm is 14/20, text-base is 16/24, text-lg is 18/28, text-xl is 20/28 and text-2xl is 24/32. text-sm/4 means 14px with a 16px line, and text-[10px]/3 means 10px with a 12px line.
• font-medium is 500 and font-semibold is 600.
• ring is a 1px inset box-shadow (ring-inset). outline-3 is a 3px solid outline at offset 0. X/25 means colour X at alpha 0.25 (Tailwind uses color-mix(in oklab, X 25%, transparent)).
• Semantic utility names map to CSS variables. text-default is --ui-text, text-muted is --ui-text-muted, bg-default is --ui-bg, bg-elevated is --ui-bg-elevated, ring-accented is --ui-border-accented, bg-inverted is --ui-bg-inverted, bg-border is --ui-border, and so on. See section 2.4.
• bg-primary, text-primary and similar use --ui-primary.

1. Licence

Source: LICENSE.md at the repo root (https://github.com/nuxt/ui/blob/v4/LICENSE.md).

MIT License

Copyright (c) 2023 Nuxt

Keep the full MIT permission and warranty text with that copyright line in the third-party notice. Two related notices:

• The default icon set is Lucide (i-lucide-*, src/theme/icons.ts), which is ISC-licensed.
• The palettes come from Tailwind CSS (MIT, Copyright (c) Tailwind Labs, Inc.).

Copying palette values or icons brings in those notices as well.

2. Design tokens

2.1 Colour aliases and default palettes

Sources: src/utils/defaults.ts (getDefaultConfig, resolveColors) and the docs page https://ui.nuxt.com/docs/getting-started/theme/design-system.

• theme.colors defaults to ['primary','secondary','success','info','warning','error']. neutral is always present and handled separately: every component has a dedicated neutral branch that uses the semantic tokens instead of a palette.
• Users override the mapping through app.config.ts (ui.colors.primary = 'indigo').
• If neutral is set to 'neutral', Nuxt UI substitutes the Tailwind v3 hex neutral palette (--color-old-neutral-*) in src/templates.ts and runtime/plugins/colors.ts. This does not apply to the default (slate).

Generated alias variables (src/runtime/plugins/colors.ts):

--ui-color-<alias>-<50..950> = the palette's shade
:root, .light { --ui-<alias>: var(--ui-color-<alias>-500); }   /* light: shade 500 */
.dark         { --ui-<alias>: var(--ui-color-<alias>-400); }   /* dark:  shade 400 */

This rule covers every alias except neutral. For example, --ui-primary is green-500 in light mode and green-400 in dark mode.

2.2 Tailwind v4 palettes used by default

Source: tailwindcss@4.1.11/theme.css. Tailwind defines them in OKLCH, and the hex values below are the sRGB conversions (they match Tailwind’s published hex).

Exact OKLCH sources for the shades used most:

slate-50 oklch(98.4% 0.003 247.858); slate-100 oklch(96.8% 0.007 247.896); slate-200 oklch(92.9% 0.013 255.508); slate-300 oklch(86.9% 0.022 252.894); slate-400 oklch(70.4% 0.04 256.788); slate-500 oklch(55.4% 0.046 257.417); slate-600 oklch(44.6% 0.043 257.281); slate-700 oklch(37.2% 0.044 257.287); slate-800 oklch(27.9% 0.041 260.031); slate-900 oklch(20.8% 0.042 265.755); green-400 oklch(79.2% 0.209 151.711); green-500 oklch(72.3% 0.219 149.579); blue-400 oklch(70.7% 0.165 254.624); blue-500 oklch(62.3% 0.214 259.815); yellow-400 oklch(85.2% 0.199 91.936); yellow-500 oklch(79.5% 0.184 86.047); red-400 oklch(70.4% 0.191 22.216); red-500 oklch(63.7% 0.237 25.331).

2.3 Semantic CSS variables (light and dark)

Source: src/runtime/index.css (@layer theme). Light values apply on :root, :host, .light, dark values on .dark. Here “neutral” means --ui-color-neutral-*, which is slate by default.

Mode-independent variables (:root, :host):

The body base style is antialiased text-default bg-default scheme-light dark:scheme-dark (src/templates.ts, the ui.css template).

2.4 Tailwind theme bridge and radius scale

Source: src/templates.ts, the @theme default inline block.

--radius-xs:  calc(var(--ui-radius) * 0.5)   = 2px
--radius-sm:  var(--ui-radius)               = 4px
--radius-md:  calc(var(--ui-radius) * 1.5)   = 6px
--radius-lg:  calc(var(--ui-radius) * 2)     = 8px
--radius-xl:  calc(var(--ui-radius) * 3)     = 12px
--radius-2xl: calc(var(--ui-radius) * 4)     = 16px
--radius-3xl: calc(var(--ui-radius) * 6)     = 24px
(rounded-full = 9999px, unchanged)

The pixel values assume the default --ui-radius of 4px.

Utility to variable mapping (same block):

2.5 Motion and shadow tokens

Sources: Tailwind v4 theme.css and src/runtime/keyframes.css.

Easing curves

Shadows

Keyframes

Under prefers-reduced-motion, the scale and slide keyframes are redefined as opacity-only fades (keyframes.css around line 620).

Transitions

When theme.transitions is true (the default), interactive elements add transition-colors. Tailwind’s default for that is 150ms with cubic-bezier(0.4, 0, 0.2, 1).

Common durations

2.6 Shared focus and disabled conventions

These apply across components unless a section says otherwise.

• Focus ring. outline-<c>/25 focus-visible:outline-3 gives a 3px outline at 25% alpha of the colour. For outline and subtle styles, focus-visible:ring-<c> also turns the 1px inset ring fully opaque. With color=neutral, <c> is the inverted token.
• Disabled state. disabled:opacity-75 disabled:cursor-not-allowed.
• Field groups. When a component sits in a UFieldGroup, its inner corners are squared (rounded-e-none and similar) and the group uses -space-x-px (src/theme/field-group.ts).

3. Components

Each section cites src/theme/<file>.ts for classes and src/runtime/components/<Name>.vue for props. The class lists are verbatim. The <c> placeholder stands for any non-neutral alias such as primary.

3.1 Button

Sources: src/theme/button.ts and Button.vue. Docs: https://ui.nuxt.com/docs/components/button.

Props: label (string); color (alias or 'neutral', primary); variant (solid | outline | soft | subtle | ghost | link, solid); size (xs | sm | md | lg | xl, md); activeColor, activeVariant (used when a link is active); square (boolean, false. Set automatically when there is an icon and no label.); block (boolean, false); loading, loadingAuto (boolean, false); loadingIcon (icon, i-lucide-loader-circle); icon, leadingIcon, trailingIcon, avatar, leading, trailing; Link props (to, href, target, disabled).

Base classes: rounded-md font-medium inline-flex items-center disabled:opacity-75 transition-colors. The radius is 6px.

Sizes

block adds w-full justify-center, and the trailing icon gets ms-auto. Loading spins the leading icon (animate-spin), or the trailing icon when the button has only a trailing one.

Resulting heights with the default line heights:

Variants, color=<c> (compoundVariants, verbatim):

Variants, color=neutral:

The source also lists aria-disabled: and dark:disabled: twins of each disabled: class. They are omitted above because they use identical values.

3.2 Badge

Sources: src/theme/badge.ts and Badge.vue.

Props: as ('span'); label (string or number); color (alias or neutral, primary); variant (solid | outline | soft | subtle (no ghost or link), solid); size (xs..xl, md); square (boolean, auto when there is no label); icon and avatar props (as Button).

Base classes: font-medium inline-flex items-center.

Sizes

Variants

3.3 Avatar

Sources: src/theme/avatar.ts and Avatar.vue.

Props: src, alt (string); icon (icon); text (string. Otherwise initials come from alt.); size (3xs..3xl, md); color (alias or neutral, neutral); chip (boolean or ChipProps); as ('span').

Classes

Sizes (root box and font size):

3.4 Card

Sources: src/theme/card.ts and Card.vue.

Props: as ('div'); title (string); description (string); variant (solid | outline | soft | subtle, outline).

Card has no sizes and no colour prop.

Slots

Variants

3.5 Input

Sources: src/theme/input.ts and Input.vue.

Props: type ('text'); placeholder (string); color (alias or neutral, primary); variant (outline | soft | subtle | ghost | none, outline); size (xs..xl, md); highlight (boolean, forces the coloured ring); fixed (boolean, false, which enables the responsive text sizes below); autocomplete ('off'); autofocusDelay (number, 0); disabled, required, loading, icon, leadingIcon, trailingIcon, avatar, modelValue.

Classes

Sizes

The larger text on mobile avoids iOS zoom. On desktop the sizes match Button: md is 14px text in a 32px-high field.

Variants (base, any colour):

Colour compounds

3.6 Textarea

Sources: src/theme/textarea.ts (merges in input.ts) and Textarea.vue.

Props: the same as Input, plus: rows (3); maxrows (0); autoresize (false); autoresizeDelay (0).

Classes, variants, colours and sizes are identical to Input. The only differences:

• Leading and trailing slots are items-start and pinned to the top: inset-y-1 for xs, inset-y-1.5 for sm and md, inset-y-2 for lg and xl.
• autoresize adds resize-none.

3.7 Select

Sources: src/theme/select.ts (merges in input.ts) and Select.vue.

Props: items; placeholder; color, variant, size (primary / outline / md); trailingIcon (i-lucide-chevron-down); selectedIcon (i-lucide-check); content ({ side:'bottom', sideOffset:8, collisionPadding:8, position:'popper' }); arrow (false); portal (true); valueKey ('value'); labelKey ('label'); descriptionKey ('description'); multiple, highlight, fixed.

Trigger. Uses the Input sizes and variants with these changes:

• base becomes relative group rounded-md inline-flex items-center.
• outline adds hover:bg-elevated disabled:bg-default.
• subtle adds hover:bg-accented/75 disabled:bg-elevated.
• placeholder is truncate text-dimmed.

Popup slots

Item sizes

3.8 Checkbox

Sources: src/theme/checkbox.ts and Checkbox.vue.

Props: label, description; color (primary); variant (list | card, default list); size (md); indicator (start | end | hidden, default start); highlight; icon (i-lucide-check); indeterminateIcon (i-lucide-minus); modelValue (boolean | 'indeterminate'); required, disabled.

Slots

required adds a red * after the label (after:text-error). disabled gives the root opacity-75.

Sizes

Card variant

• Root: border border-default rounded-lg. Hover (not checked, not disabled): bg-elevated/50 border-accented.
• Checked with <c>: border-<c>/50 bg-<c>/10. Checked with neutral: border-inverted/50 bg-elevated.

Focus

• list variant: on the box, outline-<c>/25 focus-visible:outline-3 focus-visible:ring-<c>.
• card variant: on the card, has-focus-visible:outline-3 and border-<c>.

3.9 Switch

Sources: src/theme/switch.ts and Switch.vue.

Props: color (primary); size (md); loading; loadingIcon (i-lucide-loader-circle); checkedIcon, uncheckedIcon; label, description; highlight, required, disabled.

Slots

Sizes

The track height is the thumb plus the 2px transparent border on each side, so md is 36x20. The wrapper is ms-2.

3.10 RadioGroup

Sources: src/theme/radio-group.ts and RadioGroup.vue.

Props: items; legend; valueKey ('value'); labelKey ('label'); descriptionKey ('description'); size (md); variant (list | card | table, default list); color (primary); orientation (vertical); indicator (start); highlight, disabled, required, modelValue.

Slots

Sizes

Card and table variants

• card: like Checkbox’s card. Items are border border-default rounded-lg. Checked: border-<c>/50 bg-<c>/10 (neutral: border-inverted/50 bg-elevated).
• table: the items are joined. Horizontal uses -space-x-px, first:rounded-s-lg and last:rounded-e-lg. Vertical uses -space-y-px, first:rounded-t-lg and last:rounded-b-lg.

3.11 Tabs

Sources: src/theme/tabs.ts and Tabs.vue.

Props: items; color (primary); variant (pill | link, default pill); size (md); orientation (horizontal); content (true); defaultValue ('0'); unmountOnHide (true); valueKey ('value'); labelKey ('label').

Slots

Trigger sizes

Trailing badges are sm.

pill variant

• list: bg-elevated rounded-lg (8px).
• trigger: grow.
• indicator: rounded-md shadow-xs plus bg-<c> (neutral bg-inverted). Horizontal adds inset-y-1; vertical adds inset-x-1.
• active trigger: text-inverted.

link variant

• list: border-default. Horizontal adds border-b -mb-px; vertical adds border-s -ms-px.
• indicator: rounded-full bg-<c>, 1px. Horizontal sits at -bottom-px h-px; vertical uses w-px.
• active trigger: text-<c> (neutral text-highlighted).

3.12 Accordion

Sources: src/theme/accordion.ts and Accordion.vue.

Props: items; type ('single'); collapsible (true); unmountOnHide (true); trailingIcon (i-lucide-chevron-down); valueKey ('value'); labelKey ('label'); disabled.

Accordion has no size, colour or variant.

Slots

Disabled triggers get opacity-75.

3.13 Modal

Sources: src/theme/modal.ts and Modal.vue.

Props: title, description; overlay (true); scrollable (false); transition (true); fullscreen (false); portal (true); close (true. A ghost neutral Button with i-lucide-x.); dismissible (true); modal (true); open (v-model).

Slots

Transitions (200ms ease-out): the overlay fades in and out; the content uses scale-in / scale-out (0.95 to 1 with opacity).

3.14 Slideover

Sources: src/theme/slideover.ts and Slideover.vue.

Props: the same as Modal, minus scrollable and fullscreen, plus: side (top | right | bottom | left, default right); inset (false).

Slots

Header, footer, title, description and close are identical to Modal.

Placement

Transition: slide-in-from-<side> / slide-out-to-<side> (translate ±100%), 200ms ease-out, with an overlay fade.

3.15 DropdownMenu

Sources: src/theme/dropdown-menu.ts and DropdownMenu.vue.

Props: items (nested arrays form groups; item types are label, separator, checkbox and link); size (md); content ({ side:'bottom', sideOffset:8, collisionPadding:8 }); arrow (false); portal (true); modal (true); checkedIcon (i-lucide-check); loadingIcon (spinner); externalIcon (true (i-lucide-arrow-up-right)); filter (false); labelKey ('label'); descriptionKey ('description'); disabled.

Each item can also carry a per-item color and kbds.

Slots

Sizes

3.16 Tooltip

Sources: src/theme/tooltip.ts, Tooltip.vue and App.vue (TooltipProvider).

Props: text; kbds; content ({ side:'bottom', sideOffset:8, collisionPadding:8 }); arrow (false); portal (true); reference; delayDuration (Reka provider default 700ms (skipDelayDuration 300ms). Configurable through <UApp :tooltip>.).

Slots

3.17 Toast and Toaster

Sources: src/theme/toast.ts, src/theme/toaster.ts, Toast.vue, Toaster.vue and the useToast() composable.

Toast props

Props: title, description; icon; avatar (avatarSize 2xl); color (primary); orientation (vertical); close (true. A link neutral Button, size="sm".); closeIcon (i-lucide-x); actions (Buttons rendered with size="xs" and the toast colour); duration (5000); progress (true. A bottom progress bar.).

Toast slots

Toaster props

Props: position (bottom-right. Six positions.); expand (true); duration (5000); progress (true); max (5); portal (true).

Toaster slots

• viewport: fixed flex flex-col w-[calc(100%-2rem)] sm:w-96 z-[100] (384px wide), placed at bottom-4 right-4 and similar.
• toast: stacked absolutely using --index, --transform and --front-height. Non-front toasts are collapsed and their content hidden. Slide-in comes from the top or bottom edge over 200ms, and swipe-to-dismiss follows the swipe direction.

3.18 Table

Sources: src/theme/table.ts and Table.vue. It is built on TanStack Table.

Props: data; columns (TanStack ColumnDef); caption (sr-only); sticky (boolean | 'header' | 'footer', default false); loading; loadingColor (primary); loadingAnimation (carousel | carousel-inverse | swing | elastic, default carousel); empty (t('table.noData')); virtualize (false (estimateSize 65, overscan 12)); onSelect, onHover; state props (sorting, selection, pinning and similar).

Slots

3.19 Pagination

Sources: src/theme/pagination.ts and Pagination.vue. It is composed entirely of Buttons.

Props: page (v-model); total (0); itemsPerPage (10); siblingCount (2); showEdges (false); showControls (true); color (neutral); variant (outline); activeColor (primary); activeVariant (solid); size (Button default md); to ((page) => link); firstIcon (i-lucide-chevrons-left); prevIcon (i-lucide-chevron-left); nextIcon (i-lucide-chevron-right); lastIcon (i-lucide-chevrons-right); ellipsisIcon (i-lucide-ellipsis).

Slots

The look therefore comes from Button: neutral outline (section 3.1) for every page, and primary solid for the current one.

3.20 Breadcrumb

Sources: src/theme/breadcrumb.ts and Breadcrumb.vue.

Props: items ({ label, icon, avatar, to, disabled }); separatorIcon (i-lucide-chevron-right); color (primary); labelKey ('label'); as ('nav').

Slots

3.21 NavigationMenu

Sources: src/theme/navigation-menu.ts and NavigationMenu.vue.

Props: items (flat or nested arrays; children produce dropdown or collapsible content); orientation (horizontal); contentOrientation (horizontal); variant (pill | link, default pill); color (primary); highlight (false); highlightColor (primary); collapsed (false (vertical only)); tooltip (false); popover (false); arrow (false); type ('multiple'); trailingIcon (i-lucide-chevron-down); externalIcon (true); delayDuration (0); unmountOnHide (true); valueKey ('value'); labelKey ('label').

Slots

Orientation

States

Highlight: draws an after: bar in highlightColor.

• horizontal: after:-bottom-2 after:inset-x-2.5 after:h-px.
• vertical, level: after:-start-1.5 after:w-px.

Horizontal dropdown popup

• viewport: bg-default shadow-lg rounded-md ring ring-default, scale-in over 100ms, animating width and height over 200ms.
• child list: grid grid-cols-2 gap-2 p-2.
• childLink: px-3 py-2 gap-2 text-sm, hover before:bg-elevated/50, active before:bg-elevated text-highlighted.
• childLinkDescription: text-muted.

3.22 Dashboard layout

Sources: src/theme/dashboard-*.ts, Dashboard*.vue and src/runtime/composables/useResizable.ts. Docs: https://ui.nuxt.com/docs/components/dashboard-group.

DashboardGroup

• Props: storage 'cookie' | 'local' (default 'cookie'), storageKey 'dashboard', persistent true, unit '%' | 'rem' | 'px' (default '%').
• Base: fixed inset-0 flex overflow-hidden.
• Provides a context with sidebarOpen, sidebarCollapsed and the toggle and collapse functions.

DashboardSidebar

Props: id; side ('left'); mode ('slideover' | 'modal' | 'drawer', default 'slideover'. This is the mobile presentation.); menu (props passed through to that overlay); toggle (true); toggleSide ('left'); autoClose (true); resizable (false); collapsible (false); minSize (10); maxSize (20); defaultSize (15); collapsedSize (0).

minSize, maxSize and defaultSize are in unit (% by default). open and collapsed are v-models.

Slots:

Behaviour:

• Hidden below lg (1024px). There, the same content renders inside a Slideover, Modal or Drawer opened by DashboardSidebarToggle (lg:hidden, a Button), and the menu variant adds sm:px-6 paddings.
• DashboardSidebarCollapse (hidden lg:flex) collapses it.
• The resize handle (DashboardResizeHandle) is cursor-ew-resize with a 12px hit zone (before:-left-1.5 before:-right-1.5).

DashboardPanel

• Props: id, minSize 15, maxSize, defaultSize, resizable false.
• root: relative flex flex-col min-w-0 min-h-svh lg:not-last:border-e lg:not-last:border-default shrink-0. With a size it becomes w-full lg:w-(--width); otherwise flex-1.
• body: flex flex-col gap-4 sm:gap-6 flex-1 overflow-y-auto p-4 sm:p-6.
• The header and footer slots usually hold DashboardNavbar and DashboardToolbar.

DashboardNavbar

Props: title, icon, toggle (default true; a sidebar toggle shown below lg) and toggleSide ('left').

DashboardToolbar (often used with the navbar)

• root: shrink-0 flex items-center justify-between border-b border-default px-4 sm:px-6 gap-1.5 overflow-x-auto min-h-[49px].

4. Fonts and typography

Sources: src/module.ts, src/templates.ts, Tailwind v4 theme.css and docs/app/assets/css/main.css.

Font family

The library sets no font family of its own. Text uses Tailwind’s --font-sans:

ui-sans-serif, system-ui, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol', 'Noto Color Emoji'

The mono stack is ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono', 'Courier New', monospace. It is used by Kbd and code.

Web font loading

The module enables @nuxt/fonts (option fonts: true) with default weights [400, 500, 600, 700]. Any family a user names in --font-sans is then auto-downloaded.

The ui.nuxt.com site itself uses --font-sans: 'Public Sans', sans-serif (docs/app/assets/css/main.css). This is the face visible in the docs screenshots, so it is the one to use to match the docs look. Public Sans is SIL OFL 1.1.

Base styles

• body: antialiased text-default bg-default. Default text is neutral-700 on white in light mode and neutral-200 on neutral-900 in dark mode.
• Root font size: browser default, 16px.

Sizes used by the components (md defaults)

Colour hierarchy

5. Behaviours that are hard for a non-DOM toolkit

These come from Reka UI primitives (https://reka-ui.com) driven by the components above.

Cross-cutting constructs to emulate:

• before: / after: pseudo-element highlight layers. Menu and nav highlights are a rounded rectangle inset 1px behind the content.
• Alpha-mixed colours (/10, /25, /50, /75). Blend in OKLab when matching closely; sRGB alpha is close enough in practice.
• Focus-visible versus focus. Outlines show only for keyboard focus.
• Reduced motion. Swap the scale and slide animations for opacity fades.
• RTL. Logical properties (ms-, ps-, start-) and rtl: translate flips on Switch and Tabs.

Edit this page on GitHub ↗