feat(module): add theme.defaultVariants option (#4400)

benjamincanac · web-flow · commit 35f90b9920c1 · 2025-07-09T14:37:49.000+02:00
diff --git a/docs/content/1.getting-started/2.installation/1.nuxt.md b/docs/content/1.getting-started/2.installation/1.nuxt.md
@@ -225,6 +225,27 @@ export default defineNuxtConfig({
 This option adds the `transition-colors` class on components with hover or active states.
 ::
 
+### `theme.defaultVariants` :badge{label="Soon" class="align-text-top"}
+
+Use the `theme.defaultVariants` option to override the default `color` and `size` variants for components.
+
+- Default: `{ color: 'primary', size: 'md' }`{lang="ts-type"}
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  modules: ['@nuxt/ui'],
+  css: ['~/assets/css/main.css'],
+  ui: {
+    theme: {
+      defaultVariants: {
+        color: 'neutral',
+        size: 'sm'
+      }
+    }
+  }
+})
+```
+
 ## Continuous Releases
 
 Nuxt UI uses [pkg.pr.new](https://github.com/stackblitz-labs/pkg.pr.new) for continuous preview releases, providing developers with instant access to the latest features and bug fixes without waiting for official releases.
diff --git a/docs/content/1.getting-started/2.installation/2.vue.md b/docs/content/1.getting-started/2.installation/2.vue.md
@@ -333,6 +333,32 @@ export default defineConfig({
 This option adds the `transition-colors` class on components with hover or active states.
 ::
 
+### `theme.defaultVariants` :badge{label="Soon" class="align-text-top"}
+
+Use the `theme.defaultVariants` option to override the default `color` and `size` variants for components.
+
+- Default: `{ color: 'primary', size: 'md' }`{lang="ts-type"}
+
+```ts [vite.config.ts]
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+import ui from '@nuxt/ui/vite'
+
+export default defineConfig({
+  plugins: [
+    vue(),
+    ui({
+      theme: {
+        defaultVariants: {
+          color: 'neutral',
+          size: 'sm'
+        }
+      }
+    })
+  ]
+})
+```
+
 ### `inertia`
 
 Use the `inertia` option to enable compatibility with [Inertia.js](https://inertiajs.com/).
diff --git a/src/module.ts b/src/module.ts
@@ -6,6 +6,9 @@ import { name, version } from '../package.json'
 
 export type * from './runtime/types'
 
+type Color = 'primary' | 'secondary' | 'success' | 'info' | 'warning' | 'error' | (string & {})
+type Size = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | (string & {})
+
 export interface ModuleOptions {
   /**
    * Prefix for components
@@ -38,14 +41,28 @@ export interface ModuleOptions {
      * @defaultValue `['primary', 'secondary', 'success', 'info', 'warning', 'error']`
      * @link https://ui.nuxt.com/getting-started/installation/nuxt#themecolors
      */
-    colors?: string[]
+    colors?: Color[]
 
     /**
      * Enable or disable transitions on components
      * @defaultValue `true`
      * @link https://ui.nuxt.com/getting-started/installation/nuxt#themetransitions
      */
     transitions?: boolean
+
+    defaultVariants?: {
+      /**
+       * The default color variant to use for components
+       * @defaultValue `'primary'`
+       */
+      color?: Color
+
+      /**
+       * The default size variant to use for components
+       * @defaultValue `'md'`
+       */
+      size?: Size
+    }
   }
 }
 
diff --git a/src/templates.ts b/src/templates.ts
@@ -26,6 +26,14 @@ export function getTemplates(options: ModuleOptions, uiConfig: Record<string, an
         const template = (theme as any)[component]
         const result = typeof template === 'function' ? template(options) : template
 
+        // Override default variants from nuxt.config.ts
+        if (result?.defaultVariants?.color && options.theme?.defaultVariants?.color) {
+          result.defaultVariants.color = options.theme.defaultVariants.color
+        }
+        if (result?.defaultVariants?.size && options.theme?.defaultVariants?.size) {
+          result.defaultVariants.size = options.theme.defaultVariants.size
+        }
+
         const variants = Object.entries(result.variants || {})
           .filter(([_, values]) => {
             const keys = Object.keys(values as Record<string, unknown>)
@@ -56,7 +64,10 @@ export function getTemplates(options: ModuleOptions, uiConfig: Record<string, an
           return [
             `import template from ${JSON.stringify(templatePath)}`,
             ...generateVariantDeclarations(variants),
-            `const result = typeof template === 'function' ? (template as Function)(${JSON.stringify(options, null, 2)}) : template`,
+            `const options = ${JSON.stringify(options, null, 2)}`,
+            `const result = typeof template === 'function' ? (template as Function)(options) : template`,
+            `if (result?.defaultVariants?.color && options.theme?.defaultVariants?.color) result.defaultVariants.color = options.theme.defaultVariants.color`,
+            `if (result?.defaultVariants?.size && options.theme?.defaultVariants?.size) result.defaultVariants.size = options.theme.defaultVariants.size`,
             `const theme = ${json}`,
             `export default result as typeof theme`
           ].join('\n\n')
