Tailwind CSS uses a CSS-first configuration, letting you define your design tokens with the @theme directive directly in your CSS. This makes your theme portable, maintainable and easy to customize.
@import "tailwindcss";
@import "@nuxt/ui";
@theme {
/* Your custom design tokens go here */
}
Check the Tailwind CSS documentation for all available theme variable customization options.
Use the --font-* theme variables to customize the font family utilities in your project.
@import "tailwindcss";
@import "@nuxt/ui";
@theme {
--font-sans: 'Public Sans', system-ui, sans-serif;
--font-mono: 'JetBrains Mono', monospace;
}
Fonts defined here are automatically loaded and optimized by the @nuxt/fonts module.
Use the --color-* theme variables to customize your colors or override default colors.
@import "tailwindcss";
@import "@nuxt/ui";
@theme static {
/* Override default green color */
--color-green-50: #EFFDF5;
--color-green-100: #D9FBE8;
--color-green-200: #B3F5D1;
--color-green-300: #75EDAE;
--color-green-400: #00DC82;
--color-green-500: #00C16A;
--color-green-600: #00A155;
--color-green-700: #007F45;
--color-green-800: #016538;
--color-green-900: #0A5331;
--color-green-950: #052E16;
/* Define new custom color */
--color-brand-50: #fef2f2;
--color-brand-100: #fee2e2;
--color-brand-200: #fecaca;
--color-brand-300: #fca5a5;
--color-brand-400: #f87171;
--color-brand-500: #ef4444;
--color-brand-600: #dc2626;
--color-brand-700: #b91c1c;
--color-brand-800: #991b1b;
--color-brand-900: #7f1d1d;
--color-brand-950: #450a0a;
}
When adding custom colors, make sure to define all shades from 50 to 950 for each color.
Use the --breakpoint-* theme variables to customize your breakpoints.
@import "tailwindcss";
@import "@nuxt/ui";
@theme {
--breakpoint-3xl: 1920px;
--breakpoint-4xl: 2560px;
--breakpoint-5xl: 3840px;
}
Nuxt UI's color system is designed around semantic naming rather than specific color values. This approach makes your UI more maintainable and allows for easy theme switching.
Nuxt UI provides semantic color aliases that describe the purpose of the color. Each alias is defined based on a color from your @theme configuration, which can be any color you define in addition to the default Tailwind CSS palette.
| Color | Default | Description |
|---|---|---|
primary | green | Main CTAs, active navigation, brand elements, important links |
secondary | blue | Secondary buttons, alternative actions, complementary UI elements |
success | green | Success messages, completed states, positive confirmations |
info | blue | Info alerts, tooltips, help text, neutral notifications |
warning | yellow | Warning messages, pending states, attention-needed items |
error | red | Error messages, validation errors, destructive actions |
neutral | slate | Text, borders, backgrounds, disabled states |
These semantic colors are available in the color prop of Nuxt UI components:
<template>
<UButton color="primary">Save Changes</UButton>
</template>
Try the theme picker in the header to instantly see how different color schemes affect the entire UI!
You can configure these colors at runtime in your app.config.ts file under the ui.colors key, allowing for dynamic theme customization without restarting the server:
export default defineAppConfig({
ui: {
colors: {
primary: 'blue',
secondary: 'purple',
neutral: 'zinc'
}
}
})
You can configure these colors at runtime in your vite.config.ts file under the ui.colors key, allowing for dynamic theme customization:
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'
export default defineConfig({
plugins: [
vue(),
ui({
ui: {
colors: {
primary: 'blue',
secondary: 'purple',
neutral: 'zinc'
}
}
})
]
})
You can only use colors that exist in your theme. Either:
blue, green, zinc)@theme directive (like brand in our example above)You may want to define extra semantic colors beyond the defaults, such as adding a tertiary color:
First, register the new color in your nuxt.config.ts under the ui.theme.colors key:
export default defineNuxtConfig({
ui: {
theme: {
colors: [
'primary',
'secondary',
'tertiary',
'info',
'success',
'warning',
'error'
]
}
}
})
Then, assign it in your app.config.ts under the ui.colors key:
export default defineAppConfig({
ui: {
colors: {
primary: 'blue',
secondary: 'purple',
tertiary: 'indigo'
}
}
})
Register and assign the new color in your vite.config.ts file:
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'
export default defineConfig({
plugins: [
vue(),
ui({
theme: {
colors: [
'primary',
'secondary',
'tertiary',
'info',
'success',
'warning',
'error'
]
},
ui: {
colors: {
primary: 'blue',
secondary: 'purple',
tertiary: 'indigo'
}
}
})
]
})
Finally, use this new color in components that support the color prop or as a class:
<UButton color="tertiary">
Special Action
</UButton>