mirror of
https://github.com/ArthurDanjou/ui.git
synced 2026-01-14 20:19:34 +01:00
docs(app): framework select global (#2719)
Co-authored-by: harlan <harlan@harlanzw.com>
This commit is contained in:
Benjamin Canac
GitHub
@@ -71,7 +71,7 @@ You can now use Nuxt UI in any Vue project without Nuxt by adding the Vite and V
|
||||
- **Developer Experience**: Complete TypeScript support with IntelliSense and auto-completion
|
||||
|
||||
::tip{to="/getting-started/installation/vue"}
|
||||
Learn how to install and configure Nuxt UI in a Vue project in the [Vue installation guide](/getting-started/installation/vue).
|
||||
Learn how to install and configure Nuxt UI in a Vue project in the **Vue installation guide**.
|
||||
::
|
||||
|
||||
## Migration
|
||||
|
||||
@@ -0,0 +1 @@
|
||||
shadow: true
|
||||
@@ -1,16 +1,13 @@
|
||||
---
|
||||
title: Install in a Nuxt app
|
||||
title: Installation
|
||||
description: 'Learn how to install and configure Nuxt UI in your Nuxt application.'
|
||||
select:
|
||||
items:
|
||||
- label: Nuxt
|
||||
icon: i-logos-nuxt-icon
|
||||
to: /getting-started/installation/nuxt
|
||||
- label: Vue
|
||||
icon: i-logos-vue
|
||||
to: /getting-started/installation/vue
|
||||
navigation.framework: nuxt
|
||||
---
|
||||
|
||||
::callout{to="/getting-started/installation/vue" icon="i-logos-vue" class="hidden"}
|
||||
Looking for the **Vue** version?
|
||||
::
|
||||
|
||||
## Setup
|
||||
|
||||
::steps{level="4"}
|
||||
|
||||
@@ -1,16 +1,13 @@
|
||||
---
|
||||
title: Install in a Vue app
|
||||
title: Installation
|
||||
description: 'Learn how to install and configure Nuxt UI in your Vue application.'
|
||||
select:
|
||||
items:
|
||||
- label: Nuxt
|
||||
icon: i-logos-nuxt-icon
|
||||
to: /getting-started/installation/nuxt
|
||||
- label: Vue
|
||||
icon: i-logos-vue
|
||||
to: /getting-started/installation/vue
|
||||
navigation.framework: vue
|
||||
---
|
||||
|
||||
::callout{to="/getting-started/installation/nuxt" icon="i-logos-nuxt-icon" class="hidden"}
|
||||
Looking for the **Nuxt** version?
|
||||
::
|
||||
|
||||
## Setup
|
||||
|
||||
::steps{level="4"}
|
||||
@@ -155,10 +152,6 @@ export default defineConfig({
|
||||
|
||||
Use the `ui` option to provide configuration for Nuxt UI.
|
||||
|
||||
::warning
|
||||
In the rest of the docs, there are references to the `app.config.ts` file (which is a Nuxt feature). When using Nuxt UI in a project without Nuxt, this configuration is passed in this `ui` option instead.
|
||||
::
|
||||
|
||||
```ts [vite.config.ts]
|
||||
import { defineConfig } from 'vite'
|
||||
import vue from '@vitejs/plugin-vue'
|
||||
|
||||
@@ -78,8 +78,14 @@ Nuxt UI extends Tailwind CSS's theming capabilities, providing a flexible design
|
||||
|
||||
### Colors
|
||||
|
||||
::framework-only
|
||||
#nuxt
|
||||
Nuxt UI leverages Nuxt [App Config](https://nuxt.com/docs/guide/directory-structure/app-config#app-config-file) to provide customizable color aliases based on [Tailwind CSS colors](https://tailwindcss.com/docs/customizing-colors#color-palette-reference):
|
||||
|
||||
#vue
|
||||
Nuxt UI leverages Vite config to provide customizable color aliases based on [Tailwind CSS colors](https://tailwindcss.com/docs/customizing-colors#color-palette-reference):
|
||||
::
|
||||
|
||||
| Color | Default | Description |
|
||||
| --- | --- | --- |
|
||||
| `primary`{color="primary"} | `green` | Main brand color, used as the default color for components. |
|
||||
@@ -90,6 +96,8 @@ Nuxt UI leverages Nuxt [App Config](https://nuxt.com/docs/guide/directory-struct
|
||||
| `error`{color="error"} | `red` | Used for form error validation states. |
|
||||
| `neutral` | `slate` | Neutral color for backgrounds, text, etc. |
|
||||
|
||||
::framework-only
|
||||
#nuxt
|
||||
You can configure these color aliases at runtime in your `app.config.ts` file under the `ui.colors` key, allowing for dynamic theme customization without requiring an application rebuild:
|
||||
|
||||
```ts [app.config.ts]
|
||||
@@ -103,6 +111,30 @@ export default defineAppConfig({
|
||||
})
|
||||
```
|
||||
|
||||
#vue
|
||||
You can configure these color aliases at runtime in your `vite.config.ts` file under the `ui.colors` key:
|
||||
|
||||
```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({
|
||||
ui: {
|
||||
colors: {
|
||||
primary: 'blue',
|
||||
neutral: 'zinc'
|
||||
}
|
||||
}
|
||||
})
|
||||
]
|
||||
})
|
||||
```
|
||||
::
|
||||
|
||||
::note
|
||||
Try the :prose-icon{name="i-lucide-swatch-book" class="text-[var(--ui-primary)]"} theme picker in the header above to change `primary` and `neutral` colors.
|
||||
::
|
||||
@@ -118,8 +150,10 @@ slots:
|
||||
---
|
||||
::
|
||||
|
||||
::tip
|
||||
You can add you own dynamic color aliases in your `app.config.ts`, you just have to make sure to define them in the [`ui.theme.colors`](/getting-started/installation#themecolors) option in your `nuxt.config.ts` file.
|
||||
::framework-only
|
||||
#nuxt
|
||||
:::tip
|
||||
You can add you own dynamic color aliases in your `app.config.ts`, you just have to make sure to define them in the [`ui.theme.colors`](/getting-started/installation/nuxt#themecolors) option in your `nuxt.config.ts` file.
|
||||
|
||||
```ts [app.config.ts]
|
||||
export default defineAppConfig({
|
||||
@@ -140,7 +174,34 @@ export default defineNuxtConfig({
|
||||
}
|
||||
})
|
||||
```
|
||||
:::
|
||||
|
||||
#vue
|
||||
:::tip
|
||||
You can add you own dynamic color aliases in your `vite.config.ts`, you just have to make sure to also define them in the [`theme.colors`](/getting-started/installation/vue#themecolors) option of the `ui` plugin.
|
||||
|
||||
```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({
|
||||
ui: {
|
||||
colors: {
|
||||
tertiary: 'indigo'
|
||||
}
|
||||
},
|
||||
theme: {
|
||||
colors: ['primary', 'secondary', 'tertiary', 'info', 'success', 'warning', 'error']
|
||||
}
|
||||
})
|
||||
]
|
||||
})
|
||||
```
|
||||
:::
|
||||
::
|
||||
|
||||
::warning
|
||||
@@ -490,7 +551,19 @@ props:
|
||||
---
|
||||
::
|
||||
|
||||
The `defaultVariants` property specifies the default values for each variant. It determines how a component looks and behaves when no prop is provided. These default values can be customized in your [`app.config.ts`](#appconfigts) to adjust the standard appearance of components throughout your application.
|
||||
The `defaultVariants` property specifies the default values for each variant. It determines how a component looks and behaves when no prop is provided.
|
||||
|
||||
::framework-only
|
||||
#nuxt
|
||||
:::tip
|
||||
These default values can be customized in your [`app.config.ts`](#config) to adjust the standard appearance of components throughout your application.
|
||||
:::
|
||||
|
||||
#vue
|
||||
:::tip
|
||||
These default values can be customized in your [`vite.config.ts`](#config) to adjust the standard appearance of components throughout your application.
|
||||
:::
|
||||
::
|
||||
|
||||
## Customize theme
|
||||
|
||||
@@ -507,9 +580,11 @@ You can explore the theme for each component in two ways:
|
||||
- Browse the source code directly in the GitHub repository at https://github.com/nuxt/ui/tree/v3/src/theme.
|
||||
::
|
||||
|
||||
### `app.config.ts`
|
||||
### Config
|
||||
|
||||
You can override the theme of components inside your `app.config.ts` by using the exact same structure as the theme object.
|
||||
::framework-only
|
||||
#nuxt
|
||||
You can override the theme of components globally inside your `app.config.ts` by using the exact same structure as the theme object.
|
||||
|
||||
Let's say you want to change the font weight of all your buttons, you can do it like this:
|
||||
|
||||
@@ -525,13 +600,42 @@ export default defineAppConfig({
|
||||
})
|
||||
```
|
||||
|
||||
#vue
|
||||
You can override the theme of components globally inside your `vite.config.ts` by using the exact same structure as the theme object.
|
||||
|
||||
Let's say you want to change the font weight of all your buttons, you can do it like this:
|
||||
|
||||
```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({
|
||||
ui: {
|
||||
button: {
|
||||
slots: {
|
||||
base: 'font-bold'
|
||||
}
|
||||
}
|
||||
}
|
||||
})
|
||||
]
|
||||
})
|
||||
```
|
||||
::
|
||||
|
||||
::note
|
||||
In this example, the `font-bold` class will override the default `font-medium` class on all buttons.
|
||||
::
|
||||
|
||||
### `ui` prop
|
||||
### Props
|
||||
|
||||
You can also override a component's **slots** using the `ui` prop. This has priority over the `app.config.ts` configuration and `variants` resolution.
|
||||
#### `ui` prop
|
||||
|
||||
You can also override a component's **slots** using the `ui` prop. This has priority over the global configuration and `variants` resolution.
|
||||
|
||||
::component-code{slug="button"}
|
||||
---
|
||||
@@ -560,9 +664,9 @@ slots:
|
||||
In this example, the `trailingIcon` slot is overwritten with `size-3` even though the `md` size variant would apply a `size-5` class to it.
|
||||
::
|
||||
|
||||
### `class` prop
|
||||
#### `class` prop
|
||||
|
||||
The `class` prop allows you to override the classes of the `root` or `base` slot. This has priority over the `app.config.ts` configuration and `variants` resolution.
|
||||
The `class` prop allows you to override the classes of the `root` or `base` slot. This has priority over the global configuration and `variants` resolution.
|
||||
|
||||
::component-code{slug="button"}
|
||||
---
|
||||
|
||||
1
docs/content/1.getting-started/4.icons/.navigation.yml
Normal file
1
docs/content/1.getting-started/4.icons/.navigation.yml
Normal file
@@ -0,0 +1 @@
|
||||
shadow: true
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
title: Icons
|
||||
description: 'Nuxt UI integrates with Nuxt Icon to access over 200,000+ icons from Iconify.'
|
||||
navigation.framework: nuxt
|
||||
links:
|
||||
- label: 'Iconify'
|
||||
to: https://iconify.design/
|
||||
@@ -12,14 +13,14 @@ links:
|
||||
icon: i-simple-icons-github
|
||||
---
|
||||
|
||||
::callout{to="/getting-started/icons/vue" icon="i-logos-vue" class="hidden"}
|
||||
Looking for the **Vue** version?
|
||||
::
|
||||
|
||||
## Usage
|
||||
|
||||
Nuxt UI automatically registers the [`@nuxt/icon`](https://github.com/nuxt/icon) module for you, so there's no additional setup required.
|
||||
|
||||
::note
|
||||
You can use any name from the https://icones.js.org collection.
|
||||
::
|
||||
|
||||
### Icon Component
|
||||
|
||||
You can use the [Icon](/components/icon) component with a `name` prop to display an icon:
|
||||
@@ -32,6 +33,10 @@ props:
|
||||
---
|
||||
::
|
||||
|
||||
::note
|
||||
You can use any name from the https://icones.js.org collection.
|
||||
::
|
||||
|
||||
### Component Props
|
||||
|
||||
Some components also have an `icon` prop to display an icon, like the [Button](/components/button) for example:
|
||||
55
docs/content/1.getting-started/4.icons/2.vue.md
Normal file
55
docs/content/1.getting-started/4.icons/2.vue.md
Normal file
@@ -0,0 +1,55 @@
|
||||
---
|
||||
title: Icons
|
||||
description: 'Nuxt UI integrates with Iconify to access over 200,000+ icons.'
|
||||
navigation.framework: vue
|
||||
links:
|
||||
- label: 'Iconify'
|
||||
to: https://iconify.design/
|
||||
target: _blank
|
||||
icon: i-simple-icons-iconify
|
||||
---
|
||||
|
||||
::callout{to="/getting-started/icons/nuxt" icon="i-logos-nuxt-icon" class="hidden"}
|
||||
Looking for the **Nuxt** version?
|
||||
::
|
||||
|
||||
## Usage
|
||||
|
||||
### Icon Component
|
||||
|
||||
You can use the [Icon](/components/icon) component with a `name` prop to display an icon:
|
||||
|
||||
::component-code{slug="icon"}
|
||||
---
|
||||
props:
|
||||
name: 'i-lucide-lightbulb'
|
||||
class: 'size-5'
|
||||
---
|
||||
::
|
||||
|
||||
::note
|
||||
You can use any name from the https://icones.js.org collection.
|
||||
::
|
||||
|
||||
### Component Props
|
||||
|
||||
Some components also have an `icon` prop to display an icon, like the [Button](/components/button) for example:
|
||||
|
||||
::component-code{slug="button"}
|
||||
---
|
||||
ignore:
|
||||
- color
|
||||
- variant
|
||||
props:
|
||||
icon: i-lucide-sun
|
||||
variant: subtle
|
||||
slots:
|
||||
default: Button
|
||||
---
|
||||
::
|
||||
|
||||
## Theme
|
||||
|
||||
You can change the default icons used by Nuxt UI components in your `vite.config.ts`:
|
||||
|
||||
:icons-theme
|
||||
@@ -1,6 +1,7 @@
|
||||
---
|
||||
title: Fonts
|
||||
description: 'Nuxt UI integrates with Nuxt Fonts to provide plug-and-play font optimization.'
|
||||
navigation.framework: nuxt
|
||||
links:
|
||||
- label: 'nuxt/fonts'
|
||||
to: https://github.com/nuxt/fonts
|
||||
@@ -10,7 +11,7 @@ links:
|
||||
|
||||
## Usage
|
||||
|
||||
Nuxt UI automatically registers the [`@nuxt/fonts`](https://github.com/nuxt/fonts) module for you, so there's no additional setup required. To use a font in your Nuxt UI application, you can simply declare it in your CSS:
|
||||
Nuxt UI automatically registers the [`@nuxt/fonts`](https://github.com/nuxt/fonts) module for you, so there's no additional setup required. To use a font in your Nuxt UI application, you can simply declare it in your CSS. It will be automatically loaded and optimized for you.
|
||||
|
||||
```css [main.css]
|
||||
@import "tailwindcss";
|
||||
@@ -21,8 +22,12 @@ Nuxt UI automatically registers the [`@nuxt/fonts`](https://github.com/nuxt/font
|
||||
}
|
||||
```
|
||||
|
||||
That's it! Nuxt Fonts will detect this and you should immediately see the web font loaded in your browser.
|
||||
You can disable the `@nuxt/fonts` module with the `ui.fonts` option in your `nuxt.config.ts`:
|
||||
|
||||
::note{to="https://fonts.nuxt.com/advanced" target="_blank"}
|
||||
Read more about how `@nuxt/fonts` work behind the scenes to optimize your fonts.
|
||||
::
|
||||
```ts [nuxt.config.ts]
|
||||
export default defineNuxtConfig({
|
||||
ui: {
|
||||
fonts: false
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
@@ -1,27 +0,0 @@
|
||||
---
|
||||
title: Color Mode
|
||||
description: 'Nuxt UI integrates with Nuxt Color Mode to allow for easy switching between light and dark themes.'
|
||||
links:
|
||||
- label: 'nuxtjs/color-mode'
|
||||
to: https://github.com/nuxt-modules/color-mode
|
||||
target: _blank
|
||||
icon: i-simple-icons-github
|
||||
---
|
||||
|
||||
## Usage
|
||||
|
||||
Nuxt UI automatically registers the [`@nuxtjs/color-mode`](https://github.com/nuxt-modules/color-mode) module for you, so there's no additional setup required.
|
||||
|
||||
You can disable dark mode by setting the `preference` to `light` instead of `system` in your `nuxt.config.ts`.
|
||||
|
||||
```ts [nuxt.config.ts]
|
||||
export default defineNuxtConfig({
|
||||
colorMode: {
|
||||
preference: 'light'
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
::tip
|
||||
If you're stuck in dark mode even after changing this setting, you might need to remove the `nuxt-color-mode` entry from your browser's local storage.
|
||||
::
|
||||
@@ -0,0 +1 @@
|
||||
shadow: true
|
||||
58
docs/content/1.getting-started/6.color-mode/1.nuxt.md
Normal file
58
docs/content/1.getting-started/6.color-mode/1.nuxt.md
Normal file
@@ -0,0 +1,58 @@
|
||||
---
|
||||
title: Color Mode
|
||||
description: 'Nuxt UI integrates with Nuxt Color Mode to allow for easy switching between light and dark themes.'
|
||||
navigation.framework: nuxt
|
||||
links:
|
||||
- label: 'nuxtjs/color-mode'
|
||||
to: https://github.com/nuxt-modules/color-mode
|
||||
target: _blank
|
||||
icon: i-simple-icons-github
|
||||
---
|
||||
|
||||
::callout{to="/getting-started/color-mode/vue" icon="i-logos-vue" class="hidden"}
|
||||
Looking for the **Vue** version?
|
||||
::
|
||||
|
||||
## Usage
|
||||
|
||||
Nuxt UI automatically registers the [`@nuxtjs/color-mode`](https://github.com/nuxt-modules/color-mode) module for you, so there's no additional setup required. You can simply use the `useColorMode` composable to switch between light and dark modes:
|
||||
|
||||
```vue [ColorModeButton.vue]
|
||||
<script setup>
|
||||
const colorMode = useColorMode()
|
||||
|
||||
const isDark = computed({
|
||||
get() {
|
||||
return colorMode.value === 'dark'
|
||||
},
|
||||
set() {
|
||||
colorMode.preference = colorMode.value === 'dark' ? 'light' : 'dark'
|
||||
}
|
||||
})
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<ClientOnly v-if="!colorMode?.forced">
|
||||
<UButton
|
||||
:icon="isDark ? 'i-lucide-moon' : 'i-lucide-sun'"
|
||||
color="neutral"
|
||||
variant="ghost"
|
||||
@click="isDark = !isDark"
|
||||
/>
|
||||
|
||||
<template #fallback>
|
||||
<div class="size-8" />
|
||||
</template>
|
||||
</ClientOnly>
|
||||
</template>
|
||||
```
|
||||
|
||||
You can disable the `@nuxtjs/color-mode` module with the `ui.colorMode` option in your `nuxt.config.ts`:
|
||||
|
||||
```ts [nuxt.config.ts]
|
||||
export default defineNuxtConfig({
|
||||
ui: {
|
||||
colorMode: false
|
||||
}
|
||||
})
|
||||
```
|
||||
47
docs/content/1.getting-started/6.color-mode/2.vue.md
Normal file
47
docs/content/1.getting-started/6.color-mode/2.vue.md
Normal file
@@ -0,0 +1,47 @@
|
||||
---
|
||||
title: Color Mode
|
||||
description: 'Nuxt UI integrates with VueUse to allow for easy switching between light and dark themes.'
|
||||
navigation.framework: vue
|
||||
---
|
||||
|
||||
::callout{to="/getting-started/color-mode/nuxt" icon="i-logos-nuxt-icon" class="hidden"}
|
||||
Looking for the **Nuxt** version?
|
||||
::
|
||||
|
||||
## Usage
|
||||
|
||||
Nuxt UI automatically registers the [useDark](https://vueuse.org/core/useDark) composable as a Vue plugin, so there's no additional setup required. You can simply use it to switch between light and dark modes:
|
||||
|
||||
```vue [ColorModeButton.vue]
|
||||
<script setup>
|
||||
import { useColorMode } from '@vueuse/core'
|
||||
|
||||
const mode = useColorMode()
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<UButton
|
||||
:icon="mode === 'dark' ? 'i-lucide-moon' : 'i-lucide-sun'"
|
||||
color="neutral"
|
||||
variant="ghost"
|
||||
@click="mode = mode === 'dark' ? 'light' : 'dark'"
|
||||
/>
|
||||
</template>
|
||||
```
|
||||
|
||||
You can disable this plugin with the `colorMode` option in your `vite.config.ts`:
|
||||
|
||||
```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({
|
||||
colorMode: false
|
||||
})
|
||||
]
|
||||
})
|
||||
```
|
||||
@@ -1 +1,2 @@
|
||||
badge: New
|
||||
shadow: true
|
||||
|
||||
@@ -1,20 +1,17 @@
|
||||
---
|
||||
title: Internationalization (i18n) in a Nuxt app
|
||||
title: Internationalization (i18n)
|
||||
description: 'Learn how to internationalize your Nuxt app with multi-directional support (LTR/RTL).'
|
||||
select:
|
||||
items:
|
||||
- label: Nuxt
|
||||
icon: i-logos-nuxt-icon
|
||||
to: /getting-started/i18n/nuxt
|
||||
- label: Vue
|
||||
icon: i-logos-vue
|
||||
to: /getting-started/i18n/vue
|
||||
navigation.framework: nuxt
|
||||
---
|
||||
|
||||
::callout{to="/getting-started/i18n/vue" icon="i-logos-vue" class="hidden"}
|
||||
Looking for the **Vue** version?
|
||||
::
|
||||
|
||||
## Usage
|
||||
|
||||
::note{to="/components/app"}
|
||||
Nuxt UI provides an [App](/components/app) component that wraps your app to provide global configurations.
|
||||
Nuxt UI provides an **App** component that wraps your app to provide global configurations.
|
||||
::
|
||||
|
||||
### Locale
|
||||
|
||||
@@ -1,20 +1,17 @@
|
||||
---
|
||||
title: Internationalization (i18n) in a Vue app
|
||||
title: Internationalization (i18n)
|
||||
description: 'Learn how to internationalize your Vue app with multi-directional support (LTR/RTL).'
|
||||
select:
|
||||
items:
|
||||
- label: Nuxt
|
||||
icon: i-logos-nuxt-icon
|
||||
to: /getting-started/i18n/nuxt
|
||||
- label: Vue
|
||||
icon: i-logos-vue
|
||||
to: /getting-started/i18n/vue
|
||||
navigation.framework: vue
|
||||
---
|
||||
|
||||
::callout{to="/getting-started/i18n/nuxt" icon="i-logos-nuxt-icon" class="hidden"}
|
||||
Looking for the **Nuxt** version?
|
||||
::
|
||||
|
||||
## Usage
|
||||
|
||||
::note{to="/components/app"}
|
||||
Nuxt UI provides an [App](/components/app) component that wraps your app to provide global configurations.
|
||||
Nuxt UI provides an **App** component that wraps your app to provide global configurations.
|
||||
::
|
||||
|
||||
### Locale
|
||||
|
||||
Reference in New Issue
Block a user