# Instalação

> \[!NOTE]
> See: /docs/getting-started/installation/vue
>
> Procurando pela versão **Vue**?

## Configuração

### Adicionar a um projeto Nuxt

#### Instale o pacote do Nitro UI

```bash [pnpm]
pnpm add @nitro/ui tailwindcss
```

```bash [yarn]
yarn add @nitro/ui tailwindcss
```

```bash [npm]
npm install @nitro/ui tailwindcss
```

```bash [bun]
bun add @nitro/ui tailwindcss
```

#### Adicione o módulo do Nitro UI no seu `nuxt.config.ts`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nitro/ui']
})
```

> \[!NOTE]
>
> Não é necessário adicionar `@nuxt/icon`, `@nuxt/fonts` ou `@nuxtjs/color-mode` ao seu array `modules`, pois o Nitro UI os registra automaticamente. Você ainda pode configurar esses módulos no seu `nuxt.config.ts` usando as chaves `icon`, `fonts` e `colorMode`.

#### Importe o Tailwind CSS e o Nitro UI no seu CSS

```css [app/assets/css/main.css]
@import "tailwindcss";
@import "@nitro/ui";
```

```ts [nuxt.config.ts] {3}
export default defineNuxtConfig({
  modules: ['@nitro/ui'],
  css: ['~/assets/css/main.css']
})
```

> \[!TIP]
> See: https\://nuxt.com/docs/getting-started/layers
>
> Ao usar [Nuxt Layers](https://nuxt.com/docs/getting-started/layers){rel=""nofollow""}, o módulo gera automaticamente diretivas [`@source`](https://tailwindcss.com/docs/functions-and-directives#source-directive){rel=""nofollow""} para cada diretório de layer, garantindo que o Tailwind CSS escaneie todos os arquivos-fonte dos seus layers em busca de classes utilitárias.

> \[!NOTE]
>
> É recomendado instalar a extensão [Tailwind CSS IntelliSense](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss){rel=""nofollow""} para o VSCode e adicionar as seguintes configurações:
>
> ```json [.vscode/settings.json]
> {
>   "files.associations": {
>     "*.css": "tailwindcss"
>   },
>   "editor.quickSuggestions": {
>     "strings": "on"
>   },
>   "tailwindCSS.classAttributes": ["class", "ui"],
>   "tailwindCSS.classFunctions": ["defineAppConfig"]
> }
> ```

#### Envolva o seu app com o componente App

```vue [app.vue]
<template>
  <NApp>
    <NuxtPage />
  </NApp>
</template>
```

> \[!NOTE]
> See: /docs/components/app
>
> O componente `App` fornece configurações globais e é necessário para que os componentes **Toast** e **Tooltip** funcionem, assim como os **overlays programáticos**.

### Usar um template Nuxt

Comece com um dos nossos templates oficiais usando o botão `Use this template` no GitHub ou a CLI:

```bash [Starter]
npm create nuxt@latest -- -t ui
```

```bash [Landing]
npm create nuxt@latest -- -t ui/landing
```

```bash [Docs]
npm create nuxt@latest -- -t ui/docs
```

```bash [SaaS]
npm create nuxt@latest -- -t ui/saas
```

```bash [Dashboard]
npm create nuxt@latest -- -t ui/dashboard
```

```bash [Chat]
npm create nuxt@latest -- -t ui/chat
```

```bash [Portfolio]
npm create nuxt@latest -- -t ui/portfolio
```

```bash [Changelog]
npm create nuxt@latest -- -t ui/changelog
```

```bash [Editor]
npm create nuxt@latest -- -t ui/editor
```

## Opções

Você pode personalizar o Nitro UI fornecendo opções no seu `nuxt.config.ts`.

### `prefix`

Use a opção `prefix` para alterar o prefixo dos componentes.

- Default: `N`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

```ts [nuxt.config.ts] {4-6}
export default defineNuxtConfig({
  modules: ['@nitro/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    prefix: 'Nuxt'
  }
})
```

### `fonts`

Use a opção `fonts` para habilitar ou desabilitar o módulo [`@nuxt/fonts`](https://github.com/nuxt/fonts){rel="&#x22;nofollow&#x22;"}.

- Default: `true`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

```ts [nuxt.config.ts] {4-6}
export default defineNuxtConfig({
  modules: ['@nitro/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    fonts: false
  }
})
```

### `colorMode`

Use a opção `colorMode` para habilitar ou desabilitar o módulo [`@nuxt/color-mode`](https://github.com/nuxt-modules/color-mode){rel="&#x22;nofollow&#x22;"}.

- Default: `true`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

```ts [nuxt.config.ts] {4-6}
export default defineNuxtConfig({
  modules: ['@nitro/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    colorMode: false
  }
})
```

### `theme.colors`

Use a opção `theme.colors` para definir os aliases de cor dinâmicos usados para gerar o tema dos componentes.

- Default: `['primary', 'secondary', 'success', 'info', 'warning', 'error']`{.inline,language-ts-type,shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

```ts [nuxt.config.ts] {4-8}
export default defineNuxtConfig({
  modules: ['@nitro/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    theme: {
      colors: ['primary', 'error']
    }
  }
})
```

> \[!TIP]
> See: /docs/getting-started/theme/design-system#colors
>
> Saiba mais sobre personalização de cores e tematização na seção Tema.

### `theme.transitions`

Use a opção `theme.transitions` para habilitar ou desabilitar as transições nos componentes.

- Default: `true`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

```ts [nuxt.config.ts] {4-8}
export default defineNuxtConfig({
  modules: ['@nitro/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    theme: {
      transitions: false
    }
  }
})
```

> \[!NOTE]
>
> Essa opção adiciona a classe `transition-colors` nos componentes com estados de hover ou ativo.

### `theme.unstyled` `4.9+`

Use a opção `theme.unstyled` para remover todas as classes de tema padrão dos componentes, mantendo apenas sua estrutura e as classes que você fornece por meio de `class`, `ui` ou `app.config.ui`.

- Default: `false`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

```ts [nuxt.config.ts] {4-8}
export default defineNuxtConfig({
  modules: ['@nitro/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    theme: {
      unstyled: true
    }
  }
})
```

> \[!WARNING]
>
> Isso também remove classes **estruturais** (posicionamento, transições, flex/grid), não apenas as cosméticas. Componentes com muito layout, como `Modal`, `Drawer` ou `Calendar`, exigirão que você forneça novamente o layout deles, semelhante ao modo unstyled do PrimeVue.

### `theme.defaultVariants`

Use a opção `theme.defaultVariants` para sobrescrever as variantes `color` e `size` padrão dos componentes.

- Default: `{ color: 'primary', size: 'md' }`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

```ts [nuxt.config.ts] {4-11}
export default defineNuxtConfig({
  modules: ['@nitro/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    theme: {
      defaultVariants: {
        color: 'neutral',
        size: 'sm'
      }
    }
  }
})
```

### `theme.prefix` `4.2+`

Use a opção `theme.prefix` para configurar o mesmo prefixo que você definiu na importação do Tailwind CSS. Isso garante que os componentes do Nitro UI usem as classes utilitárias e variáveis CSS com o prefixo correto.

```ts [nuxt.config.ts] {4-8}
export default defineNuxtConfig({
  modules: ['@nitro/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    theme: {
      prefix: 'tw'
    }
  }
})
```

```css [app/assets/css/main.css] {1}
@import "tailwindcss" prefix(tw);
@import "@nitro/ui";
```

> \[!WARNING]
> See: https\://fonts.nuxt.com/get-started/configuration#processcssvariables
>
> Você pode precisar habilitar `fonts.processCSSVariables` para usar a opção de prefixo com o módulo `@nuxt/fonts`:
>
> ```ts [nuxt.config.ts] {9-11}
> export default defineNuxtConfig({
>   modules: ['@nitro/ui'],
>   css: ['~/assets/css/main.css'],
>   ui: {
>     theme: {
>       prefix: 'tw'
>     }
>   },
>   fonts: {
>     processCSSVariables: true
>   }
> })
> ```

Isso adicionará automaticamente o prefixo a todas as classes utilitárias do Tailwind e variáveis CSS nos temas dos componentes do Nitro UI:

```html
<!-- Without prefix -->
<button class="px-2 py-1 text-xs hover:bg-primary/75">Button</button>

<!-- With prefix: tw -->
<button class="tw:px-2 tw:py-1 tw:text-xs tw:hover:bg-primary/75">Button</button>
```

> \[!NOTE]
> See: https\://tailwindcss.com/docs/styling-with-utility-classes#using-the-prefix-option
>
> Saiba mais sobre o uso de um prefixo na documentação do Tailwind CSS.

### `prose`

Use a opção `prose` para forçar a importação dos [componentes `Prose`](https://ui.nitro.news/docs/typography) do Nitro UI mesmo que o `@nuxtjs/mdc` ou o `@nuxt/content` não estejam instalados.

- Default: `false`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

```ts [nuxt.config.ts] {4-6}
export default defineNuxtConfig({
  modules: ['@nitro/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    prose: true
  }
})
```

### `mdc` `Deprecated`

Use a opção [`prose`](https://ui.nitro.news/#prose).

### `content`

Use a opção `content` para forçar a importação dos componentes `<Prose>` e `<NContent>` do Nitro UI mesmo que o `@nuxt/content` não esteja instalado.

- Default: `false`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

```ts [nuxt.config.ts] {4-6}
export default defineNuxtConfig({
  modules: ['@nitro/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    content: true
  }
})
```

### `experimental.componentDetection` `4.1+`

Use a opção `experimental.componentDetection` para habilitar a detecção automática de componentes para tree-shaking. Esse recurso escaneia seu código-fonte para detectar quais componentes são realmente usados e gera apenas o CSS necessário para esses componentes (incluindo suas dependências).

- Default: `false`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- Type: `boolean | string[]`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

**Enable automatic detection:**

```ts [nuxt.config.ts] {4-8}
export default defineNuxtConfig({
  modules: ['@nitro/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    experimental: {
      componentDetection: true
    }
  }
})
```

**Include additional components for dynamic usage:**

```ts [nuxt.config.ts] {4-8}
export default defineNuxtConfig({
  modules: ['@nitro/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    experimental: {
      componentDetection: ['Modal', 'Dropdown', 'Popover']
    }
  }
})
```

> \[!NOTE]
>
> Ao fornecer um array de nomes de componentes, a detecção automática é habilitada e esses componentes (junto com suas dependências) têm inclusão garantida. Isso é útil para componentes dinâmicos como `<component :is="..." />` que não podem ser analisados estaticamente.

## Lançamentos contínuos

O Nitro UI usa o [pkg.pr.new](https://github.com/stackblitz-labs/pkg.pr.new){rel="&#x22;nofollow&#x22;"} para lançamentos de preview contínuos, dando aos desenvolvedores acesso instantâneo aos recursos mais recentes e correções de bugs sem esperar pelos lançamentos oficiais.

Lançamentos de preview automáticos são criados para todos os commits e PRs na branch `v4`. Use-os substituindo a versão do seu pacote pelo hash específico do commit ou pelo número do PR.

```diff [package.json]
{
  "dependencies": {
-   "@nitro/ui": "^4.0.0",
+   "@nitro/ui": "https://pkg.pr.new/@nitro/ui@4c96909",
  }
}
```

> \[!NOTE]
>
> **pkg.pr.new** will automatically comment on PRs with the installation URL, making it easy to test changes.


# Instalação

> \[!NOTE]
> See: /docs/getting-started/installation/nuxt
>
> Procurando pela versão **Nuxt**?

## Configuração

### Adicionar a um projeto Vue

#### Instale o pacote do Nitro UI

```bash [pnpm]
pnpm add @nitro/ui tailwindcss
```

```bash [yarn]
yarn add @nitro/ui tailwindcss
```

```bash [npm]
npm install @nitro/ui tailwindcss
```

```bash [bun]
bun add @nitro/ui tailwindcss
```

#### Adicione o plugin Vite do Nitro UI no seu `vite.config.ts`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

```ts [vite.config.ts (Vite)] {3,8}
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nitro/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui()
  ]
})
```

```ts [vite.config.ts (Laravel Inertia)] {3,20-22}
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nitro/ui/vite'
import laravel from 'laravel-vite-plugin'

export default defineConfig({
  plugins: [
    laravel({
      input: ['resources/js/app.ts'],
      refresh: true
    }),
    vue({
      template: {
        transformAssetUrls: {
          base: null,
          includeAbsolute: false
        }
      }
    }),
    ui({
      router: 'inertia'
    })
  ]
})
```

```ts [vite.config.ts (AdonisJS Inertia)] {3,15-17}
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nitro/ui/vite'
import adonisjs from '@adonisjs/vite/client'
import inertia from '@adonisjs/inertia/client'

export default defineConfig({
  plugins: [
    adonisjs({
      entrypoints: ['inertia/app/app.ts'],
      reload: ['resources/views/**/*.edge']
    }),
    inertia(),
    vue(),
    ui({
      router: 'inertia'
    })
  ]
})
```

> \[!TIP]
>
> O Nitro UI registra o `unplugin-auto-import` e o `unplugin-vue-components`, que geram os arquivos de declaração de tipos `auto-imports.d.ts` e `components.d.ts`. Você provavelmente vai querer colocá-los no gitignore e adicioná-los ao seu `tsconfig`.
>
> ```json [tsconfig.app.json]
> {
>   "include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.vue", "auto-imports.d.ts", "components.d.ts"]
> }
> ```
>
> ```bash [.gitignore]
> # Auto-generated type declarations
> auto-imports.d.ts
> components.d.ts
> ```

> \[!TIP]
>
> Internamente, o Nitro UI depende de um alias personalizado para resolver os tipos do tema. Se você usa TypeScript, deve adicionar um alias ao seu `tsconfig` para habilitar o autocompletar no seu `vite.config.ts`.
>
> ```json [tsconfig.node.json]
> {
>   "compilerOptions": {
>     "paths": {
>       "#build/ui": [
>         "./node_modules/.nuxt-ui/ui"
>       ]
>     }
>   }
> }
> ```
>
> ```json [tsconfig.app.json]
> {
>   "compilerOptions": {
>     "paths": {
>       "#build/ui/*": [
>         "./node_modules/.nuxt-ui/ui/*"
>       ]
>     }
>   }
> }
> ```

#### Use o plugin Vue do Nitro UI

```ts [src/main.ts (Vite)] {3,14}
import { createApp } from 'vue'
import { createRouter, createWebHistory } from 'vue-router'
import ui from '@nitro/ui/vue-plugin'
import App from './App.vue'

const app = createApp(App)

const router = createRouter({
  routes: [],
  history: createWebHistory()
})

app.use(router)
app.use(ui)

app.mount('#app')
```

```ts [resources/js/app.ts (Laravel Inertia)] {3,19}
import type { DefineComponent } from 'vue'
import { createInertiaApp } from '@inertiajs/vue3'
import ui from '@nitro/ui/vue-plugin'
import { resolvePageComponent } from 'laravel-vite-plugin/inertia-helpers'
import { createApp, h } from 'vue'

const appName = import.meta.env.VITE_APP_NAME || 'Laravel x Nitro UI'

createInertiaApp({
  title: title => (title ? `${title} - ${appName}` : appName),
  resolve: name =>
    resolvePageComponent(
      `./pages/${name}.vue`,
      import.meta.glob<DefineComponent>('./pages/**/*.vue')
    ),
  setup({ el, App, props, plugin }) {
    createApp({ render: () => h(App, props) })
      .use(plugin)
      .use(ui)
      .mount(el)
  }
})
```

```ts [inertia/app/app.ts (AdonisJS Inertia)] {3,19}
import type { DefineComponent } from 'vue'
import { createInertiaApp } from '@inertiajs/vue3'
import ui from '@nitro/ui/vue-plugin'
import { resolvePageComponent } from '@adonisjs/inertia/helpers'
import { createApp, h } from 'vue'

const appName = import.meta.env.VITE_APP_NAME || 'AdonisJS x Nitro UI'

createInertiaApp({
  title: title => (title ? `${title} - ${appName}` : appName),
  resolve: name =>
    resolvePageComponent(
      `../pages/${name}.vue`,
      import.meta.glob<DefineComponent>('../pages/**/*.vue')
    ),
  setup({ el, App, props, plugin }) {
    createApp({ render: () => h(App, props) })
      .use(plugin)
      .use(ui)
      .mount(el)
  }
})
```

#### Importe o Tailwind CSS e o Nitro UI no seu CSS

```css [src/assets/css/main.css (Vite)]
@import "tailwindcss";
@import "@nitro/ui";
```

```css [resources/css/app.css (Laravel Inertia)]
@import "tailwindcss";
@import "@nitro/ui";
```

```css [inertia/css/app.css (AdonisJS Inertia)]
@import "tailwindcss";
@import "@nitro/ui";
```

> \[!TIP]
>
> Importe o arquivo CSS no seu ponto de entrada.
>
> ```ts [src/main.ts] {1}
> import './assets/css/main.css'
>
> import { createApp } from 'vue'
> import { createRouter, createWebHistory } from 'vue-router'
> import ui from '@nitro/ui/vue-plugin'
> import App from './App.vue'
>
> const app = createApp(App)
>
> const router = createRouter({
>   routes: [],
>   history: createWebHistory()
> })
>
> app.use(router)
> app.use(ui)
>
> app.mount('#app')
> ```
>
> ```ts [resources/js/app.ts (Laravel Inertia)] {1}
> import '../css/app.css'
> import type { DefineComponent } from 'vue'
> import { createInertiaApp } from '@inertiajs/vue3'
> import ui from '@nitro/ui/vue-plugin'
> import { resolvePageComponent } from 'laravel-vite-plugin/inertia-helpers'
> import { createApp, h } from 'vue'
>
> const appName = import.meta.env.VITE_APP_NAME || 'Laravel x Nitro UI'
>
> createInertiaApp({
>   title: title => (title ? `${title} - ${appName}` : appName),
>   resolve: name =>
>     resolvePageComponent(
>       `./pages/${name}.vue`,
>       import.meta.glob<DefineComponent>('./pages/**/*.vue')
>     ),
>   setup({ el, App, props, plugin }) {
>     createApp({ render: () => h(App, props) })
>       .use(plugin)
>       .use(ui)
>       .mount(el)
>   }
> })
> ```
>
> ```ts [inertia/app/app.ts (AdonisJS Inertia)] {1}
> import '../css/app.css'
> import type { DefineComponent } from 'vue'
> import { createInertiaApp } from '@inertiajs/vue3'
> import ui from '@nitro/ui/vue-plugin'
> import { resolvePageComponent } from '@adonisjs/inertia/helpers'
> import { createApp, h } from 'vue'
>
> const appName = import.meta.env.VITE_APP_NAME || 'AdonisJS x Nitro UI'
>
> createInertiaApp({
>   title: title => (title ? `${title} - ${appName}` : appName),
>   resolve: name =>
>     resolvePageComponent(
>       `../pages/${name}.vue`,
>       import.meta.glob<DefineComponent>('../pages/**/*.vue')
>     ),
>   setup({ el, App, props, plugin }) {
>     createApp({ render: () => h(App, props) })
>       .use(plugin)
>       .use(ui)
>       .mount(el)
>   }
> })
> ```

> \[!NOTE]
>
> É recomendado instalar a extensão [Tailwind CSS IntelliSense](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss){rel="&#x22;nofollow&#x22;"} para o VSCode e adicionar as seguintes configurações:
>
> ```json [.vscode/settings.json]
> {
>   "files.associations": {
>     "*.css": "tailwindcss"
>   },
>   "editor.quickSuggestions": {
>     "strings": "on"
>   },
>   "tailwindCSS.classAttributes": ["class", "ui"],
>   "tailwindCSS.classFunctions": ["defineAppConfig"]
> }
> ```

#### Envolva o seu app com o componente App

```vue [src/App.vue (Vite)]
<template>
  <NApp>
    <RouterView />
  </NApp>
</template>
```

```vue [resources/js/pages/index.vue (Laravel Inertia)]
<template>
  <NApp>
    <!-- Your content goes here -->
  </NApp>
</template>
```

```vue [inertia/pages/index.vue (AdonisJS Inertia)]
<template>
  <NApp>
    <!-- Your content goes here -->
  </NApp>
</template>
```

> \[!NOTE]
> See: /docs/components/app
>
> O componente `App` configura o config global e é necessário para **Toast**, **Tooltip** e **overlays programáticos**.

#### Adicione a classe `isolate` ao seu container raiz

```html [index.html (Vite)] {9}
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Nitro UI</title>
  </head>
  <body>
    <div id="app" class="isolate"></div>
    <script type="module" src="/src/main.ts"></script>
  </body>
</html>
```

```blade [resources/views/app.blade.php (Laravel Inertia)] {10}
<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1">
    @inertiaHead
    @vite('resources/js/app.ts')
  </head>
  <body>
    <div class="isolate">
        @inertia
    </div>
  </body>
</html>
```

```edge [resources/views/inertia_layout.edge (AdonisJS Inertia)] {10}
<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1">
    @inertiaHead()
    @vite(['inertia/app/app.ts', `inertia/pages/${page.component}.vue`])
  </head>
  <body>
    @inertia({ class: 'isolate' })
  </body>
</html>
```

> \[!NOTE]
>
> Isso garante que os estilos fiquem restritos ao seu app e evita problemas com overlays e contextos de empilhamento.

## Opções

Você pode personalizar o Nitro UI fornecendo opções no seu `vite.config.ts`.

### `prefix`

Use a opção `prefix` para alterar o prefixo dos componentes.

- Default: `N`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

```ts [vite.config.ts] {9}
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nitro/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      prefix: 'Nuxt'
    })
  ]
})
```

### `ui`

Use a opção `ui` para fornecer a configuração do Nitro UI.

```ts [vite.config.ts] {9-14}
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nitro/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      ui: {
        colors: {
          primary: 'green',
          neutral: 'slate'
        }
      }
    })
  ]
})
```

### `colorMode`

Use a opção `colorMode` para habilitar ou desabilitar a integração de modo de cor do `@vueuse/core`.

- Default: `true`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

```ts [vite.config.ts] {9}
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nitro/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      colorMode: false
    })
  ]
})
```

### `theme.colors`

Use a opção `theme.colors` para definir os aliases de cor dinâmicos usados para gerar o tema dos componentes.

- Default: `['primary', 'secondary', 'success', 'info', 'warning', 'error']`{.inline,language-ts-type,shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

```ts [vite.config.ts] {9-11}
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nitro/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      theme: {
        colors: ['primary', 'error']
      }
    })
  ]
})
```

> \[!TIP]
> See: /docs/getting-started/theme/design-system#colors
>
> Saiba mais sobre personalização de cores e tematização na seção Tema.

### `theme.transitions`

Use a opção `theme.transitions` para habilitar ou desabilitar as transições nos componentes.

- Default: `true`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

```ts [vite.config.ts] {9-11}
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nitro/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      theme: {
        transitions: false
      }
    })
  ]
})
```

> \[!NOTE]
>
> Essa opção adiciona a classe `transition-colors` nos componentes com estados de hover ou ativo.

### `theme.unstyled` `4.9+`

Use a opção `theme.unstyled` para remover todas as classes de tema padrão dos componentes, mantendo apenas sua estrutura e as classes que você fornece por meio de `class`, `ui` ou `app.config.ui`.

- Default: `false`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

```ts [vite.config.ts] {9-11}
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nitro/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      theme: {
        unstyled: true
      }
    })
  ]
})
```

> \[!WARNING]
>
> Isso também remove classes **estruturais** (posicionamento, transições, flex/grid), não apenas as cosméticas. Componentes com muito layout, como `Modal`, `Drawer` ou `Calendar`, exigirão que você forneça novamente o layout deles, semelhante ao modo unstyled do PrimeVue.

### `theme.defaultVariants`

Use a opção `theme.defaultVariants` para sobrescrever as variantes `color` e `size` padrão dos componentes.

- Default: `{ color: 'primary', size: 'md' }`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

```ts [vite.config.ts] {9-14}
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nitro/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      theme: {
        defaultVariants: {
          color: 'neutral',
          size: 'sm'
        }
      }
    })
  ]
})
```

### `theme.prefix` `4.2+`

Use a opção `theme.prefix` para configurar o mesmo prefixo que você definiu na importação do Tailwind CSS. Isso garante que os componentes do Nitro UI usem as classes utilitárias e variáveis CSS com o prefixo correto.

```ts [vite.config.ts] {9-11}
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nitro/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      theme: {
        prefix: 'tw'
      }
    })
  ]
})
```

```css [src/assets/css/main.css] {1}
@import "tailwindcss" prefix(tw);
@import "@nitro/ui";
```

Isso adicionará automaticamente o prefixo a todas as classes utilitárias do Tailwind e variáveis CSS nos temas dos componentes do Nitro UI:

```html
<!-- Without prefix -->
<button class="px-2 py-1 text-xs hover:bg-primary/75">Button</button>

<!-- With prefix: tw -->
<button class="tw:px-2 tw:py-1 tw:text-xs tw:hover:bg-primary/75">Button</button>
```

> \[!NOTE]
> See: https\://tailwindcss.com/docs/styling-with-utility-classes#using-the-prefix-option
>
> Saiba mais sobre o uso de um prefixo na documentação do Tailwind CSS.

### `prose`

Use a opção `prose` para habilitar os [componentes `Prose`](https://ui.nitro.news/docs/typography) do Nitro UI e o tema deles.

- Default: `false`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

```ts [vite.config.ts] {9}
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nitro/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      prose: true
    })
  ]
})
```

### `autoImport`

Use a opção `autoImport` para desabilitar a importação automática de composables ou para personalizar as opções do [`unplugin-auto-import`](https://github.com/unplugin/unplugin-auto-import){rel="&#x22;nofollow&#x22;"}.

- Default: `{}`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

```ts [vite.config.ts] {9}
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nitro/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      autoImport: false
    })
  ]
})
```

> \[!NOTE]
>
> Quando desabilitado, você ainda pode importar composables explicitamente de `@nitro/ui/composables`.

### `components`

Use a opção `components` para desabilitar a importação automática de componentes ou para personalizar as opções do [`unplugin-vue-components`](https://github.com/unplugin/unplugin-vue-components){rel="&#x22;nofollow&#x22;"}.

- Default: `{}`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

```ts [vite.config.ts] {9}
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nitro/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      components: false
    })
  ]
})
```

> \[!NOTE]
>
> Quando desabilitado, você ainda pode importar componentes explicitamente, ex.: `import Button from '@nitro/ui/components/Button.vue'` ou `import ProseCode from '@nitro/ui/components/prose/Code.vue'`.

### `router` `4.3+`

Use a opção `router` para configurar a integração de roteamento. Isso é útil para aplicações que não usam `vue-router`, como apps Electron, MPAs ou frameworks como [Inertia.js](https://inertiajs.com/){rel="&#x22;nofollow&#x22;"} ou [Hybridly](https://hybridly.dev/){rel="&#x22;nofollow&#x22;"}.

- Default: `true`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

| Value                                                                                                                           | Description                                                     |
| ------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| `true`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"}      | Uses `vue-router` for navigation with `RouterLink` component.   |
| `false`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"}     | Disables routing integration, links render as plain `<a>` tags. |
| `'inertia'`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | Uses Inertia.js for navigation with its `Link` component.       |

```ts [vite.config.ts] {9}
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nitro/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      router: false
    })
  ]
})
```

> \[!TIP]
>
> Você pode fornecer uma lógica de navegação personalizada para frameworks como o **Hybridly** definindo `router: false` na configuração do Vite e passando uma função ao instalar o plugin do Vue:
>
> ```ts [src/main.ts]
> import ui from '@nitro/ui/vue-plugin'
> import { router } from 'hybridly'
>
> app.use(ui, {
>   router: (event, { href, external }) => {
>     if (external) {
>       return
>     }
>
>     event.preventDefault()
>
>     router.navigate({ url: href })
>   }
> })
> ```

> \[!NOTE]
>
> Quando definido como `false` ou `'inertia'`, o `vue-router` não é necessário como dependência.

### `scanPackages` `4.3+`

Use a opção `scanPackages` para especificar pacotes npm adicionais que devem ser escaneados em busca de componentes que usam o Nitro UI. Isso é útil quando você tem uma biblioteca de componentes compartilhada que usa componentes do Nitro UI internamente.

```ts [vite.config.ts] {9}
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nitro/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      scanPackages: ['@my-org/ui-components']
    })
  ]
})
```

> \[!NOTE]
>
> Por padrão, apenas o `@nitro/ui` é escaneado. Use esta opção quando seus pacotes externos contiverem componentes Vue que usam o Nitro UI.

### `root` `4.9+`

Use a opção `root` para sobrescrever o diretório onde o Nitro UI gera seu diretório `.nuxt-ui` (que contém os templates do tema). Por padrão, ele usa o `root` do Vite, mas em configurações como [`electron-vite`](https://electron-vite.org/){rel="&#x22;nofollow&#x22;"} o `root` do renderer aponta para um subdiretório (ex.: `src/renderer`), então os templates acabam em `src/renderer/node_modules/.nuxt-ui`, onde o Tailwind não os escaneia, fazendo com que classes de tema como `bg-default`, `ring-default` e `divide-default` fiquem ausentes.

```ts [electron.vite.config.ts] {12}
import { defineConfig } from 'electron-vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nitro/ui/vite'

export default defineConfig({
  renderer: {
    root: 'src/renderer',
    plugins: [
      vue(),
      ui({
        root: __dirname
      })
    ]
  }
})
```

> \[!NOTE]
>
> Aponte o `root` para a raiz do seu projeto para que o diretório `.nuxt-ui` gerado fique em um `node_modules` que o Tailwind escaneia.

## Lançamentos contínuos

O Nitro UI usa o [pkg.pr.new](https://github.com/stackblitz-labs/pkg.pr.new){rel="&#x22;nofollow&#x22;"} para lançamentos de preview contínuos, dando aos desenvolvedores acesso instantâneo aos recursos mais recentes e correções de bugs sem esperar pelos lançamentos oficiais.

Lançamentos de preview automáticos são criados para todos os commits e PRs na branch `v4`. Use-os substituindo a versão do seu pacote pelo hash específico do commit ou pelo número do PR.

```diff [package.json]
{
  "dependencies": {
-   "@nitro/ui": "^4.0.0",
+   "@nitro/ui": "https://pkg.pr.new/@nitro/ui@4c96909",
  }
}
```

> \[!NOTE]
>
> **pkg.pr.new** will automatically comment on PRs with the installation URL, making it easy to test changes.


# Introdução

## O que é o Nitro UI?

Uma biblioteca moderna de componentes de UI para Vue, construída sobre [Reka UI](https://reka-ui.com/){rel="&#x22;nofollow&#x22;"}, [Tailwind CSS](https://tailwindcss.com/){rel="&#x22;nofollow&#x22;"} e [Tailwind Variants](https://www.tailwind-variants.org/){rel="&#x22;nofollow&#x22;"} para entregar aplicações bonitas e acessíveis com mais de 125 componentes prontos para produção. Funciona com Nuxt e com apps Vue puros (Vite, Inertia, SSR).

Se você está construindo um projeto Vue com Tailwind CSS, o Nitro UI é uma ótima escolha padrão. Ele oferece componentes de alto nível e prontos para uso (tabelas de dados, formulários, overlays, navegação) e ainda permite personalização avançada quando necessário.

**Experiência do desenvolvedor em primeiro lugar**

Intuitive APIs, excellent TypeScript support, auto-completion, and comprehensive docs.

**Bonito por padrão**

Um design moderno e limpo por padrão, com um tema que você pode adaptar em minutos.

**Acessível por padrão**

Compatível com WAI-ARIA, com navegação por teclado, gerenciamento de foco e suporte a leitores de tela.

**Pronto para produção**

Mais de 125 componentes testados em produção, incluindo tabelas de dados, formulários, overlays e navegação, usados por milhares de aplicações.

## Tecnologias principais

### Reka UI

O Nitro UI é construído sobre o [Reka UI](https://reka-ui.com/){rel="&#x22;nofollow&#x22;"} como base para os componentes:

- **WAI-ARIA Compliance**: Follows [WAI-ARIA authoring practices](https://reka-ui.com/docs/overview/accessibility){rel="&#x22;nofollow&#x22;"} with proper semantics and roles
- **Keyboard Navigation**: Built-in keyboard support for complex components like tabs and dialogs
- **Focus Management**: Intelligent focus handling that moves focus based on user interactions
- **Accessible Labels**: Abstractions to simplify labeling controls for screen readers

### Tailwind CSS

Nitro UI integrates the latest [Tailwind CSS](https://tailwindcss.com/){rel="&#x22;nofollow&#x22;"}, bringing significant improvements:

- **5x Faster Builds**: Full builds up to 5x faster, incremental builds over 100x faster
- **Unified Toolchain**: Built-in import handling, vendor prefixing, and syntax transforms
- **CSS-first Configuration**: Customize and extend directly in CSS instead of JavaScript
- **Modern Web Features**: Container queries, cascade layers, wide-gamut colors, and more

### Tailwind Variants

O Nitro UI aproveita o [Tailwind Variants](https://www.tailwind-variants.org/){rel="&#x22;nofollow&#x22;"} para oferecer um design system poderoso:

- **Dynamic Styling**: Flexible component variants with a powerful API
- **Type Safety**: Full TypeScript support with auto-completion
- **Conflict Resolution**: Efficient merging of conflicting styles

## Principais recursos

### Integração com o ecossistema

O Nitro UI é compatível com SSR e se integra perfeitamente ao ecossistema Nuxt (esses recursos também funcionam no Vue com configuração adicional):

- [**Icons**](https://ui.nitro.news/docs/getting-started/integrations/icons): Access 200,000+ icons from Iconify
- [**Fonts**](https://ui.nitro.news/docs/getting-started/integrations/fonts): Plug-and-play web font optimization and configuration
- [**Color Mode**](https://ui.nitro.news/docs/getting-started/integrations/color-mode): Dark and Light mode with auto detection
- [**i18n**](https://ui.nitro.news/docs/getting-started/integrations/i18n): Internationalize your components with 50+ languages
- [**Content**](https://ui.nitro.news/docs/getting-started/integrations/content): Beautiful typography out of the box

### Compatibilidade com Vue (Nuxt opcional)

O Nitro UI funciona com qualquer projeto Vue, não apenas Nuxt. Basta adicionar os plugins do Vite e do Vue à sua configuração:

- **Auto-imports**: Components and composables are automatically imported and available globally
- **Design System**: Full theming support with customizable colors, sizes, variants, and more
- **Developer Experience**: Complete TypeScript support with IntelliSense and auto-completion

> \[!TIP]
> See: /docs/getting-started/installation/vue
>
> Aprenda a instalar e configurar o Nitro UI em um projeto Vue no **guia de instalação para Vue**.

### Suporte a TypeScript

O Nitro UI oferece uma integração completa com TypeScript para uma experiência de desenvolvimento superior:

- **Auto-completion**: For all component props, slots, and events
- **Generic Components**: Using [Vue Generics](https://vuejs.org/api/sfc-script-setup.html#generics){rel="&#x22;nofollow&#x22;"}
- **Type-safe Theming**: In `app.config.ts`
- **IntelliSense**: Throughout your entire codebase

## Perguntas frequentes

**Q: Is Nitro UI free to use?**

Sim! O Nitro UI é totalmente gratuito e de código aberto sob a licença MIT. Todos os mais de 125 componentes estão disponíveis para todos.

**Q: Can I use Nitro UI with Vue without Nuxt?**

Sim! Embora otimizado para Nuxt, o Nitro UI funciona perfeitamente com projetos Vue independentes via nosso plugin do Vite. Você pode seguir o [guia de instalação](https://ui.nitro.news/docs/getting-started/installation/vue) para começar.

**Q: How does Nitro UI handle accessibility?**

Por meio da integração com o [Reka UI](https://reka-ui.com/docs/overview/accessibility){rel="&#x22;nofollow&#x22;"}, o Nitro UI fornece atributos ARIA automáticos, navegação por teclado, gerenciamento de foco e suporte a leitores de tela. Embora ofereça uma base sólida, testar no seu caso de uso específico continua sendo importante.

**Q: Is Nitro UI production-ready?**

Sim! O Nitro UI é usado em produção por milhares de aplicações, com mais de 1000 testes no Vitest, atualizações regulares e manutenção ativa.

**Q: When should I consider alternatives?**

Considere o **Vuetify** se você quer o estilo Material Design, o **ant-design-vue** para o estilo Ant Design, o **PrimeVue** ou o **Element Plus** se você não quer Tailwind CSS, o **shadcn-vue** se prefere copiar componentes para o seu repositório, o **Quasar** para apps multiplataforma (web, mobile, desktop), ou o **Reka UI** / **Headless UI** se você só precisa de primitivos sem estilo.

**Q: Where can I get help?**

Faça perguntas e obtenha ajuda no [GitHub Discussions](https://github.com/nuxt/ui/discussions/categories/q-a){rel="&#x22;nofollow&#x22;"}, converse com a comunidade no [Discord](https://go.nuxt.com/discord){rel="&#x22;nofollow&#x22;"} ou relate bugs no [GitHub](https://github.com/nuxt/ui/issues){rel="&#x22;nofollow&#x22;"}.


# Instalação

> \[!NOTE]
> See: /docs/getting-started/installation/vue
>
> Procurando pela versão **Vue**?

## Configuração

### Adicionar a um projeto Nuxt

#### Instale o pacote do Nitro UI

```bash [pnpm]
pnpm add @nitro/ui tailwindcss
```

```bash [yarn]
yarn add @nitro/ui tailwindcss
```

```bash [npm]
npm install @nitro/ui tailwindcss
```

```bash [bun]
bun add @nitro/ui tailwindcss
```

#### Adicione o módulo do Nitro UI no seu `nuxt.config.ts`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nitro/ui']
})
```

> \[!NOTE]
>
> Não é necessário adicionar `@nuxt/icon`, `@nuxt/fonts` ou `@nuxtjs/color-mode` ao seu array `modules`, pois o Nitro UI os registra automaticamente. Você ainda pode configurar esses módulos no seu `nuxt.config.ts` usando as chaves `icon`, `fonts` e `colorMode`.

#### Importe o Tailwind CSS e o Nitro UI no seu CSS

```css [app/assets/css/main.css]
@import "tailwindcss";
@import "@nitro/ui";
```

```ts [nuxt.config.ts] {3}
export default defineNuxtConfig({
  modules: ['@nitro/ui'],
  css: ['~/assets/css/main.css']
})
```

> \[!TIP]
> See: https\://nuxt.com/docs/getting-started/layers
>
> Ao usar [Nuxt Layers](https://nuxt.com/docs/getting-started/layers){rel="&#x22;nofollow&#x22;"}, o módulo gera automaticamente diretivas [`@source`](https://tailwindcss.com/docs/functions-and-directives#source-directive){rel="&#x22;nofollow&#x22;"} para cada diretório de layer, garantindo que o Tailwind CSS escaneie todos os arquivos-fonte dos seus layers em busca de classes utilitárias.

> \[!NOTE]
>
> É recomendado instalar a extensão [Tailwind CSS IntelliSense](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss){rel="&#x22;nofollow&#x22;"} para o VSCode e adicionar as seguintes configurações:
>
> ```json [.vscode/settings.json]
> {
>   "files.associations": {
>     "*.css": "tailwindcss"
>   },
>   "editor.quickSuggestions": {
>     "strings": "on"
>   },
>   "tailwindCSS.classAttributes": ["class", "ui"],
>   "tailwindCSS.classFunctions": ["defineAppConfig"]
> }
> ```

#### Envolva o seu app com o componente App

```vue [app.vue]
<template>
  <NApp>
    <NuxtPage />
  </NApp>
</template>
```

> \[!NOTE]
> See: /docs/components/app
>
> O componente `App` fornece configurações globais e é necessário para que os componentes **Toast** e **Tooltip** funcionem, assim como os **overlays programáticos**.

### Usar um template Nuxt

Comece com um dos nossos templates oficiais usando o botão `Use this template` no GitHub ou a CLI:

```bash [Starter]
npm create nuxt@latest -- -t ui
```

```bash [Landing]
npm create nuxt@latest -- -t ui/landing
```

```bash [Docs]
npm create nuxt@latest -- -t ui/docs
```

```bash [SaaS]
npm create nuxt@latest -- -t ui/saas
```

```bash [Dashboard]
npm create nuxt@latest -- -t ui/dashboard
```

```bash [Chat]
npm create nuxt@latest -- -t ui/chat
```

```bash [Portfolio]
npm create nuxt@latest -- -t ui/portfolio
```

```bash [Changelog]
npm create nuxt@latest -- -t ui/changelog
```

```bash [Editor]
npm create nuxt@latest -- -t ui/editor
```

## Opções

Você pode personalizar o Nitro UI fornecendo opções no seu `nuxt.config.ts`.

### `prefix`

Use a opção `prefix` para alterar o prefixo dos componentes.

- Default: `N`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

```ts [nuxt.config.ts] {4-6}
export default defineNuxtConfig({
  modules: ['@nitro/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    prefix: 'Nuxt'
  }
})
```

### `fonts`

Use a opção `fonts` para habilitar ou desabilitar o módulo [`@nuxt/fonts`](https://github.com/nuxt/fonts){rel="&#x22;nofollow&#x22;"}.

- Default: `true`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

```ts [nuxt.config.ts] {4-6}
export default defineNuxtConfig({
  modules: ['@nitro/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    fonts: false
  }
})
```

### `colorMode`

Use a opção `colorMode` para habilitar ou desabilitar o módulo [`@nuxt/color-mode`](https://github.com/nuxt-modules/color-mode){rel="&#x22;nofollow&#x22;"}.

- Default: `true`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

```ts [nuxt.config.ts] {4-6}
export default defineNuxtConfig({
  modules: ['@nitro/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    colorMode: false
  }
})
```

### `theme.colors`

Use a opção `theme.colors` para definir os aliases de cor dinâmicos usados para gerar o tema dos componentes.

- Default: `['primary', 'secondary', 'success', 'info', 'warning', 'error']`{.inline,language-ts-type,shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

```ts [nuxt.config.ts] {4-8}
export default defineNuxtConfig({
  modules: ['@nitro/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    theme: {
      colors: ['primary', 'error']
    }
  }
})
```

> \[!TIP]
> See: /docs/getting-started/theme/design-system#colors
>
> Saiba mais sobre personalização de cores e tematização na seção Tema.

### `theme.transitions`

Use a opção `theme.transitions` para habilitar ou desabilitar as transições nos componentes.

- Default: `true`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

```ts [nuxt.config.ts] {4-8}
export default defineNuxtConfig({
  modules: ['@nitro/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    theme: {
      transitions: false
    }
  }
})
```

> \[!NOTE]
>
> Essa opção adiciona a classe `transition-colors` nos componentes com estados de hover ou ativo.

### `theme.unstyled` `4.9+`

Use a opção `theme.unstyled` para remover todas as classes de tema padrão dos componentes, mantendo apenas sua estrutura e as classes que você fornece por meio de `class`, `ui` ou `app.config.ui`.

- Default: `false`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

```ts [nuxt.config.ts] {4-8}
export default defineNuxtConfig({
  modules: ['@nitro/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    theme: {
      unstyled: true
    }
  }
})
```

> \[!WARNING]
>
> Isso também remove classes **estruturais** (posicionamento, transições, flex/grid), não apenas as cosméticas. Componentes com muito layout, como `Modal`, `Drawer` ou `Calendar`, exigirão que você forneça novamente o layout deles, semelhante ao modo unstyled do PrimeVue.

### `theme.defaultVariants`

Use a opção `theme.defaultVariants` para sobrescrever as variantes `color` e `size` padrão dos componentes.

- Default: `{ color: 'primary', size: 'md' }`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

```ts [nuxt.config.ts] {4-11}
export default defineNuxtConfig({
  modules: ['@nitro/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    theme: {
      defaultVariants: {
        color: 'neutral',
        size: 'sm'
      }
    }
  }
})
```

### `theme.prefix` `4.2+`

Use a opção `theme.prefix` para configurar o mesmo prefixo que você definiu na importação do Tailwind CSS. Isso garante que os componentes do Nitro UI usem as classes utilitárias e variáveis CSS com o prefixo correto.

```ts [nuxt.config.ts] {4-8}
export default defineNuxtConfig({
  modules: ['@nitro/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    theme: {
      prefix: 'tw'
    }
  }
})
```

```css [app/assets/css/main.css] {1}
@import "tailwindcss" prefix(tw);
@import "@nitro/ui";
```

> \[!WARNING]
> See: https\://fonts.nuxt.com/get-started/configuration#processcssvariables
>
> Você pode precisar habilitar `fonts.processCSSVariables` para usar a opção de prefixo com o módulo `@nuxt/fonts`:
>
> ```ts [nuxt.config.ts] {9-11}
> export default defineNuxtConfig({
>   modules: ['@nitro/ui'],
>   css: ['~/assets/css/main.css'],
>   ui: {
>     theme: {
>       prefix: 'tw'
>     }
>   },
>   fonts: {
>     processCSSVariables: true
>   }
> })
> ```

Isso adicionará automaticamente o prefixo a todas as classes utilitárias do Tailwind e variáveis CSS nos temas dos componentes do Nitro UI:

```html
<!-- Without prefix -->
<button class="px-2 py-1 text-xs hover:bg-primary/75">Button</button>

<!-- With prefix: tw -->
<button class="tw:px-2 tw:py-1 tw:text-xs tw:hover:bg-primary/75">Button</button>
```

> \[!NOTE]
> See: https\://tailwindcss.com/docs/styling-with-utility-classes#using-the-prefix-option
>
> Saiba mais sobre o uso de um prefixo na documentação do Tailwind CSS.

### `prose`

Use a opção `prose` para forçar a importação dos [componentes `Prose`](https://ui.nitro.news/docs/typography) do Nitro UI mesmo que o `@nuxtjs/mdc` ou o `@nuxt/content` não estejam instalados.

- Default: `false`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

```ts [nuxt.config.ts] {4-6}
export default defineNuxtConfig({
  modules: ['@nitro/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    prose: true
  }
})
```

### `mdc` `Deprecated`

Use a opção [`prose`](https://ui.nitro.news/#prose).

### `content`

Use a opção `content` para forçar a importação dos componentes `<Prose>` e `<NContent>` do Nitro UI mesmo que o `@nuxt/content` não esteja instalado.

- Default: `false`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

```ts [nuxt.config.ts] {4-6}
export default defineNuxtConfig({
  modules: ['@nitro/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    content: true
  }
})
```

### `experimental.componentDetection` `4.1+`

Use a opção `experimental.componentDetection` para habilitar a detecção automática de componentes para tree-shaking. Esse recurso escaneia seu código-fonte para detectar quais componentes são realmente usados e gera apenas o CSS necessário para esses componentes (incluindo suas dependências).

- Default: `false`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- Type: `boolean | string[]`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

**Enable automatic detection:**

```ts [nuxt.config.ts] {4-8}
export default defineNuxtConfig({
  modules: ['@nitro/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    experimental: {
      componentDetection: true
    }
  }
})
```

**Include additional components for dynamic usage:**

```ts [nuxt.config.ts] {4-8}
export default defineNuxtConfig({
  modules: ['@nitro/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    experimental: {
      componentDetection: ['Modal', 'Dropdown', 'Popover']
    }
  }
})
```

> \[!NOTE]
>
> Ao fornecer um array de nomes de componentes, a detecção automática é habilitada e esses componentes (junto com suas dependências) têm inclusão garantida. Isso é útil para componentes dinâmicos como `<component :is="..." />` que não podem ser analisados estaticamente.

## Lançamentos contínuos

O Nitro UI usa o [pkg.pr.new](https://github.com/stackblitz-labs/pkg.pr.new){rel="&#x22;nofollow&#x22;"} para lançamentos de preview contínuos, dando aos desenvolvedores acesso instantâneo aos recursos mais recentes e correções de bugs sem esperar pelos lançamentos oficiais.

Lançamentos de preview automáticos são criados para todos os commits e PRs na branch `v4`. Use-os substituindo a versão do seu pacote pelo hash específico do commit ou pelo número do PR.

```diff [package.json]
{
  "dependencies": {
-   "@nitro/ui": "^4.0.0",
+   "@nitro/ui": "https://pkg.pr.new/@nitro/ui@4c96909",
  }
}
```

> \[!NOTE]
>
> **pkg.pr.new** will automatically comment on PRs with the installation URL, making it easy to test changes.


# Instalação

> \[!NOTE]
> See: /docs/getting-started/installation/nuxt
>
> Procurando pela versão **Nuxt**?

## Configuração

### Adicionar a um projeto Vue

#### Instale o pacote do Nitro UI

```bash [pnpm]
pnpm add @nitro/ui tailwindcss
```

```bash [yarn]
yarn add @nitro/ui tailwindcss
```

```bash [npm]
npm install @nitro/ui tailwindcss
```

```bash [bun]
bun add @nitro/ui tailwindcss
```

#### Adicione o plugin Vite do Nitro UI no seu `vite.config.ts`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

```ts [vite.config.ts (Vite)] {3,8}
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nitro/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui()
  ]
})
```

```ts [vite.config.ts (Laravel Inertia)] {3,20-22}
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nitro/ui/vite'
import laravel from 'laravel-vite-plugin'

export default defineConfig({
  plugins: [
    laravel({
      input: ['resources/js/app.ts'],
      refresh: true
    }),
    vue({
      template: {
        transformAssetUrls: {
          base: null,
          includeAbsolute: false
        }
      }
    }),
    ui({
      router: 'inertia'
    })
  ]
})
```

```ts [vite.config.ts (AdonisJS Inertia)] {3,15-17}
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nitro/ui/vite'
import adonisjs from '@adonisjs/vite/client'
import inertia from '@adonisjs/inertia/client'

export default defineConfig({
  plugins: [
    adonisjs({
      entrypoints: ['inertia/app/app.ts'],
      reload: ['resources/views/**/*.edge']
    }),
    inertia(),
    vue(),
    ui({
      router: 'inertia'
    })
  ]
})
```

> \[!TIP]
>
> O Nitro UI registra o `unplugin-auto-import` e o `unplugin-vue-components`, que geram os arquivos de declaração de tipos `auto-imports.d.ts` e `components.d.ts`. Você provavelmente vai querer colocá-los no gitignore e adicioná-los ao seu `tsconfig`.
>
> ```json [tsconfig.app.json]
> {
>   "include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.vue", "auto-imports.d.ts", "components.d.ts"]
> }
> ```
>
> ```bash [.gitignore]
> # Auto-generated type declarations
> auto-imports.d.ts
> components.d.ts
> ```

> \[!TIP]
>
> Internamente, o Nitro UI depende de um alias personalizado para resolver os tipos do tema. Se você usa TypeScript, deve adicionar um alias ao seu `tsconfig` para habilitar o autocompletar no seu `vite.config.ts`.
>
> ```json [tsconfig.node.json]
> {
>   "compilerOptions": {
>     "paths": {
>       "#build/ui": [
>         "./node_modules/.nuxt-ui/ui"
>       ]
>     }
>   }
> }
> ```
>
> ```json [tsconfig.app.json]
> {
>   "compilerOptions": {
>     "paths": {
>       "#build/ui/*": [
>         "./node_modules/.nuxt-ui/ui/*"
>       ]
>     }
>   }
> }
> ```

#### Use o plugin Vue do Nitro UI

```ts [src/main.ts (Vite)] {3,14}
import { createApp } from 'vue'
import { createRouter, createWebHistory } from 'vue-router'
import ui from '@nitro/ui/vue-plugin'
import App from './App.vue'

const app = createApp(App)

const router = createRouter({
  routes: [],
  history: createWebHistory()
})

app.use(router)
app.use(ui)

app.mount('#app')
```

```ts [resources/js/app.ts (Laravel Inertia)] {3,19}
import type { DefineComponent } from 'vue'
import { createInertiaApp } from '@inertiajs/vue3'
import ui from '@nitro/ui/vue-plugin'
import { resolvePageComponent } from 'laravel-vite-plugin/inertia-helpers'
import { createApp, h } from 'vue'

const appName = import.meta.env.VITE_APP_NAME || 'Laravel x Nitro UI'

createInertiaApp({
  title: title => (title ? `${title} - ${appName}` : appName),
  resolve: name =>
    resolvePageComponent(
      `./pages/${name}.vue`,
      import.meta.glob<DefineComponent>('./pages/**/*.vue')
    ),
  setup({ el, App, props, plugin }) {
    createApp({ render: () => h(App, props) })
      .use(plugin)
      .use(ui)
      .mount(el)
  }
})
```

```ts [inertia/app/app.ts (AdonisJS Inertia)] {3,19}
import type { DefineComponent } from 'vue'
import { createInertiaApp } from '@inertiajs/vue3'
import ui from '@nitro/ui/vue-plugin'
import { resolvePageComponent } from '@adonisjs/inertia/helpers'
import { createApp, h } from 'vue'

const appName = import.meta.env.VITE_APP_NAME || 'AdonisJS x Nitro UI'

createInertiaApp({
  title: title => (title ? `${title} - ${appName}` : appName),
  resolve: name =>
    resolvePageComponent(
      `../pages/${name}.vue`,
      import.meta.glob<DefineComponent>('../pages/**/*.vue')
    ),
  setup({ el, App, props, plugin }) {
    createApp({ render: () => h(App, props) })
      .use(plugin)
      .use(ui)
      .mount(el)
  }
})
```

#### Importe o Tailwind CSS e o Nitro UI no seu CSS

```css [src/assets/css/main.css (Vite)]
@import "tailwindcss";
@import "@nitro/ui";
```

```css [resources/css/app.css (Laravel Inertia)]
@import "tailwindcss";
@import "@nitro/ui";
```

```css [inertia/css/app.css (AdonisJS Inertia)]
@import "tailwindcss";
@import "@nitro/ui";
```

> \[!TIP]
>
> Importe o arquivo CSS no seu ponto de entrada.
>
> ```ts [src/main.ts] {1}
> import './assets/css/main.css'
>
> import { createApp } from 'vue'
> import { createRouter, createWebHistory } from 'vue-router'
> import ui from '@nitro/ui/vue-plugin'
> import App from './App.vue'
>
> const app = createApp(App)
>
> const router = createRouter({
>   routes: [],
>   history: createWebHistory()
> })
>
> app.use(router)
> app.use(ui)
>
> app.mount('#app')
> ```
>
> ```ts [resources/js/app.ts (Laravel Inertia)] {1}
> import '../css/app.css'
> import type { DefineComponent } from 'vue'
> import { createInertiaApp } from '@inertiajs/vue3'
> import ui from '@nitro/ui/vue-plugin'
> import { resolvePageComponent } from 'laravel-vite-plugin/inertia-helpers'
> import { createApp, h } from 'vue'
>
> const appName = import.meta.env.VITE_APP_NAME || 'Laravel x Nitro UI'
>
> createInertiaApp({
>   title: title => (title ? `${title} - ${appName}` : appName),
>   resolve: name =>
>     resolvePageComponent(
>       `./pages/${name}.vue`,
>       import.meta.glob<DefineComponent>('./pages/**/*.vue')
>     ),
>   setup({ el, App, props, plugin }) {
>     createApp({ render: () => h(App, props) })
>       .use(plugin)
>       .use(ui)
>       .mount(el)
>   }
> })
> ```
>
> ```ts [inertia/app/app.ts (AdonisJS Inertia)] {1}
> import '../css/app.css'
> import type { DefineComponent } from 'vue'
> import { createInertiaApp } from '@inertiajs/vue3'
> import ui from '@nitro/ui/vue-plugin'
> import { resolvePageComponent } from '@adonisjs/inertia/helpers'
> import { createApp, h } from 'vue'
>
> const appName = import.meta.env.VITE_APP_NAME || 'AdonisJS x Nitro UI'
>
> createInertiaApp({
>   title: title => (title ? `${title} - ${appName}` : appName),
>   resolve: name =>
>     resolvePageComponent(
>       `../pages/${name}.vue`,
>       import.meta.glob<DefineComponent>('../pages/**/*.vue')
>     ),
>   setup({ el, App, props, plugin }) {
>     createApp({ render: () => h(App, props) })
>       .use(plugin)
>       .use(ui)
>       .mount(el)
>   }
> })
> ```

> \[!NOTE]
>
> É recomendado instalar a extensão [Tailwind CSS IntelliSense](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss){rel="&#x22;nofollow&#x22;"} para o VSCode e adicionar as seguintes configurações:
>
> ```json [.vscode/settings.json]
> {
>   "files.associations": {
>     "*.css": "tailwindcss"
>   },
>   "editor.quickSuggestions": {
>     "strings": "on"
>   },
>   "tailwindCSS.classAttributes": ["class", "ui"],
>   "tailwindCSS.classFunctions": ["defineAppConfig"]
> }
> ```

#### Envolva o seu app com o componente App

```vue [src/App.vue (Vite)]
<template>
  <NApp>
    <RouterView />
  </NApp>
</template>
```

```vue [resources/js/pages/index.vue (Laravel Inertia)]
<template>
  <NApp>
    <!-- Your content goes here -->
  </NApp>
</template>
```

```vue [inertia/pages/index.vue (AdonisJS Inertia)]
<template>
  <NApp>
    <!-- Your content goes here -->
  </NApp>
</template>
```

> \[!NOTE]
> See: /docs/components/app
>
> O componente `App` configura o config global e é necessário para **Toast**, **Tooltip** e **overlays programáticos**.

#### Adicione a classe `isolate` ao seu container raiz

```html [index.html (Vite)] {9}
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Nitro UI</title>
  </head>
  <body>
    <div id="app" class="isolate"></div>
    <script type="module" src="/src/main.ts"></script>
  </body>
</html>
```

```blade [resources/views/app.blade.php (Laravel Inertia)] {10}
<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1">
    @inertiaHead
    @vite('resources/js/app.ts')
  </head>
  <body>
    <div class="isolate">
        @inertia
    </div>
  </body>
</html>
```

```edge [resources/views/inertia_layout.edge (AdonisJS Inertia)] {10}
<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1">
    @inertiaHead()
    @vite(['inertia/app/app.ts', `inertia/pages/${page.component}.vue`])
  </head>
  <body>
    @inertia({ class: 'isolate' })
  </body>
</html>
```

> \[!NOTE]
>
> Isso garante que os estilos fiquem restritos ao seu app e evita problemas com overlays e contextos de empilhamento.

## Opções

Você pode personalizar o Nitro UI fornecendo opções no seu `vite.config.ts`.

### `prefix`

Use a opção `prefix` para alterar o prefixo dos componentes.

- Default: `N`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

```ts [vite.config.ts] {9}
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nitro/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      prefix: 'Nuxt'
    })
  ]
})
```

### `ui`

Use a opção `ui` para fornecer a configuração do Nitro UI.

```ts [vite.config.ts] {9-14}
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nitro/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      ui: {
        colors: {
          primary: 'green',
          neutral: 'slate'
        }
      }
    })
  ]
})
```

### `colorMode`

Use a opção `colorMode` para habilitar ou desabilitar a integração de modo de cor do `@vueuse/core`.

- Default: `true`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

```ts [vite.config.ts] {9}
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nitro/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      colorMode: false
    })
  ]
})
```

### `theme.colors`

Use a opção `theme.colors` para definir os aliases de cor dinâmicos usados para gerar o tema dos componentes.

- Default: `['primary', 'secondary', 'success', 'info', 'warning', 'error']`{.inline,language-ts-type,shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

```ts [vite.config.ts] {9-11}
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nitro/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      theme: {
        colors: ['primary', 'error']
      }
    })
  ]
})
```

> \[!TIP]
> See: /docs/getting-started/theme/design-system#colors
>
> Saiba mais sobre personalização de cores e tematização na seção Tema.

### `theme.transitions`

Use a opção `theme.transitions` para habilitar ou desabilitar as transições nos componentes.

- Default: `true`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

```ts [vite.config.ts] {9-11}
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nitro/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      theme: {
        transitions: false
      }
    })
  ]
})
```

> \[!NOTE]
>
> Essa opção adiciona a classe `transition-colors` nos componentes com estados de hover ou ativo.

### `theme.unstyled` `4.9+`

Use a opção `theme.unstyled` para remover todas as classes de tema padrão dos componentes, mantendo apenas sua estrutura e as classes que você fornece por meio de `class`, `ui` ou `app.config.ui`.

- Default: `false`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

```ts [vite.config.ts] {9-11}
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nitro/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      theme: {
        unstyled: true
      }
    })
  ]
})
```

> \[!WARNING]
>
> Isso também remove classes **estruturais** (posicionamento, transições, flex/grid), não apenas as cosméticas. Componentes com muito layout, como `Modal`, `Drawer` ou `Calendar`, exigirão que você forneça novamente o layout deles, semelhante ao modo unstyled do PrimeVue.

### `theme.defaultVariants`

Use a opção `theme.defaultVariants` para sobrescrever as variantes `color` e `size` padrão dos componentes.

- Default: `{ color: 'primary', size: 'md' }`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

```ts [vite.config.ts] {9-14}
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nitro/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      theme: {
        defaultVariants: {
          color: 'neutral',
          size: 'sm'
        }
      }
    })
  ]
})
```

### `theme.prefix` `4.2+`

Use a opção `theme.prefix` para configurar o mesmo prefixo que você definiu na importação do Tailwind CSS. Isso garante que os componentes do Nitro UI usem as classes utilitárias e variáveis CSS com o prefixo correto.

```ts [vite.config.ts] {9-11}
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nitro/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      theme: {
        prefix: 'tw'
      }
    })
  ]
})
```

```css [src/assets/css/main.css] {1}
@import "tailwindcss" prefix(tw);
@import "@nitro/ui";
```

Isso adicionará automaticamente o prefixo a todas as classes utilitárias do Tailwind e variáveis CSS nos temas dos componentes do Nitro UI:

```html
<!-- Without prefix -->
<button class="px-2 py-1 text-xs hover:bg-primary/75">Button</button>

<!-- With prefix: tw -->
<button class="tw:px-2 tw:py-1 tw:text-xs tw:hover:bg-primary/75">Button</button>
```

> \[!NOTE]
> See: https\://tailwindcss.com/docs/styling-with-utility-classes#using-the-prefix-option
>
> Saiba mais sobre o uso de um prefixo na documentação do Tailwind CSS.

### `prose`

Use a opção `prose` para habilitar os [componentes `Prose`](https://ui.nitro.news/docs/typography) do Nitro UI e o tema deles.

- Default: `false`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

```ts [vite.config.ts] {9}
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nitro/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      prose: true
    })
  ]
})
```

### `autoImport`

Use a opção `autoImport` para desabilitar a importação automática de composables ou para personalizar as opções do [`unplugin-auto-import`](https://github.com/unplugin/unplugin-auto-import){rel="&#x22;nofollow&#x22;"}.

- Default: `{}`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

```ts [vite.config.ts] {9}
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nitro/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      autoImport: false
    })
  ]
})
```

> \[!NOTE]
>
> Quando desabilitado, você ainda pode importar composables explicitamente de `@nitro/ui/composables`.

### `components`

Use a opção `components` para desabilitar a importação automática de componentes ou para personalizar as opções do [`unplugin-vue-components`](https://github.com/unplugin/unplugin-vue-components){rel="&#x22;nofollow&#x22;"}.

- Default: `{}`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

```ts [vite.config.ts] {9}
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nitro/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      components: false
    })
  ]
})
```

> \[!NOTE]
>
> Quando desabilitado, você ainda pode importar componentes explicitamente, ex.: `import Button from '@nitro/ui/components/Button.vue'` ou `import ProseCode from '@nitro/ui/components/prose/Code.vue'`.

### `router` `4.3+`

Use a opção `router` para configurar a integração de roteamento. Isso é útil para aplicações que não usam `vue-router`, como apps Electron, MPAs ou frameworks como [Inertia.js](https://inertiajs.com/){rel="&#x22;nofollow&#x22;"} ou [Hybridly](https://hybridly.dev/){rel="&#x22;nofollow&#x22;"}.

- Default: `true`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

| Value                                                                                                                           | Description                                                     |
| ------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| `true`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"}      | Uses `vue-router` for navigation with `RouterLink` component.   |
| `false`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"}     | Disables routing integration, links render as plain `<a>` tags. |
| `'inertia'`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | Uses Inertia.js for navigation with its `Link` component.       |

```ts [vite.config.ts] {9}
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nitro/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      router: false
    })
  ]
})
```

> \[!TIP]
>
> Você pode fornecer uma lógica de navegação personalizada para frameworks como o **Hybridly** definindo `router: false` na configuração do Vite e passando uma função ao instalar o plugin do Vue:
>
> ```ts [src/main.ts]
> import ui from '@nitro/ui/vue-plugin'
> import { router } from 'hybridly'
>
> app.use(ui, {
>   router: (event, { href, external }) => {
>     if (external) {
>       return
>     }
>
>     event.preventDefault()
>
>     router.navigate({ url: href })
>   }
> })
> ```

> \[!NOTE]
>
> Quando definido como `false` ou `'inertia'`, o `vue-router` não é necessário como dependência.

### `scanPackages` `4.3+`

Use a opção `scanPackages` para especificar pacotes npm adicionais que devem ser escaneados em busca de componentes que usam o Nitro UI. Isso é útil quando você tem uma biblioteca de componentes compartilhada que usa componentes do Nitro UI internamente.

```ts [vite.config.ts] {9}
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nitro/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      scanPackages: ['@my-org/ui-components']
    })
  ]
})
```

> \[!NOTE]
>
> Por padrão, apenas o `@nitro/ui` é escaneado. Use esta opção quando seus pacotes externos contiverem componentes Vue que usam o Nitro UI.

### `root` `4.9+`

Use a opção `root` para sobrescrever o diretório onde o Nitro UI gera seu diretório `.nuxt-ui` (que contém os templates do tema). Por padrão, ele usa o `root` do Vite, mas em configurações como [`electron-vite`](https://electron-vite.org/){rel="&#x22;nofollow&#x22;"} o `root` do renderer aponta para um subdiretório (ex.: `src/renderer`), então os templates acabam em `src/renderer/node_modules/.nuxt-ui`, onde o Tailwind não os escaneia, fazendo com que classes de tema como `bg-default`, `ring-default` e `divide-default` fiquem ausentes.

```ts [electron.vite.config.ts] {12}
import { defineConfig } from 'electron-vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nitro/ui/vite'

export default defineConfig({
  renderer: {
    root: 'src/renderer',
    plugins: [
      vue(),
      ui({
        root: __dirname
      })
    ]
  }
})
```

> \[!NOTE]
>
> Aponte o `root` para a raiz do seu projeto para que o diretório `.nuxt-ui` gerado fique em um `node_modules` que o Tailwind escaneia.

## Lançamentos contínuos

O Nitro UI usa o [pkg.pr.new](https://github.com/stackblitz-labs/pkg.pr.new){rel="&#x22;nofollow&#x22;"} para lançamentos de preview contínuos, dando aos desenvolvedores acesso instantâneo aos recursos mais recentes e correções de bugs sem esperar pelos lançamentos oficiais.

Lançamentos de preview automáticos são criados para todos os commits e PRs na branch `v4`. Use-os substituindo a versão do seu pacote pelo hash específico do commit ou pelo número do PR.

```diff [package.json]
{
  "dependencies": {
-   "@nitro/ui": "^4.0.0",
+   "@nitro/ui": "https://pkg.pr.new/@nitro/ui@4c96909",
  }
}
```

> \[!NOTE]
>
> **pkg.pr.new** will automatically comment on PRs with the installation URL, making it easy to test changes.


# Contribuição

O Nitro UI prospera graças à sua incrível comunidade ❤️. Damos as boas-vindas a todas as contribuições por meio de relatos de bugs, pull requests e feedback para ajudar a tornar esta biblioteca ainda melhor.

> \[!CAUTION]
>
> Antes de relatar um bug ou solicitar um recurso, certifique-se de ter lido nossa [documentação](https://ui.nitro.news/){rel="&#x22;nofollow&#x22;"} e as [issues](https://github.com/nuxt/ui/issues?q=is%3Aissue%20is%3Aopen%20sort%3Aupdated-desc){rel="&#x22;nofollow&#x22;"} existentes. Para perguntas e ajuda, use o [GitHub Discussions](https://github.com/nuxt/ui/discussions/categories/q-a){rel="&#x22;nofollow&#x22;"}.

## Assistência de IA

Fornecemos diretrizes de contribuição por meio do [`AGENTS.md`](https://github.com/nuxt/ui/blob/v4/AGENTS.md){rel="&#x22;nofollow&#x22;"} para assistentes de IA ajudarem você a contribuir com o Nitro UI. Ele é detectado automaticamente por todos os agentes de IA de programação e orienta sobre a estrutura dos componentes, padrões de tematização, convenções de testes e diretrizes de documentação.

## Estrutura do projeto

Aqui está uma visão geral dos principais diretórios e arquivos na estrutura do projeto Nitro UI:

### Documentação

A documentação fica na pasta `docs` como um app Nuxt que usa o `@nuxt/content` para gerar páginas a partir de arquivos Markdown. Veja a [documentação do Nuxt Content](https://content.nuxt.com/docs/getting-started){rel="&#x22;nofollow&#x22;"} para detalhes de como funciona. Aqui está um detalhamento da sua estrutura:

```bash
├── app/
│   ├── assets/
│   ├── components/
│   │   └── content/
│   │       └── examples   # Components used in documentation as examples
│   ├── composables/
│   └── ...
├── content/
│   ├── 1.getting-started
│   ├── 2.composables
│   └── 3.components       # Components documentation
```

### Módulo

O código do módulo fica na pasta `src`. Aqui está um detalhamento da sua estrutura:

```bash
├── plugins/
├── runtime/
│   ├── components/        # Where all the components are located
│   │   ├── Accordion.vue
│   │   ├── Alert.vue
│   │   └── ...
│   ├── composables/
│   ├── locale/
│   ├── plugins/
│   ├── types/
│   ├── utils/
│   └── vue/
│       ├── components/
│       └── plugins/
├── theme/                 # This where the theme for each component is located
│   ├── accordion.ts       # Theme for Accordion component
│   ├── alert.ts
│   └── ...
└── module.ts
```

## CLI

Para facilitar o desenvolvimento, criamos uma CLI que você pode usar para gerar componentes e locales. Você a acessa usando o comando `nuxt-ui make`.

Primeiro, você precisa vincular a CLI ao seu ambiente global:

```sh
npm link
```

### Componentes

Você pode criar novos componentes usando o seguinte comando:

```sh
nuxt-ui make component <name> [options]
```

Available options:

- `--primitive` Create a primitive component
- `--prose` Create a prose component
- `--content` Create a content component
- `--template` Only generate specific template (available templates: `playground`, `docs`, `test`, `theme`, `component`)

Example:

```sh
# Create a basic component
nuxt-ui make component my-component

# Create a prose component
nuxt-ui make component heading --prose

# Create a content component
nuxt-ui make component block --content

# Generate only documentation template
nuxt-ui make component my-component --template=docs
```

> \[!NOTE]
>
> Ao criar um novo componente, a CLI gera automaticamente todos os arquivos necessários, como o próprio componente, o tema, os testes e a documentação.

### Locales

Você pode criar novos locales usando o seguinte comando:

```sh
nuxt-ui make locale --code <code> --name <name>
```

> \[!NOTE]
> See: /docs/getting-started/integrations/i18n/nuxt#supported-languages
>
> Saiba mais sobre **i18n** na documentação.

## Enviar um Pull Request (PR)

Antes de começar, verifique se já existe uma issue descrevendo o problema ou a solicitação de recurso em que você está trabalhando. Se existir, deixe um comentário na issue para nos avisar que você está trabalhando nela.

Se não existir, abra uma nova issue para discutir o problema ou o recurso.

### Desenvolvimento local

To begin local development, follow these steps:

#### Clone o repositório `nuxt/ui` para a sua máquina local

```sh
git clone -b v4 https://github.com/nuxt/ui.git
```

#### Habilite o [Corepack](https://github.com/nodejs/corepack){rel="&#x22;nofollow&#x22;"}

```sh
corepack enable
```

#### Instale as dependências

```sh
pnpm install
```

#### Gere os stubs de tipos

```sh
pnpm run dev:prepare
```

#### Inicie o desenvolvimento

- To work on the **documentation** located in the `docs` folder, run:

```sh
pnpm run docs
```

- To test the Nuxt components using the **playground**, run:

```sh
pnpm run dev
```

- To test the Vue components using the **playground**, run:

```sh
pnpm run dev:vue
```

> \[!NOTE]
> See: #cli
>
> Se você está trabalhando na implementação de um novo componente, confira a seção **CLI** para iniciar o processo.

### Configuração da IDE

Recomendamos usar o VSCode junto com a [extensão do ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint){rel="&#x22;nofollow&#x22;"}. Você pode habilitar a correção automática e a formatação ao salvar o código. Veja como:

```json [.vscode/settings.json]
{
  "editor.codeActionsOnSave": {
    "source.fixAll": "never",
    "source.fixAll.eslint": "explicit"
  },
  "prettier.enable": false
}
```

> \[!WARNING]
>
> Como o ESLint já está configurado para formatar o código, não há necessidade de duplicar essa funcionalidade com o **Prettier**. Se você o tiver instalado no seu editor, recomendamos desabilitá-lo para evitar conflitos.

### Linting

Você pode usar o comando `lint` para verificar erros de linting:

```sh
pnpm run lint # check for linting errors
pnpm run lint:fix # fix linting errors
```

### Verificação de tipos

Usamos TypeScript para a verificação de tipos. Você pode usar o comando `typecheck` para verificar erros de tipo:

```sh
pnpm run typecheck
```

### Testes

Antes de enviar um PR, certifique-se de rodar os testes:

```sh
pnpm run test
```

> \[!TIP]
>
> Se você precisar atualizar os snapshots, pressione `u` após a execução dos testes terminar.

### Convenções de commit

Usamos [Conventional Commits](https://www.conventionalcommits.org/){rel="&#x22;nofollow&#x22;"} para as mensagens de commit, o que permite gerar um changelog automaticamente com base nos commits. Por favor, leia o [guia](https://www.conventionalcommits.org/en/v1.0.0/#summary){rel="&#x22;nofollow&#x22;"} caso ainda não esteja familiarizado com ele.

- Use `fix` and `feat` for code changes that affect functionality or logic
- Use `docs` for documentation changes and `chore` for maintenance tasks

### Abrindo um Pull Request

- Follow along the [instructions](https://github.com/nuxt/ui/blob/v4/.github/PULL_REQUEST_TEMPLATE.md?plain=1){rel="&#x22;nofollow&#x22;"} provided when creating a PR
- Ensure your PR's title adheres to the [Conventional Commits](https://www.conventionalcommits.org/){rel="&#x22;nofollow&#x22;"} since it will be used once the code is merged.
- Multiple commits are fine; no need to rebase or force push. We'll use `Squash and Merge` when merging.
- Ensure `lint`, `typecheck` and `tests` work before submitting the PR. Avoid making unrelated changes.

Vamos revisá-lo prontamente. Se for atribuído a um mantenedor, ele o revisará com cuidado. Ignore o texto em vermelho; ele serve para fins de rastreamento.

## Agradecimentos

Obrigado novamente por se interessar por este projeto! Você é incrível! ❤️


# Design System

## Tailwind CSS

O Tailwind CSS usa uma configuração CSS-first, permitindo que você defina seus design tokens com a diretiva [`@theme`](https://tailwindcss.com/docs/functions-and-directives#theme-directive){rel="&#x22;nofollow&#x22;"} diretamente no seu CSS. Isso torna seu tema portátil, de fácil manutenção e fácil de personalizar.

```css [app/assets/css/main.css]
@import "tailwindcss";
@import "@nitro/ui";

@theme {
  /* Your custom design tokens go here */
}
```

> \[!NOTE]
> See: https\://tailwindcss.com/docs/theme
>
> Consulte a documentação do Tailwind CSS para todas as opções de personalização de variáveis de tema disponíveis.

> \[!TIP]
>
> O Tailwind CSS v4 alterou seu [Preflight](https://tailwindcss.com/docs/upgrade-guide#buttons-use-the-default-cursor){rel="&#x22;nofollow&#x22;"} para que os botões usem `cursor: default` em vez de `cursor: pointer`, para corresponder aos padrões do navegador. Se você quiser restaurar o cursor de ponteiro globalmente, adicione estes estilos base ao seu CSS:
>
> ```css [app/assets/css/main.css]
> @layer base {
>   button:not(:disabled),
>   [role="button"]:not(:disabled) {
>     cursor: pointer;
>   }
> }
> ```

### Fontes

Use as variáveis de tema `--font-*` para [personalizar as utilidades de família de fontes](https://tailwindcss.com/docs/font-family#customizing-your-theme){rel="&#x22;nofollow&#x22;"} no seu projeto.

```css [app/assets/css/main.css]
@import "tailwindcss";
@import "@nitro/ui";

@theme {
  --font-sans: 'Public Sans', system-ui, sans-serif;
  --font-mono: 'JetBrains Mono', monospace;
}
```

**Nuxt:**

> \[!NOTE]
> See: /docs/getting-started/integrations/fonts
>
> As fontes definidas aqui são automaticamente carregadas e otimizadas pelo módulo `@nuxt/fonts`.

### Cores

Use as variáveis de tema `--color-*` para [personalizar suas cores](https://tailwindcss.com/docs/colors#customizing-your-colors){rel="&#x22;nofollow&#x22;"} ou [sobrescrever as cores padrão](https://tailwindcss.com/docs/colors#overriding-default-colors){rel="&#x22;nofollow&#x22;"}.

```css [app/assets/css/main.css]
@import "tailwindcss";
@import "@nitro/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;
}
```

> \[!WARNING]
>
> Ao adicionar cores personalizadas, certifique-se de definir todos os tons de `50` a `950` para cada cor.

### Breakpoints

Use as variáveis de tema `--breakpoint-*` para [personalizar seus breakpoints](https://tailwindcss.com/docs/responsive-design#customizing-your-theme){rel="&#x22;nofollow&#x22;"}.

```css [app/assets/css/main.css]
@import "tailwindcss";
@import "@nitro/ui";

@theme {
  --breakpoint-3xl: 1920px;
  --breakpoint-4xl: 2560px;
  --breakpoint-5xl: 3840px;
}
```

## Cores

O sistema de cores do Nitro UI é baseado em **nomes semânticos** em vez de valores de cor específicos. Essa abordagem torna sua UI mais fácil de manter e permite trocar de tema facilmente.

### Cores semânticas

O Nitro UI fornece aliases de cor semânticos que descrevem o **propósito** da cor. Cada alias é definido com base em uma cor da sua configuração `@theme`, que pode ser qualquer cor que você definir, além da [paleta padrão do Tailwind CSS](https://tailwindcss.com/docs/colors){rel="&#x22;nofollow&#x22;"}.

| Color                          | Default  | Description                                                       |
| ------------------------------ | -------- | ----------------------------------------------------------------- |
| `primary`{color="primary"}     | `green`  | Main CTAs, active navigation, brand elements, important links     |
| `secondary`{color="secondary"} | `blue`   | Secondary buttons, alternative actions, complementary UI elements |
| `success`{color="success"}     | `green`  | Success messages, completed states, positive confirmations        |
| `info`{color="info"}           | `blue`   | Info alerts, tooltips, help text, neutral notifications           |
| `warning`{color="warning"}     | `yellow` | Warning messages, pending states, attention-needed items          |
| `error`{color="error"}         | `red`    | Error messages, validation errors, destructive actions            |
| `neutral`                      | `slate`  | Text, borders, backgrounds, disabled states                       |

Essas cores semânticas estão disponíveis na prop `color` dos componentes do Nitro UI:

```vue
<template>
  <UButton color="primary">
    Save Changes
  </UButton>
</template>
```

> \[!NOTE]
>
> Experimente o seletor de tema :prose-icon{.text-primary name="i-lucide-swatch-book"} no header para ver instantaneamente como diferentes esquemas de cores afetam toda a UI!

### Configuração em tempo de execução

**Nuxt:**

Você pode configurar essas cores em tempo de execução no seu arquivo [`app.config.ts`](https://nuxt.com/docs/4.x/directory-structure/app/app-config){rel="&#x22;nofollow&#x22;"}, na chave `ui.colors`, permitindo a personalização dinâmica do tema sem reiniciar o servidor:

```ts [app/app.config.ts]
export default defineAppConfig({
  ui: {
    colors: {
      primary: 'blue',
      secondary: 'purple',
      neutral: 'zinc'
    }
  }
})
```

**Vue:**

Você pode configurar essas cores em tempo de execução no seu arquivo `vite.config.ts`, na chave `ui.colors`, permitindo a personalização dinâmica do tema:

```ts [vite.config.ts]
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nitro/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      ui: {
        colors: {
          primary: 'blue',
          secondary: 'purple',
          neutral: 'zinc'
        }
      }
    })
  ]
})
```

> \[!CAUTION]
>
> Você só pode usar cores que existem no seu tema. Uma das opções:
>
> - Use [Tailwind's default colors](https://tailwindcss.com/docs/colors){rel="&#x22;nofollow&#x22;"} (like `blue`, `green`, `zinc`)
> - Define custom colors first using the `@theme` directive (like `brand` in our example above)

### Estender cores

Você pode querer definir cores semânticas adicionais além das padrão, como adicionar uma cor `tertiary`:

**Nuxt:**

Primeiro, registre a nova cor no seu `nuxt.config.ts`, na chave `ui.theme.colors`:

```ts [nuxt.config.ts] {7}
export default defineNuxtConfig({
  ui: {
    theme: {
      colors: [
        'primary',
        'secondary',
        'tertiary',
        'info',
        'success',
        'warning',
        'error'
      ]
    }
  }
})
```

Depois, atribua-a no seu `app.config.ts`, na chave `ui.colors`:

```ts [app/app.config.ts] {6}
export default defineAppConfig({
  ui: {
    colors: {
      primary: 'blue',
      secondary: 'purple',
      tertiary: 'indigo'
    }
  }
})
```

**Vue:**

Registre e atribua a nova cor no seu arquivo `vite.config.ts`:

```ts [vite.config.ts] {13,24}
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nitro/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'
        }
      }
    })
  ]
})
```

Por fim, use essa nova cor em componentes que suportam a prop `color` ou [como uma classe](https://ui.nitro.news/docs/getting-started/theme/css-variables):

```vue
<NButton color="tertiary">
  Special Action
</NButton>
```


# Variáveis CSS

## Cores

O Nitro UI fornece classes utilitárias do Tailwind CSS para cada [cor semântica](https://ui.nitro.news/docs/getting-started/theme/design-system#semantic-colors) que você definir, permitindo usar nomes de classe como `text-error` ou `bg-success`:

```vue
<template>
  <p>
  <span>
  Primary</span>
  <span>
  Secondary</span>
  <span>
  Success</span>
  <span>
  Info</span>
  <span>
  Warning</span>
  <span>
  Error</span></p>
  <template v-slot:code=>
  <pre className=language-vue shiki shiki-themes material-theme-lighter material-theme material-theme-palenight code=<template>
    <span class="text-primary">Primary</span>
    <span class="text-secondary">Secondary</span>
    <span class="text-success">Success</span>
    <span class="text-info">Info</span>
    <span class="text-warning">Warning</span>
    <span class="text-error">Error</span>
  </template>
   language=vue meta= style=>
  <code __ignoreMap=>
  <span class=line>
  <span class=sMK4o>
  <</span>
  <span class=swJcz>
  template</span>
  <span class=sMK4o>
  >
  </span></span>
  <span class=line>
  <span class=sMK4o>
    <</span>
  <span class=swJcz>
  span</span>
  <span class=spNyl>
   class</span>
  <span class=sMK4o>
  =</span>
  <span class=sMK4o>
  "</span>
  <span class=sfazB>
  text-primary</span>
  <span class=sMK4o>
  "</span>
  <span class=sMK4o>
  ></span>
  <span class=sTEyZ>
  Primary</span>
  <span class=sMK4o>
  </</span>
  <span class=swJcz>
  span</span>
  <span class=sMK4o>
  >
  </span></span>
  <span class=line>
  <span class=sMK4o>
    <</span>
  <span class=swJcz>
  span</span>
  <span class=spNyl>
   class</span>
  <span class=sMK4o>
  =</span>
  <span class=sMK4o>
  "</span>
  <span class=sfazB>
  text-secondary</span>
  <span class=sMK4o>
  "</span>
  <span class=sMK4o>
  ></span>
  <span class=sTEyZ>
  Secondary</span>
  <span class=sMK4o>
  </</span>
  <span class=swJcz>
  span</span>
  <span class=sMK4o>
  >
  </span></span>
  <span class=line>
  <span class=sMK4o>
    <</span>
  <span class=swJcz>
  span</span>
  <span class=spNyl>
   class</span>
  <span class=sMK4o>
  =</span>
  <span class=sMK4o>
  "</span>
  <span class=sfazB>
  text-success</span>
  <span class=sMK4o>
  "</span>
  <span class=sMK4o>
  ></span>
  <span class=sTEyZ>
  Success</span>
  <span class=sMK4o>
  </</span>
  <span class=swJcz>
  span</span>
  <span class=sMK4o>
  >
  </span></span>
  <span class=line>
  <span class=sMK4o>
    <</span>
  <span class=swJcz>
  span</span>
  <span class=spNyl>
   class</span>
  <span class=sMK4o>
  =</span>
  <span class=sMK4o>
  "</span>
  <span class=sfazB>
  text-info</span>
  <span class=sMK4o>
  "</span>
  <span class=sMK4o>
  ></span>
  <span class=sTEyZ>
  Info</span>
  <span class=sMK4o>
  </</span>
  <span class=swJcz>
  span</span>
  <span class=sMK4o>
  >
  </span></span>
  <span class=line>
  <span class=sMK4o>
    <</span>
  <span class=swJcz>
  span</span>
  <span class=spNyl>
   class</span>
  <span class=sMK4o>
  =</span>
  <span class=sMK4o>
  "</span>
  <span class=sfazB>
  text-warning</span>
  <span class=sMK4o>
  "</span>
  <span class=sMK4o>
  ></span>
  <span class=sTEyZ>
  Warning</span>
  <span class=sMK4o>
  </</span>
  <span class=swJcz>
  span</span>
  <span class=sMK4o>
  >
  </span></span>
  <span class=line>
  <span class=sMK4o>
    <</span>
  <span class=swJcz>
  span</span>
  <span class=spNyl>
   class</span>
  <span class=sMK4o>
  =</span>
  <span class=sMK4o>
  "</span>
  <span class=sfazB>
  text-error</span>
  <span class=sMK4o>
  "</span>
  <span class=sMK4o>
  ></span>
  <span class=sTEyZ>
  Error</span>
  <span class=sMK4o>
  </</span>
  <span class=swJcz>
  span</span>
  <span class=sMK4o>
  >
  </span></span>
  <span class=line>
  <span class=sMK4o>
  </</span>
  <span class=swJcz>
  template</span>
  <span class=sMK4o>
  >
  </span></span></code></pre></template>
</template>
```

Cada classe utilitária usa uma variável CSS para definir sua cor nos modos claro e escuro:

```css [Light]
:root {
  --ui-primary: var(--ui-color-primary-500);
  --ui-secondary: var(--ui-color-secondary-500);
  --ui-success: var(--ui-color-success-500);
  --ui-info: var(--ui-color-info-500);
  --ui-warning: var(--ui-color-warning-500);
  --ui-error: var(--ui-color-error-500);
}
```

```css [Dark]
.dark {
  --ui-primary: var(--ui-color-primary-400);
  --ui-secondary: var(--ui-color-secondary-400);
  --ui-success: var(--ui-color-success-400);
  --ui-info: var(--ui-color-info-400);
  --ui-warning: var(--ui-color-warning-400);
  --ui-error: var(--ui-color-error-400);
}
```

> \[!TIP]
>
> Você pode ajustar qual tom cada classe utilitária usa nos modos claro e escuro no seu arquivo `main.css`:
>
> ```css [app/assets/css/main.css]
> @import "tailwindcss";
> @import "@nitro/ui";
>
> :root {
>   --ui-primary: var(--ui-color-primary-700);
> }
>
> .dark {
>   --ui-primary: var(--ui-color-primary-200);
> }
> ```

> \[!WARNING]
>
> Você não pode usar `primary: 'black'` na sua [**configuração**](https://ui.nitro.news/docs/getting-started/theme/design-system#runtime-configuration) porque `black` não tem múltiplos tons. Para usar preto ou branco sólido como sua cor primária, defina-o diretamente no seu arquivo `main.css`:
>
> ```css [app/assets/css/main.css]
> @import "tailwindcss";
> @import "@nitro/ui";
>
> :root {
>   --ui-primary: black;
> }
>
> .dark {
>   --ui-primary: white;
> }
> ```

## Texto

O Nitro UI fornece classes utilitárias do Tailwind CSS para cores de texto, permitindo usar nomes de classe como `text-dimmed` ou `text-muted`:

```vue
<template>
  <p>
  <span>
  Dimmed</span>
  <span>
  Muted</span>
  <span>
  Toned</span>
  <span>
  Text</span>
  <span>
  Highlighted</span>
  <span>
  Inverted</span></p>
  <template v-slot:code=>
  <pre className=language-vue shiki shiki-themes material-theme-lighter material-theme material-theme-palenight code=<template>
    <span class="text-dimmed">Dimmed</span>
    <span class="text-muted">Muted</span>
    <span class="text-toned">Toned</span>
    <span class="text-default">Text</span>
    <span class="text-highlighted">Highlighted</span>
    <span class="text-inverted bg-inverted">Inverted</span>
  </template>
   language=vue meta= style=>
  <code __ignoreMap=>
  <span class=line>
  <span class=sMK4o>
  <</span>
  <span class=swJcz>
  template</span>
  <span class=sMK4o>
  >
  </span></span>
  <span class=line>
  <span class=sMK4o>
    <</span>
  <span class=swJcz>
  span</span>
  <span class=spNyl>
   class</span>
  <span class=sMK4o>
  =</span>
  <span class=sMK4o>
  "</span>
  <span class=sfazB>
  text-dimmed</span>
  <span class=sMK4o>
  "</span>
  <span class=sMK4o>
  ></span>
  <span class=sTEyZ>
  Dimmed</span>
  <span class=sMK4o>
  </</span>
  <span class=swJcz>
  span</span>
  <span class=sMK4o>
  >
  </span></span>
  <span class=line>
  <span class=sMK4o>
    <</span>
  <span class=swJcz>
  span</span>
  <span class=spNyl>
   class</span>
  <span class=sMK4o>
  =</span>
  <span class=sMK4o>
  "</span>
  <span class=sfazB>
  text-muted</span>
  <span class=sMK4o>
  "</span>
  <span class=sMK4o>
  ></span>
  <span class=sTEyZ>
  Muted</span>
  <span class=sMK4o>
  </</span>
  <span class=swJcz>
  span</span>
  <span class=sMK4o>
  >
  </span></span>
  <span class=line>
  <span class=sMK4o>
    <</span>
  <span class=swJcz>
  span</span>
  <span class=spNyl>
   class</span>
  <span class=sMK4o>
  =</span>
  <span class=sMK4o>
  "</span>
  <span class=sfazB>
  text-toned</span>
  <span class=sMK4o>
  "</span>
  <span class=sMK4o>
  ></span>
  <span class=sTEyZ>
  Toned</span>
  <span class=sMK4o>
  </</span>
  <span class=swJcz>
  span</span>
  <span class=sMK4o>
  >
  </span></span>
  <span class=line>
  <span class=sMK4o>
    <</span>
  <span class=swJcz>
  span</span>
  <span class=spNyl>
   class</span>
  <span class=sMK4o>
  =</span>
  <span class=sMK4o>
  "</span>
  <span class=sfazB>
  text-default</span>
  <span class=sMK4o>
  "</span>
  <span class=sMK4o>
  ></span>
  <span class=sTEyZ>
  Text</span>
  <span class=sMK4o>
  </</span>
  <span class=swJcz>
  span</span>
  <span class=sMK4o>
  >
  </span></span>
  <span class=line>
  <span class=sMK4o>
    <</span>
  <span class=swJcz>
  span</span>
  <span class=spNyl>
   class</span>
  <span class=sMK4o>
  =</span>
  <span class=sMK4o>
  "</span>
  <span class=sfazB>
  text-highlighted</span>
  <span class=sMK4o>
  "</span>
  <span class=sMK4o>
  ></span>
  <span class=sTEyZ>
  Highlighted</span>
  <span class=sMK4o>
  </</span>
  <span class=swJcz>
  span</span>
  <span class=sMK4o>
  >
  </span></span>
  <span class=line>
  <span class=sMK4o>
    <</span>
  <span class=swJcz>
  span</span>
  <span class=spNyl>
   class</span>
  <span class=sMK4o>
  =</span>
  <span class=sMK4o>
  "</span>
  <span class=sfazB>
  text-inverted bg-inverted</span>
  <span class=sMK4o>
  "</span>
  <span class=sMK4o>
  ></span>
  <span class=sTEyZ>
  Inverted</span>
  <span class=sMK4o>
  </</span>
  <span class=swJcz>
  span</span>
  <span class=sMK4o>
  >
  </span></span>
  <span class=line>
  <span class=sMK4o>
  </</span>
  <span class=swJcz>
  template</span>
  <span class=sMK4o>
  >
  </span></span></code></pre></template>
</template>
```

Cada classe utilitária usa uma variável CSS para definir sua cor nos modos claro e escuro:

```css [Light]
:root {
  --ui-text-dimmed: var(--ui-color-neutral-400);
  --ui-text-muted: var(--ui-color-neutral-500);
  --ui-text-toned: var(--ui-color-neutral-600);
  --ui-text: var(--ui-color-neutral-700);
  --ui-text-highlighted: var(--ui-color-neutral-900);
  --ui-text-inverted: white;
}
```

```css [Dark]
.dark {
  --ui-text-dimmed: var(--ui-color-neutral-500);
  --ui-text-muted: var(--ui-color-neutral-400);
  --ui-text-toned: var(--ui-color-neutral-300);
  --ui-text: var(--ui-color-neutral-200);
  --ui-text-highlighted: white;
  --ui-text-inverted: var(--ui-color-neutral-900);
}
```

> \[!TIP]
>
> Você pode personalizar essas variáveis CSS no seu arquivo `main.css`:
>
> ```css [app/assets/css/main.css]
> @import "tailwindcss";
> @import "@nitro/ui";
>
> :root {
>   --ui-text: var(--ui-color-neutral-900);
> }
>
> .dark {
>   --ui-text: white;
> }
> ```

## Fundo

O Nitro UI fornece classes utilitárias do Tailwind CSS para cores de fundo, permitindo usar nomes de classe como `bg-default` ou `bg-muted`:

```vue
<template>
  <p>
  <span>
  Default</span>
  <span>
  Muted</span>
  <span>
  Elevated</span>
  <span>
  Accented</span>
  <span>
  Inverted</span></p>
  <template v-slot:code=>
  <pre className=language-vue shiki shiki-themes material-theme-lighter material-theme material-theme-palenight code=<template>
    <div class="bg-default">Default</div>
    <div class="bg-muted">Muted</div>
    <div class="bg-elevated">Elevated</div>
    <div class="bg-accented">Accented</div>
    <div class="bg-inverted text-inverted">Inverted</div>
  </template>
   language=vue meta= style=>
  <code __ignoreMap=>
  <span class=line>
  <span class=sMK4o>
  <</span>
  <span class=swJcz>
  template</span>
  <span class=sMK4o>
  >
  </span></span>
  <span class=line>
  <span class=sMK4o>
    <</span>
  <span class=swJcz>
  div</span>
  <span class=spNyl>
   class</span>
  <span class=sMK4o>
  =</span>
  <span class=sMK4o>
  "</span>
  <span class=sfazB>
  bg-default</span>
  <span class=sMK4o>
  "</span>
  <span class=sMK4o>
  ></span>
  <span class=sTEyZ>
  Default</span>
  <span class=sMK4o>
  </</span>
  <span class=swJcz>
  div</span>
  <span class=sMK4o>
  >
  </span></span>
  <span class=line>
  <span class=sMK4o>
    <</span>
  <span class=swJcz>
  div</span>
  <span class=spNyl>
   class</span>
  <span class=sMK4o>
  =</span>
  <span class=sMK4o>
  "</span>
  <span class=sfazB>
  bg-muted</span>
  <span class=sMK4o>
  "</span>
  <span class=sMK4o>
  ></span>
  <span class=sTEyZ>
  Muted</span>
  <span class=sMK4o>
  </</span>
  <span class=swJcz>
  div</span>
  <span class=sMK4o>
  >
  </span></span>
  <span class=line>
  <span class=sMK4o>
    <</span>
  <span class=swJcz>
  div</span>
  <span class=spNyl>
   class</span>
  <span class=sMK4o>
  =</span>
  <span class=sMK4o>
  "</span>
  <span class=sfazB>
  bg-elevated</span>
  <span class=sMK4o>
  "</span>
  <span class=sMK4o>
  ></span>
  <span class=sTEyZ>
  Elevated</span>
  <span class=sMK4o>
  </</span>
  <span class=swJcz>
  div</span>
  <span class=sMK4o>
  >
  </span></span>
  <span class=line>
  <span class=sMK4o>
    <</span>
  <span class=swJcz>
  div</span>
  <span class=spNyl>
   class</span>
  <span class=sMK4o>
  =</span>
  <span class=sMK4o>
  "</span>
  <span class=sfazB>
  bg-accented</span>
  <span class=sMK4o>
  "</span>
  <span class=sMK4o>
  ></span>
  <span class=sTEyZ>
  Accented</span>
  <span class=sMK4o>
  </</span>
  <span class=swJcz>
  div</span>
  <span class=sMK4o>
  >
  </span></span>
  <span class=line>
  <span class=sMK4o>
    <</span>
  <span class=swJcz>
  div</span>
  <span class=spNyl>
   class</span>
  <span class=sMK4o>
  =</span>
  <span class=sMK4o>
  "</span>
  <span class=sfazB>
  bg-inverted text-inverted</span>
  <span class=sMK4o>
  "</span>
  <span class=sMK4o>
  ></span>
  <span class=sTEyZ>
  Inverted</span>
  <span class=sMK4o>
  </</span>
  <span class=swJcz>
  div</span>
  <span class=sMK4o>
  >
  </span></span>
  <span class=line>
  <span class=sMK4o>
  </</span>
  <span class=swJcz>
  template</span>
  <span class=sMK4o>
  >
  </span></span></code></pre></template>
</template>
```

Cada classe utilitária usa uma variável CSS para definir sua cor nos modos claro e escuro:

```css [Light]
:root {
  --ui-bg: white;
  --ui-bg-muted: var(--ui-color-neutral-50);
  --ui-bg-elevated: var(--ui-color-neutral-100);
  --ui-bg-accented: var(--ui-color-neutral-200);
  --ui-bg-inverted: var(--ui-color-neutral-900);
}
```

```css [Dark]
.dark {
  --ui-bg: var(--ui-color-neutral-900);
  --ui-bg-muted: var(--ui-color-neutral-800);
  --ui-bg-elevated: var(--ui-color-neutral-800);
  --ui-bg-accented: var(--ui-color-neutral-700);
  --ui-bg-inverted: white;
}
```

> \[!TIP]
>
> Você pode personalizar essas variáveis CSS no seu arquivo `main.css`:
>
> ```css [app/assets/css/main.css]
> @import "tailwindcss";
> @import "@nitro/ui";
>
> :root {
>   --ui-bg: var(--ui-color-neutral-50);
> }
>
> .dark {
>   --ui-bg: var(--ui-color-neutral-950);
> }
> ```

## Borda

O Nitro UI fornece classes utilitárias do Tailwind CSS para cores de borda, permitindo usar nomes de classe como `border-default` ou `border-muted`:

```vue
<template>
  <p>
  <span>
  Default</span>
  <span>
  Muted</span>
  <span>
  Accented</span>
  <span>
  Inverted</span></p>
  <template v-slot:code=>
  <pre className=language-vue shiki shiki-themes material-theme-lighter material-theme material-theme-palenight code=<template>
    <div class="border border-default">Default</div>
    <div class="border border-muted">Muted</div>
    <div class="border border-accented">Accented</div>
    <div class="border border-inverted">Inverted</div>
  </template>
   language=vue meta= style=>
  <code __ignoreMap=>
  <span class=line>
  <span class=sMK4o>
  <</span>
  <span class=swJcz>
  template</span>
  <span class=sMK4o>
  >
  </span></span>
  <span class=line>
  <span class=sMK4o>
    <</span>
  <span class=swJcz>
  div</span>
  <span class=spNyl>
   class</span>
  <span class=sMK4o>
  =</span>
  <span class=sMK4o>
  "</span>
  <span class=sfazB>
  border border-default</span>
  <span class=sMK4o>
  "</span>
  <span class=sMK4o>
  ></span>
  <span class=sTEyZ>
  Default</span>
  <span class=sMK4o>
  </</span>
  <span class=swJcz>
  div</span>
  <span class=sMK4o>
  >
  </span></span>
  <span class=line>
  <span class=sMK4o>
    <</span>
  <span class=swJcz>
  div</span>
  <span class=spNyl>
   class</span>
  <span class=sMK4o>
  =</span>
  <span class=sMK4o>
  "</span>
  <span class=sfazB>
  border border-muted</span>
  <span class=sMK4o>
  "</span>
  <span class=sMK4o>
  ></span>
  <span class=sTEyZ>
  Muted</span>
  <span class=sMK4o>
  </</span>
  <span class=swJcz>
  div</span>
  <span class=sMK4o>
  >
  </span></span>
  <span class=line>
  <span class=sMK4o>
    <</span>
  <span class=swJcz>
  div</span>
  <span class=spNyl>
   class</span>
  <span class=sMK4o>
  =</span>
  <span class=sMK4o>
  "</span>
  <span class=sfazB>
  border border-accented</span>
  <span class=sMK4o>
  "</span>
  <span class=sMK4o>
  ></span>
  <span class=sTEyZ>
  Accented</span>
  <span class=sMK4o>
  </</span>
  <span class=swJcz>
  div</span>
  <span class=sMK4o>
  >
  </span></span>
  <span class=line>
  <span class=sMK4o>
    <</span>
  <span class=swJcz>
  div</span>
  <span class=spNyl>
   class</span>
  <span class=sMK4o>
  =</span>
  <span class=sMK4o>
  "</span>
  <span class=sfazB>
  border border-inverted</span>
  <span class=sMK4o>
  "</span>
  <span class=sMK4o>
  ></span>
  <span class=sTEyZ>
  Inverted</span>
  <span class=sMK4o>
  </</span>
  <span class=swJcz>
  div</span>
  <span class=sMK4o>
  >
  </span></span>
  <span class=line>
  <span class=sMK4o>
  </</span>
  <span class=swJcz>
  template</span>
  <span class=sMK4o>
  >
  </span></span></code></pre></template>
</template>
```

Cada classe utilitária usa uma variável CSS para definir sua cor nos modos claro e escuro:

```css [Light]
:root {
  --ui-border: var(--ui-color-neutral-200);
  --ui-border-muted: var(--ui-color-neutral-200);
  --ui-border-accented: var(--ui-color-neutral-300);
  --ui-border-inverted: var(--ui-color-neutral-900);
}
```

```css [Dark]
.dark {
  --ui-border: var(--ui-color-neutral-800);
  --ui-border-muted: var(--ui-color-neutral-700);
  --ui-border-accented: var(--ui-color-neutral-700);
  --ui-border-inverted: white;
}
```

> \[!TIP]
>
> Você pode personalizar essas variáveis CSS no seu arquivo `main.css`:
>
> ```css [app/assets/css/main.css]
> @import "tailwindcss";
> @import "@nitro/ui";
>
> :root {
>   --ui-border: var(--ui-color-neutral-100);
> }
>
> .dark {
>   --ui-border: var(--ui-color-neutral-900);
> }
> ```

## Foco `4.9+`

O Nitro UI aplica um contorno `focus-visible` em cada elemento interativo, tingido com a prop `color` do componente, ex.: `outline-primary/25` quando `color="primary"` ou `outline-inverted/25` quando `color="neutral"`.

Se você prefere uma única cor de contorno em todo o seu app, independentemente da cor do componente, pode adicionar uma regra global no seu arquivo `main.css`:

```css [Primary]
@import "tailwindcss";
@import "@nitro/ui";

*,
::before,
::after {
  @apply outline-primary/25;
}

*:focus-visible,
*:has(> a:focus-visible) {
  --tw-ring-color: var(--ui-primary);
}
```

```css [Neutral]
@import "tailwindcss";
@import "@nitro/ui";

*,
::before,
::after {
  @apply outline-inverted/25;
}

*:focus-visible,
*:has(> a:focus-visible) {
  --tw-ring-color: var(--ui-border-inverted);
}
```

A primeira regra tinge o contorno de foco de cada componente; a segunda alinha a recoloração do ring aplicada no foco pelas variantes com uma borda visível, como `outline` ou `subtle`, incluindo cards que se destacam quando o link deles está em foco.

> \[!NOTE]
>
> Certifique-se de declarar essas regras fora de qualquer `@layer` para que tenham precedência sobre as cores definidas pelos temas dos componentes. Tenha em mente que a primeira regra também tinge o contorno de foco nativo dos seus próprios elementos, e as variantes que recolorem uma `border` no foco, como [FileUpload](https://ui.nitro.news/docs/components/file-upload) ou [ContentSurround](https://ui.nitro.news/docs/components/content-surround), continuam seguindo o `color` do componente.

## Raio

O Nitro UI sobrescreve as utilidades `rounded-*` padrão do Tailwind CSS com um sistema unificado de raio de borda, permitindo usar as [utilidades de raio de borda](https://tailwindcss.com/docs/border-radius){rel="&#x22;nofollow&#x22;"} comuns, como `rounded-xs` ou `rounded-2xl`:

```vue
<template>
  <p>
  <span>
  xs</span>
  <span>
  sm</span>
  <span>
  md</span>
  <span>
  lg</span>
  <span>
  xl</span>
  <span>
  2xl</span>
  <span>
  3xl</span></p>
  <template v-slot:code=>
  <pre className=language-vue shiki shiki-themes material-theme-lighter material-theme material-theme-palenight code=<template>
    <div class="rounded-xs">xs</div>
    <div class="rounded-sm">sm</div>
    <div class="rounded-md">md</div>
    <div class="rounded-lg">lg</div>
    <div class="rounded-xl">xl</div>
    <div class="rounded-2xl">2xl</div>
    <div class="rounded-3xl">3xl</div>
  </template>
   language=vue meta= style=>
  <code __ignoreMap=>
  <span class=line>
  <span class=sMK4o>
  <</span>
  <span class=swJcz>
  template</span>
  <span class=sMK4o>
  >
  </span></span>
  <span class=line>
  <span class=sMK4o>
    <</span>
  <span class=swJcz>
  div</span>
  <span class=spNyl>
   class</span>
  <span class=sMK4o>
  =</span>
  <span class=sMK4o>
  "</span>
  <span class=sfazB>
  rounded-xs</span>
  <span class=sMK4o>
  "</span>
  <span class=sMK4o>
  ></span>
  <span class=sTEyZ>
  xs</span>
  <span class=sMK4o>
  </</span>
  <span class=swJcz>
  div</span>
  <span class=sMK4o>
  >
  </span></span>
  <span class=line>
  <span class=sMK4o>
    <</span>
  <span class=swJcz>
  div</span>
  <span class=spNyl>
   class</span>
  <span class=sMK4o>
  =</span>
  <span class=sMK4o>
  "</span>
  <span class=sfazB>
  rounded-sm</span>
  <span class=sMK4o>
  "</span>
  <span class=sMK4o>
  ></span>
  <span class=sTEyZ>
  sm</span>
  <span class=sMK4o>
  </</span>
  <span class=swJcz>
  div</span>
  <span class=sMK4o>
  >
  </span></span>
  <span class=line>
  <span class=sMK4o>
    <</span>
  <span class=swJcz>
  div</span>
  <span class=spNyl>
   class</span>
  <span class=sMK4o>
  =</span>
  <span class=sMK4o>
  "</span>
  <span class=sfazB>
  rounded-md</span>
  <span class=sMK4o>
  "</span>
  <span class=sMK4o>
  ></span>
  <span class=sTEyZ>
  md</span>
  <span class=sMK4o>
  </</span>
  <span class=swJcz>
  div</span>
  <span class=sMK4o>
  >
  </span></span>
  <span class=line>
  <span class=sMK4o>
    <</span>
  <span class=swJcz>
  div</span>
  <span class=spNyl>
   class</span>
  <span class=sMK4o>
  =</span>
  <span class=sMK4o>
  "</span>
  <span class=sfazB>
  rounded-lg</span>
  <span class=sMK4o>
  "</span>
  <span class=sMK4o>
  ></span>
  <span class=sTEyZ>
  lg</span>
  <span class=sMK4o>
  </</span>
  <span class=swJcz>
  div</span>
  <span class=sMK4o>
  >
  </span></span>
  <span class=line>
  <span class=sMK4o>
    <</span>
  <span class=swJcz>
  div</span>
  <span class=spNyl>
   class</span>
  <span class=sMK4o>
  =</span>
  <span class=sMK4o>
  "</span>
  <span class=sfazB>
  rounded-xl</span>
  <span class=sMK4o>
  "</span>
  <span class=sMK4o>
  ></span>
  <span class=sTEyZ>
  xl</span>
  <span class=sMK4o>
  </</span>
  <span class=swJcz>
  div</span>
  <span class=sMK4o>
  >
  </span></span>
  <span class=line>
  <span class=sMK4o>
    <</span>
  <span class=swJcz>
  div</span>
  <span class=spNyl>
   class</span>
  <span class=sMK4o>
  =</span>
  <span class=sMK4o>
  "</span>
  <span class=sfazB>
  rounded-2xl</span>
  <span class=sMK4o>
  "</span>
  <span class=sMK4o>
  ></span>
  <span class=sTEyZ>
  2xl</span>
  <span class=sMK4o>
  </</span>
  <span class=swJcz>
  div</span>
  <span class=sMK4o>
  >
  </span></span>
  <span class=line>
  <span class=sMK4o>
    <</span>
  <span class=swJcz>
  div</span>
  <span class=spNyl>
   class</span>
  <span class=sMK4o>
  =</span>
  <span class=sMK4o>
  "</span>
  <span class=sfazB>
  rounded-3xl</span>
  <span class=sMK4o>
  "</span>
  <span class=sMK4o>
  ></span>
  <span class=sTEyZ>
  3xl</span>
  <span class=sMK4o>
  </</span>
  <span class=swJcz>
  div</span>
  <span class=sMK4o>
  >
  </span></span>
  <span class=line>
  <span class=sMK4o>
  </</span>
  <span class=swJcz>
  template</span>
  <span class=sMK4o>
  >
  </span></span></code></pre></template>
</template>
```

Essas classes utilitárias são calculadas com base em uma variável CSS global `--ui-radius`, que define o valor de raio base aplicado a todos os componentes para uma aparência consistente.

```css
:root {
  --ui-radius: 0.25rem;
}
```

> \[!TIP]
>
> Você pode personalizar o valor do raio base no seu arquivo `main.css`:
>
> ```css [app/assets/css/main.css]
> @import "tailwindcss";
> @import "@nitro/ui";
>
> :root {
>   --ui-radius: 0.5rem;
> }
> ```

> \[!NOTE]
>
> Experimente o seletor de tema :prose-icon{.text-primary name="i-lucide-swatch-book"} no header acima para alterar o valor do raio base.

## Container

O Nitro UI fornece uma variável CSS `--ui-container` que controla a largura máxima do componente [Container](https://ui.nitro.news/docs/components/container).

```css
:root {
  --ui-container: 80rem; /* var(--container-7xl) */
}
```

> \[!TIP]
>
> Você pode personalizar esse valor no seu arquivo `main.css` para ajustar as larguras dos containers de forma consistente em toda a sua aplicação:
>
> ```css [app/assets/css/main.css]
> @import "tailwindcss";
> @import "@nitro/ui";
>
> @theme {
>   --container-8xl: 90rem;
> }
>
> :root {
>   --ui-container: var(--container-8xl);
> }
> ```

## Cabeçalho

O Nitro UI fornece uma variável CSS `--ui-header-height` que controla a altura do componente [Header](https://ui.nitro.news/docs/components/header).

```css
:root {
  --ui-header-height: 4rem;
}
```

> \[!TIP]
>
> Você pode personalizar esse valor no seu `main.css` para ajustar a altura do header de forma consistente em toda a sua aplicação:
>
> ```css [app/assets/css/main.css]
> @import "tailwindcss";
> @import "@nitro/ui";
>
> :root {
>   --ui-header-height: --spacing(24);
> }
> ```

## Corpo

O Nitro UI aplica classes padrão no elemento `<body>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="html"} do seu app para uma tematização consistente entre os modos claro e escuro:

```css
body {
  @apply antialiased text-default bg-default scheme-light dark:scheme-dark;
}
```


# Personalizar componentes

## Tailwind Variants

Os componentes do Nitro UI são estilizados usando a API do [Tailwind Variants](https://www.tailwind-variants.org/){rel="&#x22;nofollow&#x22;"}, que oferece uma maneira poderosa de criar variantes e gerenciar os estilos dos componentes.

### Slots

Os componentes podem ter vários `slots`, cada um representando um elemento HTML ou seção distinta dentro do componente. Esses slots permitem inserção de conteúdo e estilização flexíveis.

Vamos usar como exemplo o componente [Card](https://ui.nitro.news/docs/components/card), que tem vários slots:

```ts [src/theme/card.ts]
export default {
  slots: {
    root: 'bg-default ring ring-default divide-y divide-default rounded-lg',
    header: 'p-4 sm:px-6',
    body: 'p-4 sm:p-6',
    footer: 'p-4 sm:px-6'
  }
}
```

```vue [src/runtime/components/Card.vue]
<template>
  <div :class="ui.root({ class: [props.ui?.root, props.class] })">
    <div :class="ui.header({ class: props.ui?.header })">
      <slot name="header" />
    </div>

    <div :class="ui.body({ class: props.ui?.body })">
      <slot />
    </div>

    <div :class="ui.footer({ class: props.ui?.footer })">
      <slot name="footer" />
    </div>
  </div>
</template>
```

Alguns componentes não têm slots; eles são compostos apenas por um único elemento raiz. Nesse caso, o tema define apenas o slot `base`, como o componente [Container](https://ui.nitro.news/docs/components/container), por exemplo:

```ts [src/theme/container.ts]
export default {
  base: 'max-w-(--ui-container) mx-auto px-4 sm:px-6 lg:px-8'
}
```

```vue [src/runtime/components/Container.vue]
<template>
  <div :class="container({ class: props.class })">
    <slot />
  </div>
</template>
```

> \[!WARNING]
>
> Componentes sem slots não têm a [prop `ui`](https://ui.nitro.news/#ui-prop); apenas a [prop `class`](https://ui.nitro.news/#class-prop) está disponível para sobrescrever os estilos.

### Variantes

Os componentes suportam `variants`, que permitem ajustar dinamicamente os estilos dos diferentes `slots` com base nas props do componente.

Por exemplo, o componente [Avatar](https://ui.nitro.news/docs/components/avatar) usa uma variante `size` para controlar sua aparência:

```ts [src/theme/avatar.ts] {6-18}
export default {
  slots: {
    root: 'inline-flex items-center justify-center shrink-0 select-none overflow-hidden rounded-full align-middle bg-elevated',
    image: 'h-full w-full rounded-[inherit] object-cover'
  },
  variants: {
    size: {
      sm: {
        root: 'size-7 text-sm'
      },
      md: {
        root: 'size-8 text-base'
      },
      lg: {
        root: 'size-9 text-lg'
      }
    }
  },
  defaultVariants: {
    size: 'md'
  }
}
```

Dessa forma, a prop `size` aplicará os estilos correspondentes ao slot `root`:

```vue
<template>
  <UAvatar src="https://github.com/nuxt.png" size="lg" />
</template>
```

### Variantes padrão

A propriedade `defaultVariants` define o valor padrão de cada variante quando nenhuma prop é passada.

Por exemplo, o componente [Avatar](https://ui.nitro.news/docs/components/avatar) tem seu tamanho padrão definido como `md`:

```ts [src/theme/avatar.ts] {19-21}
export default {
  slots: {
    root: 'inline-flex items-center justify-center shrink-0 select-none overflow-hidden rounded-full align-middle bg-elevated',
    image: 'h-full w-full rounded-[inherit] object-cover'
  },
  variants: {
    size: {
      sm: {
        root: 'size-7 text-sm'
      },
      md: {
        root: 'size-8 text-base'
      },
      lg: {
        root: 'size-9 text-lg'
      }
    }
  },
  defaultVariants: {
    size: 'md'
  }
}
```

**Nuxt:**

> \[!TIP]
> See: /docs/getting-started/installation/nuxt#themedefaultvariants
>
> Você pode usar a opção `theme.defaultVariants` no seu `nuxt.config.ts` para sobrescrever os valores padrão de `size` e `color` de todos os componentes de uma vez.

**Vue:**

> \[!TIP]
> See: /docs/getting-started/installation/vue#themedefaultvariants
>
> Você pode usar a opção `theme.defaultVariants` no seu `vite.config.ts` para sobrescrever os valores padrão de `size` e `color` de todos os componentes de uma vez.

### Variantes compostas

Alguns componentes usam a propriedade `compoundVariants` para aplicar classes quando várias condições de variante são atendidas ao mesmo tempo.

Por exemplo, o componente [Button](https://ui.nitro.news/docs/components/button) usa a propriedade `compoundVariants` para aplicar classes a uma combinação específica de `color` e `variant`:

```ts [src/theme/button.ts] {27-31}
import type { ModuleOptions } from '../module'

export default (options: Required<ModuleOptions>) => ({
  slots: {
    base: ['rounded-md font-medium inline-flex items-center disabled:cursor-not-allowed aria-disabled:cursor-not-allowed disabled:opacity-75 aria-disabled:opacity-75', options.theme.transitions && 'transition-colors']
  },
  variants: {
    color: {
      ...Object.fromEntries((options.theme.colors || []).map((color: string) => [color, ''])),
      neutral: ''
    },
    variant: {
      solid: '',
      outline: '',
      soft: '',
      subtle: '',
      ghost: '',
      link: ''
    }
  },
  compoundVariants: [
    ...(options.theme.colors || []).map((color: string) => ({
      color,
      variant: 'outline',
      class: `ring ring-inset ring-${color}/50 text-${color} hover:bg-${color}/10 active:bg-${color}/10 disabled:bg-transparent aria-disabled:bg-transparent dark:disabled:bg-transparent dark:aria-disabled:bg-transparent focus:outline-none focus-visible:ring-2 focus-visible:ring-${color}`
    })),
    {
      color: 'neutral',
      variant: 'outline',
      class: 'ring ring-inset ring-accented text-default bg-default hover:bg-elevated active:bg-elevated disabled:bg-default aria-disabled:bg-default focus:outline-none focus-visible:ring-2 focus-visible:ring-inverted'
    }
  ],
  defaultVariants: {
    color: 'primary',
    variant: 'solid'
  }
})
```

## Personalizar o tema

Você tem várias maneiras de personalizar a aparência dos componentes do Nitro UI: pode fazer isso para todos os componentes de uma vez ou individualmente por componente.

> \[!NOTE]
>
> O Tailwind Variants usa o [`tailwind-merge`](https://github.com/dcastil/tailwind-merge){rel="&#x22;nofollow&#x22;"} internamente para mesclar classes, então você não precisa se preocupar com classes conflitantes.

> \[!TIP]
>
> Você pode explorar o tema de cada componente de duas maneiras:
>
> - Check the `Theme` section in the documentation of each individual component.
> - Browse the source code directly in the GitHub repository at [`src/theme`](https://github.com/nuxt/ui/tree/v4/src/theme){rel="&#x22;nofollow&#x22;"}.

### Configuração global

**Nuxt:**

Você pode sobrescrever o tema dos componentes globalmente dentro do seu `app.config.ts` usando exatamente a mesma estrutura do objeto de tema.

**Vue:**

Você pode sobrescrever o tema dos componentes globalmente dentro do seu `vite.config.ts` usando exatamente a mesma estrutura do objeto de tema.

Você pode personalizar os [`slots`](https://ui.nitro.news/#slots), [`variants`](https://ui.nitro.news/#variants), [`compoundVariants`](https://ui.nitro.news/#compound-variants) e [`defaultVariants`](https://ui.nitro.news/#default-variants) de um componente para alterar o tema padrão dele:

**Nuxt:**

```ts [app/app.config.ts]
export default defineAppConfig({
  ui: {
    button: {
      slots: {
        base: 'font-bold'
      },
      variants: {
        size: {
          md: {
            leadingIcon: 'size-4'
          }
        }
      },
      compoundVariants: [{
        color: 'neutral',
        variant: 'outline',
        class: 'ring-default hover:bg-accented'
      }],
      defaultVariants: {
        color: 'neutral',
        variant: 'outline'
      }
    }
  }
})
```

**Vue:**

```ts [vite.config.ts]
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nitro/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      ui: {
        button: {
          slots: {
            base: 'font-bold'
          },
          variants: {
            size: {
              md: {
                leadingIcon: 'size-4'
              }
            }
          },
          compoundVariants: [{
            color: 'neutral',
            variant: 'outline',
            class: 'ring-default hover:bg-accented'
          }],
          defaultVariants: {
            color: 'neutral',
            variant: 'outline'
          }
        }
      }
    })
  ]
})
```

> \[!NOTE]
>
> Neste exemplo, `font-bold` sobrescreve `font-medium` em todos os botões, `size-4` sobrescreve a classe `size-5` no ícone à esquerda quando `size="md"`, e `ring-default hover:bg-accented` sobrescreve `ring-accented hover:bg-elevated` quando `color="neutral"` e `variant="outline"`. Os botões agora usam por padrão `color="neutral"` e `variant="outline"`.

Por padrão, essas classes são mescladas com os padrões do componente. Você também pode definir um slot como uma função para substituir suas classes por completo. Ela recebe as classes padrão resolvidas como argumento, então você pode reutilizar parte delas se necessário.

**Nuxt:**

```ts [app/app.config.ts]
export default defineAppConfig({
  ui: {
    button: {
      slots: {
        label: () => 'text-base font-bold'
      }
    }
  }
})
```

**Vue:**

```ts [vite.config.ts]
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nitro/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      ui: {
        button: {
          slots: {
            label: () => 'text-base font-bold'
          }
        }
      }
    })
  ]
})
```

> \[!TIP]
> See: /docs/getting-started/installation/nuxt#themeunstyled
>
> Para remover as classes padrão de todos os componentes de uma vez, use a opção `theme.unstyled`.

### Componente de tema

O componente [Theme](https://ui.nitro.news/docs/components/theme) sobrescreve os slots e os valores padrão de props de todos os seus descendentes, sem afetar o resto do app. Isso tem prioridade sobre a configuração global, mas as props `ui` e `class` ainda prevalecem sobre ele. Os slots aceitam a mesma forma de função para substituir suas classes em vez de mesclá-las.

:component-example{name="theme-ui-example"}

### `ui` prop

Você também pode sobrescrever os **slots** de um componente usando a prop `ui`. Isso tem prioridade tanto sobre a configuração global quanto sobre as `variants` resolvidas.

```vue
<template>
  <UButton trailing-icon="i-lucide-chevron-right" size="md" color="neutral" variant="outline" :ui="{
  trailingIcon: 'rotate-90 size-3'
}">
    Button
  </UButton>
</template>
```

> \[!NOTE]
>
> Neste exemplo, o slot `trailingIcon` é sobrescrito com `size-3`, mesmo que a variante de tamanho `md` fosse aplicar a ele uma classe `size-5`.

O valor de um slot também pode ser uma função para substituir suas classes em vez de mesclá-las, da mesma forma que na configuração global:

```vue
<template>
  <NButton :ui="{ label: () => 'text-base font-bold' }" label="Button" />
</template>
```

### `class` prop

A prop `class` permite sobrescrever as classes do slot `root` ou `base`. Isso tem prioridade tanto sobre a configuração global quanto sobre as `variants` resolvidas.

```vue
<template>
  <UButton class="font-bold rounded-full">
    Button
  </UButton>
</template>
```

> \[!NOTE]
>
> Neste exemplo, a classe `font-bold` sobrescreverá a classe padrão `font-medium` neste botão.


# Ícones

> \[!NOTE]
> See: /docs/getting-started/integrations/icons/vue
>
> Procurando pela versão **Vue**?

## Uso

O Nitro UI registra automaticamente o módulo [`@nuxt/icon`](https://github.com/nuxt/icon){rel="&#x22;nofollow&#x22;"} para você, então nenhuma configuração adicional é necessária.

### Componente de ícone

Você pode usar o componente [Icon](https://ui.nitro.news/docs/components/icon) com uma prop `name` para exibir um ícone:

```vue
<template>
  <UIcon name="i-lucide-lightbulb" class="size-5" />
</template>
```

> \[!NOTE]
>
> Você pode usar qualquer nome da coleção <https://iconify.design>{rel="&#x22;nofollow&#x22;"}. Navegue por eles facilmente em <https://icones.js.org>{rel="&#x22;nofollow&#x22;"} ou busque diretamente pelo seu assistente de IA usando a ferramenta MCP [`search_icons`](https://ui.nitro.news/docs/getting-started/ai/mcp#available-tools).

### Props do componente

Alguns componentes também têm uma prop `icon` para exibir um ícone, como o [Button](https://ui.nitro.news/docs/components/button), por exemplo:

```vue
<template>
  <UButton icon="i-lucide-sun" variant="subtle">
    Button
  </UButton>
</template>
```

## Coleções

### Conjunto de dados do Iconify

É altamente recomendado instalar os dados dos ícones localmente com:

```bash [pnpm]
pnpm i @iconify-json/{collection_name}
```

```bash [yarn]
yarn add @iconify-json/{collection_name}
```

```bash [npm]
npm install @iconify-json/{collection_name}
```

Por exemplo, para usar o ícone `i-uil-github`, instale sua coleção com `@iconify-json/uil`. Assim os ícones podem ser servidos localmente ou a partir das suas funções serverless, o que é mais rápido e confiável tanto no SSR quanto no lado do cliente.

Instalar a coleção também permite que o Nitro UI embuta os ícones que usa no bundle do cliente em tempo de build, para que fiquem disponíveis na primeira renderização em vez de serem carregados sob demanda em tempo de execução. Isso acontece automaticamente para os ícones próprios do Nitro UI, da coleção `lucide` por padrão. Para empacotar outros ícones, como os que você sobrescreve ou usa em outros lugares do seu app, adicione-os à opção [`clientBundle.icons`](https://github.com/nuxt/icon?tab=readme-ov-file#client-bundle){rel="&#x22;nofollow&#x22;"} do `@nuxt/icon` no seu `nuxt.config.ts`:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nitro/ui'],
  css: ['~/assets/css/main.css'],
  icon: {
    clientBundle: {
      icons: ['lucide:heart', 'simple-icons:github']
    }
  }
})
```

Ou habilite `clientBundle.scan` para empacotar todos os ícones usados no seu app escaneando seu código-fonte, para que você não precise listá-los um a um:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nitro/ui'],
  css: ['~/assets/css/main.css'],
  icon: {
    clientBundle: {
      scan: true
    }
  }
})
```

> \[!NOTE]
> See: https\://github.com/nuxt/icon?tab=readme-ov-file#iconify-dataset
>
> Leia mais sobre isso na documentação do `@nuxt/icon`.

### Coleções locais personalizadas

Você pode usar arquivos SVG locais para criar uma coleção Iconify personalizada.

Por exemplo, coloque os arquivos SVG dos seus ícones em uma pasta de sua escolha, por exemplo, `./app/assets/icons`:

```bash
assets/icons
├── add.svg
└── remove.svg
```

No seu `nuxt.config.ts`, adicione um item em `icon.customCollections`:

```ts
export default defineNuxtConfig({
  modules: ['@nitro/ui'],
  css: ['~/assets/css/main.css'],
  icon: {
    customCollections: [{
      prefix: 'custom',
      dir: './app/assets/icons'
    }]
  }
})
```

Depois, você pode usar os ícones assim:

```vue
<template>
  <NIcon name="i-custom-add" />
</template>
```

> \[!NOTE]
> See: https\://github.com/nuxt/icon?tab=readme-ov-file#custom-local-collections
>
> Leia mais sobre isso na documentação do `@nuxt/icon`.

## Tema

Você pode alterar os ícones padrão usados pelos componentes no seu `app.config.ts`:

*See the interactive theme picker on the documentation website.*

> \[!NOTE]
>
> Os ícones que você sobrescreve em `app.config.ts` são carregados sob demanda em tempo de execução, em vez de serem embutidos no bundle do cliente. Para empacotá-los também, adicione-os no formato `{collection}:{name}` (por exemplo, `lucide:rocket`) à opção [`clientBundle.icons`](https://github.com/nuxt/icon?tab=readme-ov-file#client-bundle){rel="&#x22;nofollow&#x22;"} do `@nuxt/icon` no seu `nuxt.config.ts`.


# Ícones

> \[!NOTE]
> See: /docs/getting-started/integrations/icons/nuxt
>
> Procurando pela versão **Nuxt**?

## Uso

### Componente de ícone

Você pode usar o componente [Icon](https://ui.nitro.news/docs/components/icon) com uma prop `name` para exibir um ícone:

```vue
<template>
  <UIcon name="i-lucide-lightbulb" class="size-5" />
</template>
```

> \[!NOTE]
>
> Você pode usar qualquer nome da coleção <https://iconify.design>{rel="&#x22;nofollow&#x22;"}. Navegue por eles facilmente em <https://icones.js.org>{rel="&#x22;nofollow&#x22;"} ou busque diretamente pelo seu assistente de IA usando a ferramenta MCP [`search_icons`](https://ui.nitro.news/docs/getting-started/ai/mcp#available-tools).

> \[!WARNING]
>
> Ao usar coleções com um hífen (`-`), você precisa separar o nome do ícone do nome da coleção com dois-pontos (`:`), pois o `@iconify/vue` não trata esse caso como o `@nuxt/icon`. Por exemplo, em vez de `i-simple-icons-github`, você precisa escrever `i-simple-icons:github` ou `simple-icons:github`.
>
> Learn more about the [Iconify naming convention](https://iconify.design/docs/icon-components/vue/#icon){rel="&#x22;nofollow&#x22;"}.

### Props do componente

Alguns componentes também têm uma prop `icon` para exibir um ícone, como o [Button](https://ui.nitro.news/docs/components/button), por exemplo:

```vue
<template>
  <UButton icon="i-lucide-sun" variant="subtle">
    Button
  </UButton>
</template>
```

## Coleções

### Conjunto de dados do Iconify

É altamente recomendado instalar os dados dos ícones localmente com:

```bash [pnpm]
pnpm i @iconify-json/{collection_name}
```

```bash [yarn]
yarn add @iconify-json/{collection_name}
```

```bash [npm]
npm install @iconify-json/{collection_name}
```

Por exemplo, para usar o ícone `i-lucide-lightbulb`, instale sua coleção com `@iconify-json/lucide`.

Instalar a coleção permite que o Nitro UI embuta os ícones que usa no seu build, para que sejam renderizados imediatamente durante o SSR e funcionem totalmente offline, em vez de serem buscados na API do Iconify em tempo de execução. Isso acontece automaticamente para os ícones próprios do Nitro UI, da coleção `lucide` por padrão.

Para empacotar outros ícones, como os que você sobrescreve ou usa em outros lugares do seu app, adicione-os à opção `icon.clientBundle.icons` no seu `vite.config.ts`:

```ts [vite.config.ts]
import ui from '@nitro/ui/vite'

export default defineConfig({
  plugins: [
    ui({
      icon: {
        clientBundle: {
          icons: ['lucide:heart', 'simple-icons:github']
        }
      }
    })
  ]
})
```

> \[!NOTE]
>
> Você pode usar tanto o formato `i-{collection}-{name}` quanto `{collection}:{name}`, por exemplo `i-lucide-heart` ou `lucide:heart`, e `i-material-symbols-menu` ou `material-symbols:menu`. Instale cada coleção que você referenciar com `@iconify-json/{collection_name}`.

Para empacotar os ícones que você usa sem listá-los um a um, habilite `scan`. Ele escaneia seu código-fonte em busca de usos de ícones das suas coleções instaladas e os empacota, da mesma forma que o `clientBundle.scan` do `@nuxt/icon` funciona:

```ts [vite.config.ts]
import ui from '@nitro/ui/vite'

export default defineConfig({
  plugins: [
    ui({
      icon: {
        clientBundle: {
          scan: true
        }
      }
    })
  ]
})
```

Os ícones cuja coleção não está instalada ainda são carregados da API do Iconify em tempo de execução, então instale cada coleção que você usa com `@iconify-json/{collection_name}`. Para desativar o empacotamento por completo, defina `icon.clientBundle` como `false`.

## Tema

Você pode alterar os ícones padrão usados pelos componentes do Nitro UI no seu `vite.config.ts`:

*See the interactive theme picker on the documentation website.*


# Fontes

## Uso

O Nitro UI registra automaticamente o módulo [`@nuxt/fonts`](https://github.com/nuxt/fonts){rel="&#x22;nofollow&#x22;"} para você, então nenhuma configuração adicional é necessária.

### Declaração

Para usar uma fonte na sua aplicação Nitro UI, basta declará-la no seu CSS. Ela será carregada e otimizada automaticamente para você.

```css [app/assets/css/main.css]
@import "tailwindcss";
@import "@nitro/ui";

@theme {
  --font-sans: 'Public Sans', sans-serif;
}
```

### Configuração

Você pode desabilitar o módulo `@nuxt/fonts` com a opção `ui.fonts` no seu `nuxt.config.ts`:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  ui: {
    fonts: false
  }
})
```


# Modo de cor

> \[!NOTE]
> See: /docs/getting-started/integrations/color-mode/vue
>
> Procurando pela versão **Vue**?

## Uso

O Nitro UI registra automaticamente o módulo [`@nuxtjs/color-mode`](https://github.com/nuxt-modules/color-mode){rel="&#x22;nofollow&#x22;"} para você, então nenhuma configuração adicional é necessária.

### Componentes

Você pode usar os componentes integrados [ColorModeAvatar](https://ui.nitro.news/docs/components/color-mode-avatar) ou [ColorModeImage](https://ui.nitro.news/docs/components/color-mode-image) para exibir imagens diferentes nos modos claro e escuro, e os componentes [ColorModeButton](https://ui.nitro.news/docs/components/color-mode-button), [ColorModeSwitch](https://ui.nitro.news/docs/components/color-mode-switch) ou [ColorModeSelect](https://ui.nitro.news/docs/components/color-mode-select) para alternar entre os modos claro e escuro.

Você também pode usar o composable [useColorMode](https://color-mode.nuxtjs.org/#usage){rel="&#x22;nofollow&#x22;"} para construir seu próprio componente personalizado:

```vue [ColorModeButton.vue]
<script setup lang="ts">
const colorMode = useColorMode()

const isDark = computed({
  get() {
    return colorMode.value === 'dark'
  },
  set(_isDark) {
    colorMode.preference = _isDark ? 'dark' : 'light'
  }
})
</script>

<template>
  <ClientOnly v-if="!colorMode?.forced">
    <NButton
      :icon="isDark ? 'i-lucide-moon' : 'i-lucide-sun'"
      color="neutral"
      variant="ghost"
      :aria-label="`Switch to ${isDark ? 'light' : 'dark'} mode`"
      @click="isDark = !isDark"
    />

    <template #fallback>
      <div class="size-8" />
    </template>
  </ClientOnly>
</template>
```

### Configuração

Você pode desabilitar o módulo `@nuxtjs/color-mode` com a opção `ui.colorMode` no seu `nuxt.config.ts`:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nitro/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    colorMode: false
  }
})
```


# Modo de cor

> \[!NOTE]
> See: /docs/getting-started/integrations/color-mode/nuxt
>
> Procurando pela versão **Nuxt**?

## Uso

O Nitro UI registra automaticamente o composable [useDark](https://vueuse.org/core/useDark){rel="&#x22;nofollow&#x22;"} como um plugin do Vue, então nenhuma configuração adicional é necessária.

### Componentes

Você pode usar os componentes integrados [ColorModeAvatar](https://ui.nitro.news/docs/components/color-mode-avatar) ou [ColorModeImage](https://ui.nitro.news/docs/components/color-mode-image) para exibir imagens diferentes nos modos claro e escuro, e os componentes [ColorModeButton](https://ui.nitro.news/docs/components/color-mode-button), [ColorModeSwitch](https://ui.nitro.news/docs/components/color-mode-switch) ou [ColorModeSelect](https://ui.nitro.news/docs/components/color-mode-select) para alternar entre os modos claro e escuro.

Você também pode usar o composable [useColorMode](https://vueuse.org/core/useColorMode){rel="&#x22;nofollow&#x22;"} para construir seu próprio componente personalizado:

```vue [ColorModeButton.vue]
<script setup lang="ts">
import { useColorMode } from '@vueuse/core'

const colorMode = useColorMode()

const isDark = computed({
  get() {
    return colorMode.value === 'dark'
  },
  set(_isDark: boolean) {
    colorMode.preference = _isDark ? 'dark' : 'light'
  }
})
</script>

<template>
  <NButton
    :icon="isDark ? 'i-lucide-moon' : 'i-lucide-sun'"
    :color="color"
    :variant="variant"
    :aria-label="`Switch to ${isDark ? 'light' : 'dark'} mode`"
    @click="isDark = !isDark"
  />
</template>
```

### Configuração

Você pode desabilitar esse plugin com a opção `colorMode` no seu `vite.config.ts`:

```ts [vite.config.ts]
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nitro/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      colorMode: false
    })
  ]
})
```


# Internacionalização (i18n)

> \[!NOTE]
> See: /docs/getting-started/integrations/i18n/vue
>
> Procurando pela versão **Vue**?

## Uso

> \[!NOTE]
> See: /docs/components/app
>
> O Nitro UI fornece um componente **App** que envolve seu app para fornecer configurações globais, incluindo a prop `locale`.

### Locale

Use a prop `locale` com o locale que você quer usar de `@nitro/ui/locale`:

```vue [app.vue]
<script setup lang="ts">
import { fr } from '@nitro/ui/locale'
</script>

<template>
  <NApp :locale="fr">
    <NuxtPage />
  </NApp>
</template>
```

> \[!TIP]
>
> Cada locale tem uma propriedade `code` (ex.: `en`, `en-GB`, `fr`) que determina o formato de data/hora em componentes como [Calendar](https://ui.nitro.news/docs/components/calendar), [InputDate](https://ui.nitro.news/docs/components/input-date) e [InputTime](https://ui.nitro.news/docs/components/input-time).

### Locale personalizado

Você pode criar seu próprio locale usando o utilitário [defineLocale](https://ui.nitro.news/docs/composables/define-locale):

```vue [app.vue]
<script setup lang="ts">
import type { Messages } from '@nitro/ui'

const locale = defineLocale<Messages>({
  name: 'My custom locale',
  code: 'en',
  dir: 'ltr',
  messages: {
    // implement pairs
  }
})
</script>

<template>
  <NApp :locale="locale">
    <NuxtPage />
  </NApp>
</template>
```

> \[!TIP]
>
> Observe o parâmetro `code`; nele você precisa passar o código ISO do idioma. Exemplo:
>
> - `hi` Hindi (language)
> - `de-AT`: German (language) as used in Austria (region)

### Estender o locale

Você pode personalizar um locale existente sobrescrevendo suas `messages` ou seu `code` usando o utilitário [extendLocale](https://ui.nitro.news/docs/composables/extend-locale):

```vue [app.vue]
<script setup lang="ts">
import { en } from '@nitro/ui/locale'

const locale = extendLocale(en, {
  code: 'en-AU',
  messages: {
    commandPalette: {
      placeholder: 'Search a component...'
    }
  }
})
</script>

<template>
  <NApp :locale="locale">
    <NuxtPage />
  </NApp>
</template>
```

### Locale dinâmico

Para alternar dinamicamente entre idiomas, você pode usar o módulo [Nuxt I18n](https://i18n.nuxtjs.org/){rel="&#x22;nofollow&#x22;"}.

#### Instale o pacote Nuxt I18n

```bash [pnpm]
pnpm add @nuxtjs/i18n
```

```bash [yarn]
yarn add @nuxtjs/i18n
```

```bash [npm]
npm install @nuxtjs/i18n
```

```bash [bun]
bun add @nuxtjs/i18n
```

#### Adicione o módulo Nuxt I18n no seu `nuxt.config.ts`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: [
    '@nitro/ui',
    '@nuxtjs/i18n'
  ],
  css: ['~/assets/css/main.css'],
  i18n: {
    locales: [{
      code: 'de',
      name: 'Deutsch'
    }, {
      code: 'en',
      name: 'English'
    }, {
      code: 'fr',
      name: 'Français'
    }]
  }
})
```

#### Defina a prop `locale` usando `useI18n`

```vue [app.vue]
<script setup lang="ts">
import * as locales from '@nitro/ui/locale'

const { locale } = useI18n()
</script>

<template>
  <NApp :locale="locales[locale]">
    <NuxtPage />
  </NApp>
</template>
```

#### Localização automática de links `4.7+`

Quando o `@nuxtjs/i18n` está instalado, o componente [Link](https://ui.nitro.news/docs/components/link) localiza automaticamente os links internos usando o helper `$localePath`. Isso significa que você não precisa envolver manualmente seus links com `localePath()` ou `localeRoute()`.

```vue
<template>
  <!-- Automatically becomes /en/about or /fr/about based on current locale -->
  <NLink to="/about">About</NLink>
  <NButton to="/contact">Contact</NButton>
</template>
```

> \[!TIP]
>
> Links externos e URLs absolutas são detectados automaticamente e ignoram a localização. Você ainda pode usar `localePath()` ou `localeRoute()` manualmente se necessário.

### Direção dinâmica

Cada locale tem uma propriedade `dir` que será usada pelo componente `App` para definir a direcionalidade de todos os componentes.

Em uma aplicação multilíngue, você pode querer definir os atributos `lang` e `dir` no elemento `<html>` dinamicamente com base no locale do usuário, o que você pode fazer com o composable [useHead](https://nuxt.com/docs/api/composables/use-head){rel="&#x22;nofollow&#x22;"}:

```vue [app.vue]
<script setup lang="ts">
import * as locales from '@nitro/ui/locale'

const { locale } = useI18n()

const lang = computed(() => locales[locale.value].code)
const dir = computed(() => locales[locale.value].dir)

useHead({
  htmlAttrs: {
    lang,
    dir
  }
})
</script>

<template>
  <NApp :locale="locales[locale]">
    <NuxtPage />
  </NApp>
</template>
```

## Idiomas suportados

*See the full list of supported languages on the documentation website.*


# Internacionalização (i18n)

> \[!NOTE]
> See: /docs/getting-started/integrations/i18n/nuxt
>
> Procurando pela versão **Nuxt**?

## Uso

> \[!NOTE]
> See: /docs/components/app
>
> O Nitro UI fornece um componente **App** que envolve seu app para fornecer configurações globais, incluindo a prop `locale`.

### Locale

Use a prop `locale` com o locale que você quer usar de `@nitro/ui/locale`:

```vue [App.vue]
<script setup lang="ts">
import { fr } from '@nitro/ui/locale'
</script>

<template>
  <NApp :locale="fr">
    <RouterView />
  </NApp>
</template>
```

> \[!TIP]
>
> Cada locale tem uma propriedade `code` (ex.: `en`, `en-GB`, `fr`) que determina o formato de data/hora em componentes como [Calendar](https://ui.nitro.news/docs/components/calendar), [InputDate](https://ui.nitro.news/docs/components/input-date) e [InputTime](https://ui.nitro.news/docs/components/input-time).

### Locale personalizado

Você pode criar seu próprio locale usando o utilitário [defineLocale](https://ui.nitro.news/docs/composables/define-locale):

```vue [App.vue]
<script setup lang="ts">
import type { Messages } from '@nitro/ui'
import { defineLocale } from '@nitro/ui/composables'

const locale = defineLocale<Messages>({
  name: 'My custom locale',
  code: 'en',
  dir: 'ltr',
  messages: {
    // implement pairs
  }
})
</script>

<template>
  <NApp :locale="locale">
    <RouterView />
  </NApp>
</template>
```

> \[!TIP]
>
> Observe o parâmetro `code`; nele você precisa passar o código ISO do idioma. Exemplo:
>
> - `hi` Hindi (language)
> - `de-AT`: German (language) as used in Austria (region)

### Estender o locale

Você pode personalizar um locale existente sobrescrevendo suas `messages` ou seu `code` usando o utilitário [extendLocale](https://ui.nitro.news/docs/composables/extend-locale):

```vue [App.vue]
<script setup lang="ts">
import { en } from '@nitro/ui/locale'
import { extendLocale } from '@nitro/ui/composables'

const locale = extendLocale(en, {
  code: 'en-AU',
  messages: {
    commandPalette: {
      placeholder: 'Search a component...'
    }
  }
})
</script>

<template>
  <NApp :locale="locale">
    <RouterView />
  </NApp>
</template>
```

### Locale dinâmico

Para alternar dinamicamente entre idiomas, você pode usar o plugin [Vue I18n](https://vue-i18n.intlify.dev/){rel="&#x22;nofollow&#x22;"}.

#### Instale o pacote Vue I18n

```bash [pnpm]
pnpm add vue-i18n@11
```

```bash [yarn]
yarn add vue-i18n@11
```

```bash [npm]
npm install vue-i18n@11
```

```bash [bun]
bun add vue-i18n@11
```

#### Use o plugin Vue I18n no seu `main.ts`

```ts [src/main.ts] {3,14-26,29}
import { createApp } from 'vue'
import { createRouter, createWebHistory } from 'vue-router'
import { createI18n } from 'vue-i18n'
import ui from '@nitro/ui/vue-plugin'
import App from './App.vue'

const app = createApp(App)

const router = createRouter({
  routes: [],
  history: createWebHistory()
})

const i18n = createI18n({
  legacy: false,
  locale: 'en',
  availableLocales: ['en', 'de'],
  messages: {
    en: {
      // ...
    },
    de: {
      // ...
    }
  }
})

app.use(router)
app.use(i18n)
app.use(ui)

app.mount('#app')
```

#### Defina a prop `locale` usando `useI18n`

```vue [App.vue]
<script setup lang="ts">
import { useI18n } from 'vue-i18n'
import * as locales from '@nitro/ui/locale'

const { locale } = useI18n()
</script>

<template>
  <NApp :locale="locales[locale]">
    <RouterView />
  </NApp>
</template>
```

### Direção dinâmica

Cada locale tem uma propriedade `dir` que será usada pelo componente `App` para definir a direcionalidade de todos os componentes.

Em uma aplicação multilíngue, você pode querer definir os atributos `lang` e `dir` no elemento `<html>` dinamicamente com base no locale do usuário, o que você pode fazer com o composable [useHead](https://unhead.unjs.io/usage/composables/use-head){rel="&#x22;nofollow&#x22;"}:

```vue [App.vue]
<script setup lang="ts">
import { computed } from 'vue'
import { useI18n } from 'vue-i18n'
import { useHead } from '@unhead/vue'
import * as locales from '@nitro/ui/locale'

const { locale } = useI18n()

const lang = computed(() => locales[locale.value].code)
const dir = computed(() => locales[locale.value].dir)

useHead({
  htmlAttrs: {
    lang,
    dir
  }
})
</script>

<template>
  <NApp :locale="locales[locale]">
    <RouterView />
  </NApp>
</template>
```

## Idiomas suportados

*See the full list of supported languages on the documentation website.*


# Content

## Instalação

Para começar, você pode seguir o [guia](https://content.nuxt.com/docs/getting-started/installation){rel="&#x22;nofollow&#x22;"} oficial ou, em resumo:

```bash [pnpm]
pnpm add @nuxt/content
```

```bash [yarn]
yarn add @nuxt/content
```

```bash [npm]
npm install @nuxt/content
```

```bash [bun]
bun add @nuxt/content
```

Depois, adicione o módulo `@nuxt/content` no seu `nuxt.config.ts`:

```ts [nuxt.config.ts] {4}
export default defineNuxtConfig({
  modules: [
    '@nitro/ui',
    '@nuxt/content'
  ],
  css: ['~/assets/css/main.css']
})
```

> \[!CAUTION]
>
> Você precisa registrar o `@nuxt/content` depois do `@nitro/ui` no array `modules`, caso contrário os componentes de prose não estarão disponíveis.

## Configuração

Ao usar classes do Tailwind CSS nos seus arquivos de conteúdo markdown, você precisa garantir que o Tailwind consiga detectar e gerar as classes utilitárias necessárias. Por padrão, a detecção automática de conteúdo do Tailwind pode não captar as classes escritas em arquivos markdown.

Para corrigir isso, use a [diretiva `@source`](https://tailwindcss.com/docs/functions-and-directives#source-directive){rel="&#x22;nofollow&#x22;"} no seu arquivo CSS para incluir explicitamente o diretório de conteúdo:

```css [app/assets/css/main.css]
@import "tailwindcss";
@import "@nitro/ui";

@source "../../../content/**/*";
```

Isso garante que:

- Tailwind scans all markdown files in your content directory
- Any utility classes used in your markdown (like `text-primary`) are included in the final CSS
- Dynamic classes in MDC components or custom Vue components within your content work properly

> \[!TIP]
>
> Você também pode usar padrões glob para ser mais específico sobre quais arquivos escanear:
>
> - `@source "../../../content/docs/**/*.md"` - Only scan markdown in the docs folder
> - `@source "../../../content/**/*.{md,yml}"` - Include both markdown and YAML files

> \[!NOTE]
> See: https\://tailwindcss.com/docs/detecting-classes-in-source-files
>
> Saiba mais sobre a detecção automática de conteúdo do Tailwind e as boas práticas para otimizar o desempenho do build.

## Componentes

Você pode estar usando o `@nuxt/content` para construir uma documentação. Para ajudar você com isso, criamos alguns componentes que você pode usar nas suas páginas:

- a built-in full-text search command palette with [ContentSearch](https://ui.nitro.news/docs/components/content-search), replacing the need for Algolia DocSearch
- a navigation tree with the [ContentNavigation](https://ui.nitro.news/docs/components/content-navigation) component
- a sticky Table of Contents with the [ContentToc](https://ui.nitro.news/docs/components/content-toc) component
- a prev / next navigation with the [ContentSurround](https://ui.nitro.news/docs/components/content-surround) component

## Typography

O Nitro UI fornece suas próprias implementações personalizadas de todos os componentes de prose para uma integração perfeita com o `@nuxt/content`. Essa abordagem garante estilização consistente, controle total sobre a tipografia e alinhamento perfeito com o design system do Nitro UI, para que seu conteúdo sempre pareça coeso desde o início.

> \[!NOTE]
> See: /docs/typography
>
> Conheça o sistema completo de **Tipografia** e explore todos os componentes de prose disponíveis para uma apresentação de conteúdo rica e consistente.

## Utilitários

### `mapContentNavigation`

Este utilitário mapeará a navegação de `queryCollectionNavigation` e a transformará recursivamente em um array de objetos que pode ser usado por vários componentes.

`mapContentNavigation(navigation, options?)`

- `navigation`: The navigation tree (array of ContentNavigationItem).
- `options`(optional):
  - `labelAttribute`: (string) Which field to use as label (`title` by default)
  - `deep`: (number or undefined) Controls how many levels of navigation are included (`undefined` by default : includes all levels)

**Example:** As shown in the breadcrumb example below, it's commonly used to transform the navigation data into the correct format.

```vue [app.vue]
<script setup lang="ts">
import { mapContentNavigation } from '@nitro/ui/utils/content'
import { findPageBreadcrumb } from '@nuxt/content/utils'

const { data: navigation } = await useAsyncData('navigation', () => queryCollectionNavigation('content'))

const breadcrumb = computed(() => mapContentNavigation(findPageBreadcrumb(navigation?.value, page.value?.path, { indexAsChild: true })).map(({ icon, ...link }) => link), { deep: 0 })
</script>

<template>
  <NPage>
    <NPageHeader v-bind="page">
      <template #headline>
        <NBreadcrumb :items="breadcrumb" />
      </template>
    </NPageHeader>
  </NPage>
</template>
```


# SSR

## Uso

Ao usar o Nitro UI com o framework Nuxt, o SSR do servidor funcionará totalmente por padrão. No entanto, ao usá-lo com Vue puro, você precisará prestar atenção a alguns detalhes para que funcione como esperado.

### Injeção de variáveis de cor

Por padrão, o Nitro UI injeta no `<head>` do documento as variáveis de cor usadas por todos os componentes. Como o documento não é gerenciado pela biblioteca de UI no SSR do Vue, você precisará injetá-las manualmente.

Você pode fazer isso usando o `@unhead` da seguinte forma:

```ts [ssr.ts]
import { createHead, renderSSRHead } from '@unhead/vue/server'

// Create the header with unhead
const head = createHead()

// Render SSR header and append it to the SSR application instance
const payload = await renderSSRHead(head)
app.head.push(payload.headTags)
```

```ts [resources/js/ssr.ts (Laravel Inertia)] {4,14,27,29-33}
import { createInertiaApp } from '@inertiajs/vue3'
import createServer from '@inertiajs/vue3/server'
import ui from '@nitro/ui/vue-plugin'
import { createHead, renderSSRHead } from '@unhead/vue/server'
import { resolvePageComponent } from 'laravel-vite-plugin/inertia-helpers'
import { createSSRApp, h } from 'vue'
import { renderToString } from 'vue/server-renderer'
import type { DefineComponent } from 'vue'

const appName = import.meta.env.VITE_APP_NAME || 'Laravel x Nitro UI'

createServer(
  (page) => {
    const head = createHead()
    return createInertiaApp({
      page,
      render: renderToString,
      title: (title) => (title ? `${title} - ${appName}` : appName),
      resolve: (name) =>
        resolvePageComponent(
          `./pages/${name}.vue`,
          import.meta.glob<DefineComponent>('./pages/**/*.vue')
        ),
      setup: ({ App, props, plugin }) =>
        createSSRApp({ render: () => h(App, props) })
          .use(plugin)
          .use(head)
          .use(ui)
    }).then(async (app) => {
      const payload = await renderSSRHead(head)
      app.head.push(payload.headTags)
      return app
    })
  },
  { cluster: true }
)
```

```ts [inertia/app/ssr.ts (AdonisJS Inertia)] {4,14,27,29-33}
import { createInertiaApp } from '@inertiajs/vue3'
import createServer from '@inertiajs/vue3/server'
import ui from '@nitro/ui/vue-plugin'
import { createHead, renderSSRHead } from '@unhead/vue/server'
import { resolvePageComponent } from '@adonisjs/inertia/helpers'
import { createSSRApp, h } from 'vue'
import { renderToString } from 'vue/server-renderer'
import type { DefineComponent } from 'vue'

const appName = import.meta.env.VITE_APP_NAME || 'AdonisJS x Nitro UI'

createServer(
  (page) => {
    const head = createHead()
    return createInertiaApp({
      page,
      render: renderToString,
      title: (title) => (title ? `${title} - ${appName}` : appName),
      resolve: (name) =>
        resolvePageComponent(
          `../pages/${name}.vue`,
          import.meta.glob<DefineComponent>('../pages/**/*.vue')
        ),
      setup: ({ App, props, plugin }) =>
        createSSRApp({ render: () => h(App, props) })
          .use(plugin)
          .use(head)
          .use(ui)
    }).then(async (app) => {
      const payload = await renderSSRHead(head)
      app.head.push(payload.headTags)
      return app
    })
  },
  { cluster: true }
)
```

### Detecção de esquema de cores

O mesmo vale para a detecção do esquema de cores. Para evitar piscadas no SSR por causa da diferença do esquema de cores selecionado, você precisará detectar o esquema de cores do usuário antes da inicialização da aplicação.

Adicionar o script abaixo ao `<head>` do seu documento detectará se o usuário está usando o tema escuro e, portanto, renderizará o SSR também no tema escuro.

```html [index.html]
<script>
const theme = localStorage.getItem('vueuse-color-scheme') || 'auto'
if (theme === 'dark' || (theme === 'auto' && window.matchMedia('(prefers-color-scheme: dark)').matches)) {
  document.documentElement.classList.add('dark')
} else {
  document.documentElement.classList.remove('dark')
}
</script>
```

```html [resources/views/app.blade.php (Laravel Inertia)] {8-15}
<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1">
    @inertiaHead
    @vite('resources/js/app.ts')
    <script>
      const theme = localStorage.getItem('vueuse-color-scheme') || 'auto'
      if (theme === 'dark' || (theme === 'auto' && window.matchMedia('(prefers-color-scheme: dark)').matches)) {
        document.documentElement.classList.add('dark')
      } else {
        document.documentElement.classList.remove('dark')
      }
    </script>
  </head>
  <body>
    <div class="isolate">
      @inertia
    </div>
  </body>
</html>
```

```html [resources/views/inertia_layout.edge (AdonisJS Inertia)] {8-15}
<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1">
    @inertiaHead()
    @vite(['inertia/app/app.ts', `inertia/pages/${page.component}.vue`])
    <script>
      const theme = localStorage.getItem('vueuse-color-scheme') || 'auto'
      if (theme === 'dark' || (theme === 'auto' && window.matchMedia('(prefers-color-scheme: dark)').matches)) {
        document.documentElement.classList.add('dark')
      } else {
        document.documentElement.classList.remove('dark')
      }
    </script>
  </head>
  <body>
    @inertia({ class: 'isolate' })
  </body>
</html>
```

### Exibição de ícones

O Nitro UI empacota os ícones que usa no seu build, então eles são renderizados durante o SSR e funcionam totalmente offline assim que você instala a coleção de ícones localmente, sem nenhuma requisição à API do Iconify. Veja a integração de [Ícones](https://ui.nitro.news/docs/getting-started/integrations/icons/vue#collections) para configurar isso e empacotar seus próprios ícones.


# Servidor MCP

## O que é o MCP?

O MCP (Model Context Protocol) é um protocolo padronizado que permite a assistentes de IA acessarem fontes de dados e ferramentas externas. O Nitro UI fornece um servidor MCP que permite a assistentes de IA como Claude Code, Cursor e Windsurf acessarem diretamente informações dos componentes, código-fonte e exemplos de uso.

O servidor MCP fornece acesso estruturado à nossa biblioteca de componentes, facilitando que ferramentas de IA entendam e auxiliem no desenvolvimento com o Nitro UI.

## Recursos disponíveis

O servidor MCP do Nitro UI fornece os seguintes recursos para descoberta:

- **`resource://nuxt-ui/components`**: Browse all available components with categories
- **`resource://nuxt-ui/composables`**: Browse all available composables with categories
- **`resource://nuxt-ui/examples`**: Browse all available code examples
- **`resource://nuxt-ui/templates`**: Browse all available project templates
- **`resource://nuxt-ui/documentation-pages`**: Browse all available documentation pages

Você pode acessar esses recursos com ferramentas como o Claude Code usando `@`.

## Ferramentas disponíveis

O servidor MCP do Nitro UI fornece as seguintes ferramentas organizadas por categoria:

### Ferramentas de busca

- **`search_components`**: Search components by name, description, or category. With no params, lists all components
- **`search_composables`**: Search composables by name or description. With no params, lists all composables
- **`search_icons`**: Search for icons across Iconify collections (defaults to `lucide`). Returns icon names in the `i-{prefix}-{name}` format used by Nitro UI

### Ferramentas de componente

- **`get_component`**: Retrieves component documentation and details. Supports a `sections` parameter (`usage`, `examples`, `api`, `theme`, `changelog`) to fetch only specific parts and reduce response size
- **`get_component_metadata`**: Retrieves detailed metadata for a component including props, slots, and events (lightweight, no documentation content)

### Ferramentas de documentação

- **`search_documentation`**: Search documentation pages by title, description, or section. With no params, lists all pages. Use `section` to filter (e.g., `"getting-started"`, `"components"`)
- **`get_documentation_page`**: Retrieves documentation page content by URL path. Supports a `headings` parameter to fetch only specific h2 sections (e.g., `["Usage", "API"]`) and reduce response size

### Ferramentas de exemplo

- **`list_examples`**: Lists all available UI examples and code demonstrations
- **`get_example`**: Retrieves specific UI example implementation code and details

## Prompts disponíveis

O servidor MCP do Nitro UI fornece prompts guiados para fluxos de trabalho comuns:

- **`find_component_for_usecase`**: Find the best component for your specific use case
- **`implement_component_with_props`**: Generate complete component implementation with proper props
- **`setup_project_with_template`**: Get guided setup instructions for project templates

Você pode acessar esses recursos com ferramentas como o Claude Code usando `/`.

## Configuração

O servidor MCP do Nitro UI usa transporte HTTP e pode ser configurado em diferentes assistentes de IA.

### ChatGPT

> \[!NOTE]
>
> **Custom connectors using MCP are available on ChatGPT for Pro and Plus accounts.** Accessible on the web.

Siga estas etapas para configurar o Nitro UI como um conector dentro do ChatGPT:

1. **Enable Developer mode:**
   - Go to "Settings" > "Connectors" > "Advanced settings" > "Developer mode"
2. **Open ChatGPT settings**
3. **Na aba Connectors, crie um novo conector:**
   - Give it a name: `Nitro UI`
   - MCP server URL: `https://ui.nitro.news/mcp`
   - Authentication: `None`
4. **Click Create**

O conector do Nitro UI aparecerá na ferramenta "Developer mode" do compositor mais tarde, durante as conversas.

### Claude Code

> \[!NOTE]
>
> **Ensure Claude Code is installed.** Visit [Anthropic's documentation](https://docs.anthropic.com/en/docs/claude-code/quickstart){rel="&#x22;nofollow&#x22;"} for installation instructions.

Adicione o servidor usando o comando da CLI:

```bash
claude mcp add --transport http nuxt-ui-remote https://ui.nitro.news/mcp
```

### Claude Desktop

#### Instruções de configuração:

1. Abra o Claude Desktop e navegue até "Settings" > "Developer".
2. Clique em "Edit Config". Isso abrirá o diretório local do Claude.
3. Modifique o arquivo `claude_desktop_config.json` com a sua configuração personalizada do servidor MCP.

```json [claude_desktop_config.json]
{
  "mcpServers": {
    "nuxt-ui": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://ui.nitro.news/mcp"
      ]
    }
  }
}
```

4. Reinicie o aplicativo Claude Desktop. O servidor MCP do Nitro UI deve estar registrado agora.

### Cursor

#### Instalação rápida:

Clique no botão abaixo para instalar o servidor MCP do Nitro UI diretamente no Cursor:

[Install MCP Server](cursor://anysphere.cursor-deeplink/mcp/install?name=nuxt-ui&config=eyJ0eXBlIjoiaHR0cCIsInVybCI6Imh0dHBzOi8vdWkubnV4dC5jb20vbWNwIn0%3D)

#### Instruções de configuração manual:

1. Abra o Cursor e vá em "Settings" > "Tools & MCP"
2. Add the Nitro UI MCP server configuration

Ou crie/atualize manualmente o `.cursor/mcp.json` na raiz do seu projeto:

```json [.cursor/mcp.json]
{
  "mcpServers": {
    "nuxt-ui": {
      "type": "http",
      "url": "https://ui.nitro.news/mcp"
    }
  }
}
```

### Gemini CLI

#### Instruções de configuração:

1. Localize o arquivo de configuração da sua Gemini CLI (geralmente \~/.gemini/settings.json ou conforme especificado no seu ambiente).
2. Adicione a seguinte configuração ao seu objeto mcpServers:

```json [~/.gemini/settings.json]
{
  "mcpServers": {
    "nuxt-ui": {
      "url": "https://ui.nitro.news/mcp"
    }
  }
}
```

3. Reinicie a sessão do seu terminal ou recarregue a CLI. As ferramentas do servidor MCP do Nitro UI agora estarão disponíveis para uso.

### GitHub Copilot Agent

> \[!NOTE]
>
> **Repository administrator access required.** This is needed to configure MCP servers for GitHub Copilot coding agent.

Se você já configurou servidores MCP no [Visual Studio Code](https://ui.nitro.news/#visual-studio-code), substitua a chave `servers` por `mcpServers` e adicione uma chave `tools` especificando quais ferramentas estão disponíveis para o Copilot.

#### Instruções de configuração:

1. Navegue até o seu repositório do GitHub
2. Go to **Settings** > **Code & automation** > **Copilot** > **Coding agent**
3. Na seção **MCP configuration**, adicione a seguinte configuração:

```json
{
  "mcpServers": {
    "nuxt-ui": {
      "type": "http",
      "url": "https://ui.nitro.news/mcp",
      "tools": ["*"]
    }
  }
}
```

4. Click Save

#### Validando a configuração:

Para verificar se o servidor MCP está configurado corretamente:

1. Crie uma issue no seu repositório e atribua-a ao Copilot
2. Aguarde o Copilot criar um pull request
3. No pull request, clique em View session no evento da timeline "Copilot started work"
4. Clique no botão de reticências (...) no canto superior direito e depois clique em Copilot na barra lateral
5. Expanda a etapa Start MCP Servers para ver as ferramentas do Nuxt configuradas

Para mais informações sobre o uso de MCP com o agente de programação do GitHub Copilot, veja [Extend coding agent with MCP](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/extend-coding-agent-with-mcp){rel="&#x22;nofollow&#x22;"}.

### GitHub Copilot CLI

#### Instruções de configuração:

1. Start GitHub Copilot CLI in interactive mode.
2. Run `/mcp add`.
3. Preencha o formulário de configuração com:
   - **Server Name**: `nuxt-ui`
   - **Server Type**: `HTTP`
   - **URL**: `https://ui.nitro.news/mcp`
   - **HTTP Headers**: leave empty
   - **Tools**: `*`
4. Pressione :kbd[Ctrl] + :kbd[S] para salvar. O servidor MCP fica disponível imediatamente, sem reiniciar a CLI.

Ou adicione o servidor diretamente ao `~/.copilot/mcp-config.json`:

```json [~/.copilot/mcp-config.json]
{
  "mcpServers": {
    "nuxt-ui": {
      "type": "http",
      "url": "https://ui.nitro.news/mcp",
      "tools": ["*"]
    }
  }
}
```

Use `/mcp show` para confirmar que o servidor está configurado e disponível.

Para mais detalhes, veja [Adding MCP servers for GitHub Copilot CLI](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers){rel="&#x22;nofollow&#x22;"}.

### Google Antigravity

#### Instruções de configuração:

1. Abra a loja de MCP pelo menu "..." no topo do painel do agente do editor.
2. Click on "Manage MCP Servers"
3. Click on "View raw config"
4. Modifique o `mcp_config.json` com a sua configuração personalizada do servidor MCP:

```json [mcp_config.json]
{
  "mcpServers": {
    "nuxt-ui": {
      "serverUrl": "https://ui.nitro.news/mcp"
    }
  }
}
```

5. Volte para a aba "Manage MCP Servers" e clique em "Refresh". O servidor MCP do Nitro UI deve aparecer agora.

### Le Chat Mistral

#### Instruções de configuração:

1. Navigate to "Intelligence" > "Connectors"
2. Click on "Add Connector" button, then select "Custom MCP Connector"
3. Create your Custom MCP Connector:
   - Connector Name: `NuxtUI`
   - Connector Server: `https://ui.nitro.news/mcp`

### OpenCode

#### Instruções de configuração:

1. Na raiz do seu projeto, crie `opencode.json`
2. Add the following configuration:

```json [opencode.json]
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "nuxt-ui": {
      "type": "remote",
      "url": "https://ui.nitro.news/mcp",
      "enabled": true
    }
  }
}
```

### Visual Studio Code

> \[!NOTE]
>
> **Install required extensions.** Ensure you have [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot){rel="&#x22;nofollow&#x22;"} and [GitHub Copilot Chat](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot-chat){rel="&#x22;nofollow&#x22;"} extensions installed.

#### Instruções de configuração:

1. Abra o VS Code e acesse a Paleta de Comandos (Ctrl/Cmd + Shift + P)
2. Digite "Preferences: Open Workspace Settings (JSON)" e selecione
3. Navegue até a pasta `.vscode` do seu projeto ou crie uma se ela não existir
4. Crie ou edite o arquivo `mcp.json` com a seguinte configuração:

```json [.vscode/mcp.json]
{
  "servers": {
    "nuxt-ui": {
      "type": "http",
      "url": "https://ui.nitro.news/mcp"
    }
  }
}
```

### Windsurf

#### Instruções de configuração:

1. Abra o Windsurf e navegue até "Settings" > "Windsurf Settings" > "Cascade"
2. Clique no botão "Manage MCPs" e selecione a opção "View raw config"
3. Adicione a seguinte configuração às suas configurações de MCP:

```json [.codeium/windsurf/mcp_config.json]
{
  "mcpServers": {
    "nuxt-ui": {
      "type": "http",
      "url": "https://ui.nitro.news/mcp"
    }
  }
}
```

### Zed

#### Instruções de configuração:

1. Abra o Zed e vá em "Settings" > "Open Settings"
2. Navegue até o arquivo de configurações JSON
3. Adicione a seguinte configuração de servidor de contexto às suas configurações:

```json [.config/zed/settings.json]
{
  "context_servers": {
    "nuxt-ui": {
      "source": "custom",
      "command": "npx",
      "args": ["mcp-remote", "https://ui.nitro.news/mcp"],
      "env": {}
    }
  }
}
```

## Exemplos de uso

Uma vez configurado, você pode fazer ao seu assistente de IA perguntas como:

- "List all available Nitro UI components"
- "Get Button component documentation"
- "Show me just the Button usage examples"
- "What props does Input accept?"
- "Find form-related components"
- "Search for arrow icons in lucide"
- "List dashboard templates"
- "Get template setup instructions"
- "Show installation guide"
- "List all examples"
- "Get ContactForm example code"

O assistente de IA usará o servidor MCP para buscar dados JSON estruturados e fornecer assistência guiada para o Nitro UI durante o desenvolvimento.

> \[!TIP]
>
> Para a documentação de componentes, a IA pode usar o parâmetro `sections` (`usage`, `examples`, `api`, `theme`, `changelog`) para buscar apenas as partes relevantes. Para outras páginas, use o parâmetro `headings` com títulos h2 (ex.: `["Usage", "API"]`).


# LLMs.txt

## O que é o LLMs.txt?

LLMs.txt é um formato de documentação estruturado projetado especificamente para grandes modelos de linguagem (LLMs). O Nitro UI fornece arquivos LLMs.txt que contêm informações abrangentes sobre nossa biblioteca de componentes, facilitando que ferramentas de IA entendam e auxiliem no desenvolvimento com o Nitro UI.

Esses arquivos são otimizados para consumo por IA e contêm informações estruturadas sobre componentes, APIs, padrões de uso e boas práticas.

## Rotas disponíveis

We provide LLMs.txt routes to help AI tools access our documentation:

- **`/llms.txt`** - Contains a structured overview of all components and their documentation links (\~5K tokens)
- **`/llms-full.txt`** - Provides comprehensive documentation including implementation details, examples, theming and composables (\~1M+ tokens)

## Escolhendo o arquivo certo

> \[!NOTE]
>
> **Most users should start with `/llms.txt`** - it contains all essential information and works with standard LLM context windows. Use `/llms-full.txt` only if you need comprehensive implementation examples and your AI tool supports large contexts (200K+ tokens).

## Notas importantes de uso

> \[!WARNING]
>
> **@-symbol must be typed manually** - When using tools like Cursor or Windsurf, the `@` symbol must be typed by hand in the chat interface. Copy-pasting breaks the tool's ability to recognize it as a context reference.

## Uso com ferramentas de IA

### Cursor

O Nitro UI fornece arquivos LLMs.txt especializados que você pode referenciar no Cursor para uma melhor assistência de IA no desenvolvimento de componentes.

#### Como usar:

1. **Referência direta**: Mencione as URLs do LLMs.txt ao fazer perguntas
2. Adicione estas URLs específicas ao contexto do seu projeto usando `@docs`

[Read more about Cursor Web and Docs Search](https://docs.cursor.com/en/context/@-symbols/@-docs){rel="&#x22;nofollow&#x22;"}

### Windsurf

O Windsurf pode acessar diretamente os arquivos LLMs.txt do Nitro UI para entender o uso dos componentes e as boas práticas.

#### Usando o LLMs.txt com o Windsurf:

- Use `@docs` to reference specific LLMs.txt URLs
- Create persistent rules referencing these URLs in your workspace

[Read more about Windsurf Web and Docs Search](https://docs.windsurf.com/windsurf/cascade/web-search){rel="&#x22;nofollow&#x22;"}

### Outras ferramentas de IA

Qualquer ferramenta de IA que suporte LLMs.txt pode usar essas rotas para entender melhor o Nitro UI.

#### Exemplos para ChatGPT, Claude ou outros LLMs:

- "Using Nitro UI documentation from <https://ui.nitro.news/llms.txt>{rel="&#x22;nofollow&#x22;"}"
- "Follow complete Nitro UI guidelines from <https://ui.nitro.news/llms-full.txt>{rel="&#x22;nofollow&#x22;"}"


# Skills

## O que são Skills?

Skills são arquivos de conhecimento estruturados que dão aos agentes de IA de programação contexto sobre uma biblioteca, framework ou base de código. Diferentemente dos servidores MCP, que fornecem acesso a ferramentas em tempo real, as skills são carregadas diretamente no contexto do agente para que ele possa consultá-las ao longo da conversa.

O Nitro UI fornece uma **skill de uso** que ensina os agentes de IA a construir UIs com o Nitro UI: instalação, tematização, componentes, composables, formulários, overlays e layouts.

## Uso

A skill de uso dá aos agentes de IA um conhecimento abrangente sobre como construir com o Nitro UI v4. Ela abrange:

- Installation for Nuxt, Vue, Laravel, and AdonisJS
- Theming and branding with semantic colors and CSS variables
- All 125+ components with props and usage patterns
- Composables (`useToast`, `useOverlay`, `defineShortcuts`)
- Form validation with Standard Schema
- Layout composition (Dashboard, Docs, Chat, Editor)
- Official starter templates

A skill inclui referências adicionais que o agente de IA carrega sob demanda conforme a tarefa, mantendo as respostas focadas e eficientes em contexto.

> \[!NOTE]
>
> Uma vez instalada, você pode invocar a skill digitando `/nuxt-ui` no chat do seu agente.

### Skills CLI

A CLI [`skills`](https://skills.sh){rel="&#x22;nofollow&#x22;"} é a maneira mais fácil de instalar a skill do Nitro UI. Ela suporta mais de 35 agentes, incluindo Cursor, Claude Code, Codex, Windsurf, Cline e outros.

```bash
npx skills add nuxt/ui
```

Você pode direcionar agentes específicos com a flag `--agent`:

```bash
npx skills add nuxt/ui --agent cursor
npx skills add nuxt/ui --agent claude-code
```

Ou instale globalmente para que a skill fique disponível em todos os seus projetos:

```bash
npx skills add nuxt/ui --global
```

Se clonar do GitHub estiver lento na sua rede, você pode instalar diretamente pelo site:

```bash
npx skills add https://ui.nitro.news
```

> \[!TIP]
>
> Acesse [skills.sh](https://skills.sh){rel="&#x22;nofollow&#x22;"} para saber mais sobre o ecossistema de skills e explorar as skills disponíveis.

### Cursor

#### Instalação rápida

Clique no botão abaixo para instalar a skill do Nitro UI diretamente no Cursor:

[Install Skill](cursor://anysphere.cursor-deeplink/install-skill?url=https://github.com/nuxt/ui/tree/v4/skills/nuxt-ui)

#### Configuração manual

1. Abra o Cursor e vá em "Settings" > "Skills"
2. Clique em "Add skill" e informe a seguinte URL:

```text
https://github.com/nuxt/ui/tree/v4/skills/nuxt-ui
```

### Claude Code

> \[!NOTE]
>
> **Ensure Claude Code is installed.** Visit [Anthropic's documentation](https://docs.anthropic.com/en/docs/claude-code/quickstart){rel="&#x22;nofollow&#x22;"} for installation instructions.

Adicione a skill usando o comando da CLI:

```bash
claude skill add https://github.com/nuxt/ui/tree/v4/skills/nuxt-ui
```

### Outras ferramentas de IA

Os arquivos da skill estão disponíveis publicamente no GitHub. Você pode referenciá-los diretamente em qualquer ferramenta de IA que suporte contexto ou instruções personalizadas:

- **Skill entry point**: [`skills/nuxt-ui/SKILL.md`](https://github.com/nuxt/ui/tree/v4/skills/nuxt-ui/SKILL.md){rel="&#x22;nofollow&#x22;"}
- **Full skill directory**: [`skills/nuxt-ui/`](https://github.com/nuxt/ui/tree/v4/skills/nuxt-ui){rel="&#x22;nofollow&#x22;"}


# Accordion

## Uso

Use o componente Accordion para exibir uma lista de itens recolhíveis.

```vue
<script setup lang="ts">
import type { AccordionItem } from '@nitro/ui'

const items = ref<AccordionItem[]>([
  {
    label: "Is Nitro UI free to use?",
    content: "Yes! Nitro UI is completely free and open source under the MIT license. All 125+ components are available to everyone."
  },
  {
    label: "Can I use Nitro UI with Vue without Nuxt?",
    content: "Yes! While optimized for Nuxt, Nitro UI works perfectly with standalone Vue projects via our Vite plugin. You can follow the [installation guide](/docs/getting-started/installation/vue) to get started."
  },
  {
    label: "Is Nitro UI production-ready?",
    content: "Yes! Nitro UI is used in production by thousands of applications with extensive tests, regular updates, and active maintenance."
  }
])
</script>

<template>
  <UAccordion :items="items" />
</template>
```

### Itens

Use a prop `items` como um array de objetos com as seguintes propriedades:

- `label?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `icon?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `trailingIcon?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `content?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `value?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `disabled?: boolean`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- [`slot?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}](https://ui.nitro.news/#with-custom-slot)
- `class?: any`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `ui?: { item?: ClassNameValue, header?: ClassNameValue, trigger?: ClassNameValue, leadingIcon?: ClassNameValue, label?: ClassNameValue, trailingIcon?: ClassNameValue, content?: ClassNameValue, body?: ClassNameValue }`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

```vue
<script setup lang="ts">
import type { AccordionItem } from '@nitro/ui'

const items = ref<AccordionItem[]>([
  {
    label: "Icons",
    icon: "i-lucide-smile",
    content: "You have nothing to do, @nuxt/icon will handle it automatically."
  },
  {
    label: "Colors",
    icon: "i-lucide-swatch-book",
    content: "Choose a primary and a neutral color from your Tailwind CSS theme."
  },
  {
    label: "Components",
    icon: "i-lucide-box",
    content: "You can customize components by using the `class` / `ui` props or in your app.config.ts."
  }
])
</script>

<template>
  <UAccordion :items="items" />
</template>
```

### Múltiplo

Defina a prop `type` como `multiple` para permitir que vários itens fiquem ativos ao mesmo tempo. O padrão é `single`.

```vue
<script setup lang="ts">
import type { AccordionItem } from '@nitro/ui'

const items = ref<AccordionItem[]>([
  {
    label: "Icons",
    icon: "i-lucide-smile",
    content: "You have nothing to do, @nuxt/icon will handle it automatically."
  },
  {
    label: "Colors",
    icon: "i-lucide-swatch-book",
    content: "Choose a primary and a neutral color from your Tailwind CSS theme."
  },
  {
    label: "Components",
    icon: "i-lucide-box",
    content: "You can customize components by using the `class` / `ui` props or in your app.config.ts."
  }
])
</script>

<template>
  <UAccordion type="multiple" :items="items" />
</template>
```

### Recolhível

Quando `type` é `single`, você pode definir a prop `collapsible` como `false` para evitar que o item ativo seja recolhido.

```vue
<script setup lang="ts">
import type { AccordionItem } from '@nitro/ui'

const items = ref<AccordionItem[]>([
  {
    label: "Icons",
    icon: "i-lucide-smile",
    content: "You have nothing to do, @nuxt/icon will handle it automatically."
  },
  {
    label: "Colors",
    icon: "i-lucide-swatch-book",
    content: "Choose a primary and a neutral color from your Tailwind CSS theme."
  },
  {
    label: "Components",
    icon: "i-lucide-box",
    content: "You can customize components by using the `class` / `ui` props or in your app.config.ts."
  }
])
</script>

<template>
  <UAccordion :collapsible="false" :items="items" />
</template>
```

### Desmontar

Use a prop `unmount-on-hide` para evitar que o conteúdo seja desmontado quando o accordion é recolhido. O padrão é `true`.

```vue
<script setup lang="ts">
import type { AccordionItem } from '@nitro/ui'

const items = ref<AccordionItem[]>([
  {
    label: "Icons",
    icon: "i-lucide-smile",
    content: "You have nothing to do, @nuxt/icon will handle it automatically."
  },
  {
    label: "Colors",
    icon: "i-lucide-swatch-book",
    content: "Choose a primary and a neutral color from your Tailwind CSS theme."
  },
  {
    label: "Components",
    icon: "i-lucide-box",
    content: "You can customize components by using the `class` / `ui` props or in your app.config.ts."
  }
])
</script>

<template>
  <UAccordion :unmount-on-hide="false" :items="items" />
</template>
```

> \[!NOTE]
>
> Você pode inspecionar o DOM para ver o conteúdo de cada item sendo renderizado.

### Desabilitado

Use a propriedade `disabled` para desabilitar o Accordion.

Você também pode desabilitar um item específico usando a propriedade `disabled` no objeto do item.

```vue
<script setup lang="ts">
import type { AccordionItem } from '@nitro/ui'

const items = ref<AccordionItem[]>([
  {
    label: "Icons",
    icon: "i-lucide-smile",
    content: "You have nothing to do, @nuxt/icon will handle it automatically."
  },
  {
    label: "Colors",
    icon: "i-lucide-swatch-book",
    content: "Choose a primary and a neutral color from your Tailwind CSS theme.",
    disabled: true
  },
  {
    label: "Components",
    icon: "i-lucide-box",
    content: "You can customize components by using the `class` / `ui` props or in your app.config.ts."
  }
])
</script>

<template>
  <UAccordion disabled :items="items" />
</template>
```

### Ícone à direita

Use a prop `trailing-icon` para personalizar o [Icon](https://ui.nitro.news/docs/components/icon) à direita de cada item. O padrão é `i-lucide-chevron-down`.

> \[!TIP]
>
> Você também pode definir um ícone para um item específico usando a propriedade `trailingIcon` no objeto do item.

```vue
<script setup lang="ts">
import type { AccordionItem } from '@nitro/ui'

const items = ref<AccordionItem[]>([
  {
    label: "Icons",
    icon: "i-lucide-smile",
    content: "You have nothing to do, @nuxt/icon will handle it automatically.",
    trailingIcon: "i-lucide-plus"
  },
  {
    label: "Colors",
    icon: "i-lucide-swatch-book",
    content: "Choose a primary and a neutral color from your Tailwind CSS theme."
  },
  {
    label: "Components",
    icon: "i-lucide-box",
    content: "You can customize components by using the `class` / `ui` props or in your app.config.ts."
  }
])
</script>

<template>
  <UAccordion trailing-icon="i-lucide-arrow-down" :items="items" />
</template>
```

**Nuxt:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/nuxt#theme
>
> Você pode personalizar esse ícone globalmente no seu `app.config.ts` na chave `ui.icons.chevronDown`.

**Vue:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/vue#theme
>
> Você pode personalizar esse ícone globalmente no seu `vite.config.ts` na chave `ui.icons.chevronDown`.

## Exemplos

### Controlar o(s) item(ns) ativo(s)

Você pode controlar o item ativo usando a prop `default-value` ou a diretiva `v-model` com o `value` do item. Se nenhum `value` for fornecido, o padrão é o índice **como string**.

::component-example
---
props:
  class: px-4
name: accordion-model-value-example
---
::

> \[!TIP]
>
> Use a prop `value-key` para alterar a chave usada para corresponder os itens quando um `v-model` ou `default-value` é fornecido.

> \[!CAUTION]
>
> Quando `type="multiple"`, certifique-se de passar um array para a prop `default-value` ou para a diretiva `v-model`.

### Com arrastar e soltar

Use o composable [`useSortable`](https://vueuse.org/integrations/useSortable/){rel="&#x22;nofollow&#x22;"} de [`@vueuse/integrations`](https://vueuse.org/integrations/README.html){rel="&#x22;nofollow&#x22;"} para habilitar a funcionalidade de arrastar e soltar no Accordion. Essa integração envolve o [Sortable.js](https://sortablejs.github.io/Sortable/){rel="&#x22;nofollow&#x22;"} para oferecer uma experiência de arrastar e soltar fluida.

:component-example{name="accordion-drag-and-drop-example"}

### Com slot de corpo

Use o slot `#body` para personalizar o corpo de cada item.

::component-example
---
props:
  class: px-4
name: accordion-body-slot-example
---
::

> \[!TIP]
>
> O slot `#body` inclui alguns estilos predefinidos; use o [slot `#content`](https://ui.nitro.news/#with-content-slot) se você quiser começar do zero.

### Com slot de conteúdo

Use o slot `#content` para personalizar o conteúdo de cada item.

::component-example
---
props:
  class: px-4
name: accordion-content-slot-example
---
::

### Com slot personalizado

Use a propriedade `slot` para personalizar um item específico.

Você terá acesso aos seguintes slots:

- `#{{ item.slot }}`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `#{{ item.slot }}-body`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

::component-example
---
props:
  class: px-4
name: accordion-custom-slot-example
---
::

### Com conteúdo markdown

Você pode usar o componente [MDC](https://github.com/nuxt-content/mdc?tab=readme-ov-file#mdc){rel="&#x22;nofollow&#x22;"} do `@nuxtjs/mdc` para renderizar markdown nos itens do accordion.

::component-example{.px-8 collapse name="accordion-markdown-example"}
::

## API

### Props

```ts
/**
 * Props for the Accordion component
 */
interface AccordionProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  items?: T[] | undefined;
  /**
   * The icon displayed on the right side of the trigger.
   */
  trailingIcon?: any;
  /**
   * The key used to get the label from the item.
   * @default "\"label\""
   */
  labelKey?: GetItemKeys<T> | undefined;
  ui?: { root?: SlotClass; item?: SlotClass; header?: SlotClass; trigger?: SlotClass; content?: SlotClass; body?: SlotClass; leadingIcon?: SlotClass; trailingIcon?: SlotClass; label?: SlotClass; } | undefined;
  /**
   * When type is "single", allows closing content when clicking trigger for an open item.
   * When type is "multiple", this prop has no effect.
   * @default "true"
   */
  collapsible?: boolean | undefined;
  /**
   * The default active value of the item(s).
   * 
   * Use when you do not need to control the state of the item(s).
   */
  defaultValue?: string | string[] | undefined;
  /**
   * The controlled value of the active item(s).
   * 
   * Use this when you need to control the state of the items. Can be binded with `v-model`
   */
  modelValue?: string | string[] | undefined;
  /**
   * Determines whether a "single" or "multiple" items can be selected at a time.
   * 
   * This prop will overwrite the inferred type from `modelValue` and `defaultValue`.
   * @default "\"single\""
   */
  type?: SingleOrMultipleType | undefined;
  /**
   * When `true`, prevents the user from interacting with the accordion and all its items
   */
  disabled?: boolean | undefined;
  /**
   * When `true`, the element will be unmounted on closed state.
   * @default "true"
   */
  unmountOnHide?: boolean | undefined;
}
```

### Slots

```ts
/**
 * Slots for the Accordion component
 */
interface AccordionSlots {
  leading(): any;
  default(): any;
  trailing(): any;
  content(): any;
  body(): any;
}
```

### Emits

```ts
/**
 * Emitted events for the Accordion component
 */
interface AccordionEmits {
  update:modelValue: (payload: [value: string | string[] | undefined]) => void;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    accordion: {
      slots: {
        root: 'w-full',
        item: 'border-b border-default last:border-b-0',
        header: 'flex',
        trigger: 'group flex-1 flex items-center gap-1.5 font-medium text-sm py-3.5 focus-visible:outline-primary min-w-0',
        content: 'data-[state=open]:animate-[accordion-down_200ms_ease-out] data-[state=closed]:animate-[accordion-up_200ms_ease-out] overflow-hidden focus:outline-none',
        body: 'text-sm pb-3.5',
        leadingIcon: 'shrink-0 size-5',
        trailingIcon: 'shrink-0 size-5 ms-auto group-data-[state=open]:rotate-180 transition-transform duration-200',
        label: 'text-start break-words'
      },
      variants: {
        disabled: {
          true: {
            trigger: 'cursor-not-allowed opacity-75'
          }
        }
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/Accordion.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/accordion.ts).


# Alert

## Uso

### Título

Use a prop `title` para definir o título do Alert.

```vue
<template>
  <UAlert title="Heads up!" />
</template>
```

### Descrição

Use a prop `description` para definir a descrição do Alert.

```vue
<template>
  <UAlert title="Heads up!" description="You can change the primary color in your app config." />
</template>
```

### Ícone

Use a prop `icon` para exibir um [Icon](https://ui.nitro.news/docs/components/icon).

```vue
<template>
  <UAlert title="Heads up!" description="You can change the primary color in your app config." icon="i-lucide-terminal" />
</template>
```

### Avatar

Use a prop `avatar` para exibir um [Avatar](https://ui.nitro.news/docs/components/avatar).

```vue
<template>
  <UAlert title="Heads up!" description="You can change the primary color in your app config." :avatar="{
  src: 'https://github.com/nuxt.png'
}" />
</template>
```

### Cor

Use a prop `color` para alterar a cor do Alert.

```vue
<template>
  <UAlert color="neutral" title="Heads up!" description="You can change the primary color in your app config." icon="i-lucide-terminal" />
</template>
```

### Variante

Use a prop `variant` para alterar a variante do Alert.

```vue
<template>
  <UAlert color="neutral" variant="subtle" title="Heads up!" description="You can change the primary color in your app config." icon="i-lucide-terminal" />
</template>
```

### Fechar

Use a prop `close` para exibir um [Button](https://ui.nitro.news/docs/components/button) para dispensar o Alert.

> \[!TIP]
>
> Um evento `update:open` será emitido quando o botão de fechar for clicado.

```vue
<template>
  <UAlert title="Heads up!" description="You can change the primary color in your app config." color="neutral" variant="outline" close />
</template>
```

Você pode passar qualquer propriedade do componente [Button](https://ui.nitro.news/docs/components/button) para personalizá-lo.

```vue
<template>
  <UAlert title="Heads up!" description="You can change the primary color in your app config." color="neutral" variant="outline" :close="{
  color: 'primary',
  variant: 'outline',
  class: 'rounded-full'
}" />
</template>
```

### Ícone de fechar

Use a prop `close-icon` para personalizar o [Icon](https://ui.nitro.news/docs/components/icon) do botão de fechar. O padrão é `i-lucide-x`.

```vue
<template>
  <UAlert title="Heads up!" description="You can change the primary color in your app config." color="neutral" variant="outline" close close-icon="i-lucide-arrow-right" />
</template>
```

**Nuxt:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/nuxt#theme
>
> Você pode personalizar esse ícone globalmente no seu `app.config.ts` na chave `ui.icons.close`.

**Vue:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/vue#theme
>
> Você pode personalizar esse ícone globalmente no seu `vite.config.ts` na chave `ui.icons.close`.

### Ações

Use a prop `actions` para adicionar algumas ações de [Button](https://ui.nitro.news/docs/components/button) ao Alert.

```vue
<template>
  <UAlert title="Heads up!" description="You can change the primary color in your app config." color="neutral" variant="outline" :actions="[
  {
    label: 'Action 1'
  },
  {
    label: 'Action 2',
    color: 'neutral',
    variant: 'subtle'
  }
]" />
</template>
```

### Orientação

Use a prop `orientation` para alterar a orientação do Alert.

```vue
<template>
  <UAlert title="Heads up!" description="You can change the primary color in your app config." color="neutral" variant="outline" orientation="horizontal" :actions="[
  {
    label: 'Action 1'
  },
  {
    label: 'Action 2',
    color: 'neutral',
    variant: 'subtle'
  }
]" />
</template>
```

## Exemplos

### `class` prop

Use a prop `class` para sobrescrever os estilos base do Alert.

```vue
<template>
  <UAlert title="Heads up!" description="You can change the primary color in your app config." class="rounded-none" />
</template>
```

### `ui` prop

Use a prop `ui` para sobrescrever os estilos dos slots do Alert.

```vue
<template>
  <UAlert title="Heads up!" description="You can change the primary color in your app config." icon="i-lucide-rocket" :ui="{
  icon: 'size-11'
}" />
</template>
```

## API

### Props

```ts
/**
 * Props for the Alert component
 */
interface AlertProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  title?: string | undefined;
  description?: string | undefined;
  icon?: any;
  avatar?: AvatarProps | undefined;
  color?: "error" | "primary" | "secondary" | "accent" | "success" | "info" | "warning" | "neutral" | undefined;
  variant?: "solid" | "outline" | "soft" | "subtle" | undefined;
  /**
   * The orientation between the content and the actions.
   * @default "\"vertical\""
   */
  orientation?: "vertical" | "horizontal" | undefined;
  /**
   * Display a list of actions:
   * - under the title and description when orientation is `vertical`
   * - next to the close button when orientation is `horizontal`
   * `{ size: 'xs' }`{lang="ts-type"}
   */
  actions?: ButtonProps[] | undefined;
  /**
   * Display a close button to dismiss the alert.
   * `{ size: 'md', color: 'neutral', variant: 'link' }`{lang="ts-type"}
   */
  close?: boolean | Omit<ButtonProps, LinkPropsKeys> | undefined;
  /**
   * The icon displayed in the close button.
   */
  closeIcon?: any;
  ui?: { root?: SlotClass; wrapper?: SlotClass; title?: SlotClass; description?: SlotClass; icon?: SlotClass; avatar?: SlotClass; avatarSize?: SlotClass; actions?: SlotClass; close?: SlotClass; } | undefined;
}
```

### Slots

```ts
/**
 * Slots for the Alert component
 */
interface AlertSlots {
  leading(): any;
  title(): any;
  description(): any;
  actions(): any;
  close(): any;
}
```

### Emits

```ts
/**
 * Emitted events for the Alert component
 */
interface AlertEmits {
  update:open: (payload: [value: boolean]) => void;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    alert: {
      slots: {
        root: 'relative overflow-hidden w-full rounded-lg p-4 flex gap-2.5',
        wrapper: 'min-w-0 flex-1 flex flex-col',
        title: 'text-sm font-medium',
        description: 'text-sm opacity-90',
        icon: 'shrink-0 size-5',
        avatar: 'shrink-0',
        avatarSize: '2xl',
        actions: 'flex flex-wrap gap-1.5 shrink-0',
        close: 'p-0'
      },
      variants: {
        color: {
          primary: '',
          secondary: '',
          accent: '',
          success: '',
          info: '',
          warning: '',
          error: '',
          neutral: ''
        },
        variant: {
          solid: '',
          outline: '',
          soft: '',
          subtle: ''
        },
        orientation: {
          horizontal: {
            root: 'items-center',
            actions: 'items-center'
          },
          vertical: {
            root: 'items-start',
            actions: 'items-start mt-2.5'
          }
        },
        title: {
          true: {
            description: 'mt-1'
          }
        }
      },
      compoundVariants: [
        {
          color: 'primary',
          variant: 'solid',
          class: {
            root: 'bg-primary text-inverted'
          }
        },
        {
          color: 'secondary',
          variant: 'solid',
          class: {
            root: 'bg-secondary text-inverted'
          }
        },
        {
          color: 'accent',
          variant: 'solid',
          class: {
            root: 'bg-accent text-inverted'
          }
        },
        {
          color: 'success',
          variant: 'solid',
          class: {
            root: 'bg-success text-inverted'
          }
        },
        {
          color: 'info',
          variant: 'solid',
          class: {
            root: 'bg-info text-inverted'
          }
        },
        {
          color: 'warning',
          variant: 'solid',
          class: {
            root: 'bg-warning text-inverted'
          }
        },
        {
          color: 'error',
          variant: 'solid',
          class: {
            root: 'bg-error text-inverted'
          }
        },
        {
          color: 'primary',
          variant: 'outline',
          class: {
            root: 'text-primary ring ring-inset ring-primary/25'
          }
        },
        {
          color: 'secondary',
          variant: 'outline',
          class: {
            root: 'text-secondary ring ring-inset ring-secondary/25'
          }
        },
        {
          color: 'accent',
          variant: 'outline',
          class: {
            root: 'text-accent ring ring-inset ring-accent/25'
          }
        },
        {
          color: 'success',
          variant: 'outline',
          class: {
            root: 'text-success ring ring-inset ring-success/25'
          }
        },
        {
          color: 'info',
          variant: 'outline',
          class: {
            root: 'text-info ring ring-inset ring-info/25'
          }
        },
        {
          color: 'warning',
          variant: 'outline',
          class: {
            root: 'text-warning ring ring-inset ring-warning/25'
          }
        },
        {
          color: 'error',
          variant: 'outline',
          class: {
            root: 'text-error ring ring-inset ring-error/25'
          }
        },
        {
          color: 'primary',
          variant: 'soft',
          class: {
            root: 'bg-primary/10 text-primary'
          }
        },
        {
          color: 'secondary',
          variant: 'soft',
          class: {
            root: 'bg-secondary/10 text-secondary'
          }
        },
        {
          color: 'accent',
          variant: 'soft',
          class: {
            root: 'bg-accent/10 text-accent'
          }
        },
        {
          color: 'success',
          variant: 'soft',
          class: {
            root: 'bg-success/10 text-success'
          }
        },
        {
          color: 'info',
          variant: 'soft',
          class: {
            root: 'bg-info/10 text-info'
          }
        },
        {
          color: 'warning',
          variant: 'soft',
          class: {
            root: 'bg-warning/10 text-warning'
          }
        },
        {
          color: 'error',
          variant: 'soft',
          class: {
            root: 'bg-error/10 text-error'
          }
        },
        {
          color: 'primary',
          variant: 'subtle',
          class: {
            root: 'bg-primary/10 text-primary ring ring-inset ring-primary/25'
          }
        },
        {
          color: 'secondary',
          variant: 'subtle',
          class: {
            root: 'bg-secondary/10 text-secondary ring ring-inset ring-secondary/25'
          }
        },
        {
          color: 'accent',
          variant: 'subtle',
          class: {
            root: 'bg-accent/10 text-accent ring ring-inset ring-accent/25'
          }
        },
        {
          color: 'success',
          variant: 'subtle',
          class: {
            root: 'bg-success/10 text-success ring ring-inset ring-success/25'
          }
        },
        {
          color: 'info',
          variant: 'subtle',
          class: {
            root: 'bg-info/10 text-info ring ring-inset ring-info/25'
          }
        },
        {
          color: 'warning',
          variant: 'subtle',
          class: {
            root: 'bg-warning/10 text-warning ring ring-inset ring-warning/25'
          }
        },
        {
          color: 'error',
          variant: 'subtle',
          class: {
            root: 'bg-error/10 text-error ring ring-inset ring-error/25'
          }
        },
        {
          color: 'neutral',
          variant: 'solid',
          class: {
            root: 'text-inverted bg-inverted'
          }
        },
        {
          color: 'neutral',
          variant: 'outline',
          class: {
            root: 'text-highlighted bg-default ring ring-inset ring-default'
          }
        },
        {
          color: 'neutral',
          variant: 'soft',
          class: {
            root: 'text-highlighted bg-elevated/50'
          }
        },
        {
          color: 'neutral',
          variant: 'subtle',
          class: {
            root: 'text-highlighted bg-elevated/50 ring ring-inset ring-accented'
          }
        }
      ],
      defaultVariants: {
        color: 'primary',
        variant: 'solid'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/Alert.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/alert.ts).


# App

## Uso

Este componente implementa o [ConfigProvider](https://reka-ui.com/docs/utilities/config-provider){rel="&#x22;nofollow&#x22;"} do Reka UI para fornecer configuração global a todos os componentes:

- Enables all primitives to inherit global reading direction.
- Enables changing the behavior of scroll body when setting body lock.
- Much more controls to prevent layout shifts.

Ele também usa o [ToastProvider](https://reka-ui.com/docs/components/toast#provider){rel="&#x22;nofollow&#x22;"} e o [TooltipProvider](https://reka-ui.com/docs/components/tooltip#provider){rel="&#x22;nofollow&#x22;"} para fornecer toasts e tooltips globais, além de modais e slideovers programáticos.

Envolva toda a sua aplicação com o componente App no seu arquivo `app.vue`:

```vue [app.vue]
<template>
  <NApp>
    <NuxtPage />
  </NApp>
</template>
```

**Nuxt:**

> \[!TIP]
> See: /docs/getting-started/integrations/i18n/nuxt#locale
>
> Aprenda a usar a prop `locale` para alterar o locale do seu app. Isso também controla o formato de data/hora em componentes como Calendar, InputDate e InputTime.

**Vue:**

> \[!TIP]
> See: /docs/getting-started/integrations/i18n/vue#locale
>
> Aprenda a usar a prop `locale` para alterar o locale do seu app. Isso também controla o formato de data/hora em componentes como Calendar, InputDate e InputTime.

## API

### Props

```ts
/**
 * Props for the App component
 */
interface AppProps {
  tooltip?: TooltipProviderProps | undefined;
  toaster?: ToasterProps | null | undefined;
  locale?: Locale<T> | undefined;
  /**
   * @default "\"body\""
   */
  portal?: string | boolean | HTMLElement | undefined;
  /**
   * The global reading direction of your application. This will be inherited by all primitives.
   */
  dir?: Direction | undefined;
  /**
   * The global scroll body behavior of your application. This will be inherited by the related primitives.
   */
  scrollBody?: boolean | ScrollBodyOption | undefined;
  /**
   * The global `nonce` value of your application. This will be inherited by the related primitives.
   */
  nonce?: string | undefined;
  /**
   * The global default teleport target for all portalled primitives (e.g. `Dialog`, `Popover`, `Tooltip`).
   * Individual `*Portal` components can still override this via their own `to` prop.
   * Useful when rendering inside a custom element / shadow DOM.
   */
  teleportTo?: string | HTMLElement | undefined;
}
```

### Slots

```ts
/**
 * Slots for the App component
 */
interface AppSlots {
  default(): any;
}
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/App.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/app.ts).


# AuthForm

## Uso

Construído sobre o componente [Form](https://ui.nitro.news/docs/components/form), o componente `AuthForm` pode ser usado nas suas páginas ou envolvido em um [PageCard](https://ui.nitro.news/docs/components/page-card).

::component-example{collapse name="auth-form-example"}
::

### Campos

O Form se constrói com base na prop `fields`, e o estado é tratado internamente.

Use a prop `fields` como um array de objetos com as seguintes propriedades:

- `name: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `type: 'checkbox' | 'select' | 'otp' | 'InputHTMLAttributes['type']'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Cada campo precisa incluir uma propriedade `type`, que determina o componente de input e quaisquer props adicionais aplicadas: campos `checkbox` usam props do [Checkbox](https://ui.nitro.news/docs/components/checkbox#props), campos `select` usam props do [SelectMenu](https://ui.nitro.news/docs/components/select-menu#props), campos `otp` usam props do [PinInput](https://ui.nitro.news/docs/components/pin-input#props), e todos os outros tipos usam props do [Input](https://ui.nitro.news/docs/components/input#props).

Você também pode passar qualquer propriedade do componente [FormField](https://ui.nitro.news/docs/components/form-field#props) para cada campo.

```vue
<script setup lang="ts">
import type { AuthFormField } from '@nitro/ui'

const fields = ref<AuthFormField[]>([
  {
    name: "email",
    type: "email",
    label: "Email",
    placeholder: "Enter your email",
    required: true
  },
  {
    name: "password",
    type: "password",
    label: "Password",
    placeholder: "Enter your password",
    required: true
  },
  {
    name: "country",
    type: "select",
    label: "Country",
    placeholder: "Select country",
    items: [
      {
        label: "United States",
        value: "us"
      },
      {
        label: "France",
        value: "fr"
      },
      {
        label: "United Kingdom",
        value: "uk"
      },
      {
        label: "Australia",
        value: "au"
      }
    ]
  },
  {
    name: "otp",
    type: "otp",
    label: "OTP",
    length: 6,
    placeholder: "○"
  },
  {
    name: "remember",
    type: "checkbox",
    label: "Remember me",
    description: "You will be logged in for 30 days."
  }
])
</script>

<template>
  <UAuthForm :fields="fields" class="max-w-sm" />
</template>
```

### Título

Use a prop `title` para definir o título do Form.

```vue
<script setup lang="ts">
import type { AuthFormField } from '@nitro/ui'

const fields = ref<AuthFormField[]>([
  {
    name: "email",
    type: "text",
    label: "Email"
  },
  {
    name: "password",
    type: "password",
    label: "Password"
  }
])
</script>

<template>
  <UAuthForm title="Login" :fields="fields" class="max-w-md" />
</template>
```

### Descrição

Use a prop `description` para definir a descrição do Form.

```vue
<script setup lang="ts">
import type { AuthFormField } from '@nitro/ui'

const fields = ref<AuthFormField[]>([
  {
    name: "email",
    type: "text",
    label: "Email"
  },
  {
    name: "password",
    type: "password",
    label: "Password"
  }
])
</script>

<template>
  <UAuthForm title="Login" description="Enter your credentials to access your account." :fields="fields" class="max-w-md" />
</template>
```

### Ícone

Use a prop `icon` para definir o ícone do Form.

```vue
<script setup lang="ts">
import type { AuthFormField } from '@nitro/ui'

const fields = ref<AuthFormField[]>([
  {
    name: "email",
    type: "text",
    label: "Email"
  },
  {
    name: "password",
    type: "password",
    label: "Password"
  }
])
</script>

<template>
  <UAuthForm title="Login" description="Enter your credentials to access your account." icon="i-lucide-user" :fields="fields" class="max-w-md" />
</template>
```

### Provedores

Use a prop `providers` para adicionar provedores ao formulário.

Você pode passar qualquer propriedade do componente [Button](https://ui.nitro.news/docs/components/button), como `variant`, `color`, `to`, etc.

```vue
<script setup lang="ts">
import type { ButtonProps, AuthFormField } from '@nitro/ui'

const providers = ref<ButtonProps[]>([
  {
    label: "Google",
    icon: "i-simple-icons-google",
    color: "neutral",
    variant: "subtle"
  },
  {
    label: "GitHub",
    icon: "i-simple-icons-github",
    color: "neutral",
    variant: "subtle"
  }
])
const fields = ref<AuthFormField[]>([
  {
    name: "email",
    type: "text",
    label: "Email"
  },
  {
    name: "password",
    type: "password",
    label: "Password"
  }
])
</script>

<template>
  <UAuthForm title="Login" description="Enter your credentials to access your account." icon="i-lucide-user" :providers="providers" :fields="fields" class="max-w-md" />
</template>
```

### Separador

Use a prop `separator` para personalizar o [Separator](https://ui.nitro.news/docs/components/separator) entre os provedores e os campos. O padrão é `or`.

```vue
<script setup lang="ts">
import type { ButtonProps, AuthFormField } from '@nitro/ui'

const providers = ref<ButtonProps[]>([
  {
    label: "Google",
    icon: "i-simple-icons-google",
    color: "neutral",
    variant: "subtle"
  },
  {
    label: "GitHub",
    icon: "i-simple-icons-github",
    color: "neutral",
    variant: "subtle"
  }
])
const fields = ref<AuthFormField[]>([
  {
    name: "email",
    type: "text",
    label: "Email"
  },
  {
    name: "password",
    type: "password",
    label: "Password"
  }
])
</script>

<template>
  <UAuthForm title="Login" description="Enter your credentials to access your account." icon="i-lucide-user" :providers="providers" :fields="fields" separator="Providers" class="max-w-md" />
</template>
```

Você pode passar qualquer propriedade do componente [Separator](https://ui.nitro.news/docs/components/separator#props) para personalizá-lo.

```vue
<script setup lang="ts">
import type { ButtonProps, AuthFormField } from '@nitro/ui'

const providers = ref<ButtonProps[]>([
  {
    label: "Google",
    icon: "i-simple-icons-google",
    color: "neutral",
    variant: "subtle"
  },
  {
    label: "GitHub",
    icon: "i-simple-icons-github",
    color: "neutral",
    variant: "subtle"
  }
])
const fields = ref<AuthFormField[]>([
  {
    name: "email",
    type: "text",
    label: "Email"
  },
  {
    name: "password",
    type: "password",
    label: "Password"
  }
])
</script>

<template>
  <UAuthForm title="Login" description="Enter your credentials to access your account." icon="i-lucide-user" :providers="providers" :fields="fields" :separator="{
  icon: 'i-lucide-user'
}" class="max-w-md" />
</template>
```

### Enviar

Use a prop `submit` para alterar o botão de envio do Form.

Você pode passar qualquer propriedade do componente [Button](https://ui.nitro.news/docs/components/button), como `variant`, `color`, `to`, etc.

```vue
<script setup lang="ts">
import type { AuthFormField } from '@nitro/ui'

const fields = ref<AuthFormField[]>([
  {
    name: "email",
    type: "text",
    label: "Email"
  },
  {
    name: "password",
    type: "password",
    label: "Password"
  }
])
</script>

<template>
  <UAuthForm title="Login" description="Enter your credentials to access your account." icon="i-lucide-user" :fields="fields" :submit="{
  label: 'Submit',
  color: 'error',
  variant: 'subtle'
}" class="max-w-md" />
</template>
```

## Exemplos

### Dentro de uma página

Você pode envolver o componente `AuthForm` com o componente [PageCard](https://ui.nitro.news/docs/components/page-card) para exibi-lo dentro de uma página `login.vue`, por exemplo.

::component-example{collapse name="auth-form-page-example"}
::

## API

### Props

```ts
/**
 * Props for the AuthForm component
 */
interface AuthFormProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  /**
   * The icon displayed above the title.
   */
  icon?: any;
  title?: string | undefined;
  description?: string | undefined;
  fields?: F[] | undefined;
  /**
   * Display a list of Button under the description.
   * `{ color: 'neutral', variant: 'subtle', block: true }`{lang="ts-type"}
   */
  providers?: ButtonProps[] | undefined;
  /**
   * The text displayed in the separator.
   * @default "\"or\""
   */
  separator?: string | SeparatorProps | undefined;
  /**
   * Display a submit button at the bottom of the form.
   * `{ label: 'Continue', block: true }`{lang="ts-type"}
   */
  submit?: Omit<ButtonProps, LinkPropsKeys> | undefined;
  schema?: T | undefined;
  validate?: ((state: Partial<InferInput<T>>) => FormError<string>[] | Promise<FormError<string>[]>) | undefined;
  validateOn?: FormInputEvents[] | undefined;
  validateOnInputDelay?: number | undefined;
  disabled?: boolean | undefined;
  loading?: boolean | undefined;
  loadingAuto?: boolean | undefined;
  ui?: { root?: SlotClass; header?: SlotClass; leading?: SlotClass; leadingIcon?: SlotClass; title?: SlotClass; description?: SlotClass; body?: SlotClass; providers?: SlotClass; checkbox?: SlotClass; select?: SlotClass; password?: SlotClass; otp?: SlotClass; input?: SlotClass; separator?: SlotClass; form?: SlotClass; footer?: SlotClass; } | undefined;
  name?: string | undefined;
  autocomplete?: string | undefined;
  acceptcharset?: string | undefined;
  action?: string | undefined;
  enctype?: string | undefined;
  method?: string | undefined;
  novalidate?: Booleanish | undefined;
  target?: string | undefined;
}
```

> \[!NOTE]
> See: https\://developer.mozilla.org/en-US/docs/Web/HTML/Element/form#attributes
>
> Este componente também suporta todos os atributos HTML nativos de `<form>`.

### Slots

```ts
/**
 * Slots for the AuthForm component
 */
interface AuthFormSlots {
  header(): any;
  leading(): any;
  title(): any;
  description(): any;
  providers(): any;
  separator(): any;
  validation(): any;
  submit(): any;
  footer(): any;
}
```

### Emits

```ts
/**
 * Emitted events for the AuthForm component
 */
interface AuthFormEmits {
  submit: (payload: [payload: FormSubmitEvent<Reactive<InferInput<T>>>]) => void;
}
```

### Expose

Você pode acessar a instância tipada do componente (que expõe formRef e state) usando [`useTemplateRef`](https://vuejs.org/api/composition-api-helpers.html#usetemplateref){rel="&#x22;nofollow&#x22;"}. Por exemplo, em um formulário separado (ex.: um formulário de "redefinição") você pode fazer:

```vue
<script setup lang="ts">
const authForm = useTemplateRef('authForm')
</script>

<template>
  <NAuthForm ref="authForm" />
</template>
```

Isso dá a você acesso às seguintes propriedades (expostas):

| Name                                                                                                                          | Type                                                                                                                                              |
| ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `formRef`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | `Ref<HTMLFormElement | null>`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} |
| `state`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"}   | `Reactive<FormStateType>`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"}     |

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    authForm: {
      slots: {
        root: 'w-full space-y-6',
        header: 'flex flex-col text-center',
        leading: 'mb-2',
        leadingIcon: 'size-8 shrink-0 inline-block',
        title: 'text-xl text-pretty font-semibold text-highlighted',
        description: 'mt-1 text-base text-pretty text-muted',
        body: 'gap-y-6 flex flex-col',
        providers: 'space-y-3',
        checkbox: '',
        select: 'w-full',
        password: 'w-full',
        otp: 'w-full',
        input: 'w-full',
        separator: '',
        form: 'space-y-5',
        footer: 'text-sm text-center text-muted mt-2'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/AuthForm.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/auth-form.ts).


# Avatar

## Uso

O Avatar usa o componente `<NuxtImg>` quando o [`@nuxt/image`](https://github.com/nuxt/image){rel="&#x22;nofollow&#x22;"} está instalado, recorrendo a `img` caso contrário.

```vue
<template>
  <UAvatar src="https://github.com/benjamincanac.png" />
</template>
```

> \[!NOTE]
>
> Você pode passar qualquer propriedade do elemento HTML `<img>`, como `alt`, `loading`, etc.

> \[!TIP]
>
> Para não usar o `@nuxt/image`, use a prop `as`: `:as="{ img: 'img' }"`.

### Src

Use a prop `src` para definir a URL da imagem.

```vue
<template>
  <UAvatar src="https://github.com/benjamincanac.png" loading="lazy" />
</template>
```

### Tamanho

Use a prop `size` para definir o tamanho do Avatar.

```vue
<template>
  <UAvatar src="https://github.com/benjamincanac.png" size="xl" loading="lazy" />
</template>
```

> \[!NOTE]
>
> O `width` e o `height` do elemento `<img>` são definidos automaticamente com base na prop `size`.

### Ícone

Use a prop `icon` para exibir um [Icon](https://ui.nitro.news/docs/components/icon) de fallback.

```vue
<template>
  <UAvatar icon="i-lucide-image" size="md" />
</template>
```

### Texto

Use a prop `text` para exibir um texto de fallback.

```vue
<template>
  <UAvatar text="+1" size="md" />
</template>
```

### Alt

Quando nenhum ícone ou texto é fornecido, as **iniciais** da prop `alt` são usadas como fallback.

```vue
<template>
  <UAvatar alt="Benjamin Canac" size="md" />
</template>
```

> \[!NOTE]
>
> A prop `alt` é passada ao elemento `img` como o atributo `alt`.

### Cor `4.8+`

Use a prop `color` para alterar a cor do Avatar.

```vue
<template>
  <UAvatar color="primary" alt="Benjamin Canac" />
</template>
```

### Chip

Use a prop `chip` para exibir um chip ao redor do Avatar.

```vue
<template>
  <UAvatar src="https://github.com/benjamincanac.png" loading="lazy" :chip="{
  inset: true
}" />
</template>
```

## Exemplos

### Com tooltip

Você pode usar um componente [Tooltip](https://ui.nitro.news/docs/components/tooltip) para exibir um tooltip ao passar o mouse sobre o Avatar.

:component-example{name="avatar-tooltip-example"}

### Com máscara

Você pode usar uma máscara CSS para exibir um Avatar com um formato personalizado em vez de um simples círculo.

:component-example{name="avatar-mask-example"}

## API

### Props

```ts
/**
 * Props for the Avatar component
 */
interface AvatarProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  src?: string | undefined;
  alt?: string | undefined;
  icon?: any;
  text?: string | undefined;
  size?: "md" | "xs" | "sm" | "lg" | "xl" | "3xs" | "2xs" | "2xl" | "3xl" | undefined;
  color?: "error" | "primary" | "secondary" | "accent" | "success" | "info" | "warning" | "neutral" | undefined;
  chip?: boolean | ChipProps | undefined;
  ui?: { root?: SlotClass; image?: SlotClass; fallback?: SlotClass; icon?: SlotClass; } | undefined;
  loading?: "lazy" | "eager" | undefined;
  referrerpolicy?: HTMLAttributeReferrerPolicy | undefined;
  crossorigin?: "" | "anonymous" | "use-credentials" | undefined;
  decoding?: "async" | "auto" | "sync" | undefined;
  height?: Numberish | undefined;
  sizes?: string | undefined;
  srcset?: string | undefined;
  usemap?: string | undefined;
  width?: Numberish | undefined;
}
```

> \[!NOTE]
> See: https\://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#attributes
>
> Este componente também suporta todos os atributos HTML nativos de `<img>`.

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    avatar: {
      slots: {
        root: 'inline-flex items-center justify-center shrink-0 select-none rounded-full align-middle',
        image: 'h-full w-full rounded-[inherit] object-cover',
        fallback: 'font-medium leading-none truncate uppercase',
        icon: 'shrink-0'
      },
      variants: {
        color: {
          primary: {
            root: 'bg-primary-50',
            fallback: 'text-primary',
            icon: 'text-primary'
          },
          secondary: {
            root: 'bg-secondary-50',
            fallback: 'text-secondary',
            icon: 'text-secondary'
          },
          accent: {
            root: 'bg-accent-50',
            fallback: 'text-accent',
            icon: 'text-accent'
          },
          success: {
            root: 'bg-success-50',
            fallback: 'text-success',
            icon: 'text-success'
          },
          info: {
            root: 'bg-info-50',
            fallback: 'text-info',
            icon: 'text-info'
          },
          warning: {
            root: 'bg-warning-50',
            fallback: 'text-warning',
            icon: 'text-warning'
          },
          error: {
            root: 'bg-error-50',
            fallback: 'text-error',
            icon: 'text-error'
          },
          neutral: {
            root: 'bg-elevated',
            fallback: 'text-muted',
            icon: 'text-default'
          }
        },
        size: {
          '3xs': {
            root: 'size-4 text-[8px]'
          },
          '2xs': {
            root: 'size-5 text-[10px]'
          },
          xs: {
            root: 'size-6 text-xs'
          },
          sm: {
            root: 'size-7 text-sm'
          },
          md: {
            root: 'size-8 text-base'
          },
          lg: {
            root: 'size-9 text-lg'
          },
          xl: {
            root: 'size-10 text-xl'
          },
          '2xl': {
            root: 'size-11 text-[22px]'
          },
          '3xl': {
            root: 'size-12 text-2xl'
          }
        }
      },
      defaultVariants: {
        color: 'neutral',
        size: 'md'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/Avatar.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/avatar.ts).


# AvatarGroup

## Uso

Envolva vários [Avatar](https://ui.nitro.news/docs/components/avatar) dentro de um AvatarGroup para empilhá-los.

```vue
<template>
  <UAvatarGroup>
    <NAvatar src="https://github.com/benjamincanac.png" alt="Benjamin Canac" />
    <NAvatar src="https://github.com/romhml.png" alt="Romain Hamel" />
    <NAvatar src="https://github.com/noook.png" alt="Neil Richter" />
  </UAvatarGroup>
</template>
```

### Tamanho

Use a prop `size` para alterar o tamanho de todos os avatares.

```vue
<template>
  <UAvatarGroup size="xl">
    <NAvatar src="https://github.com/benjamincanac.png" alt="Benjamin Canac" loading="lazy" />
    <NAvatar src="https://github.com/romhml.png" alt="Romain Hamel" loading="lazy" />
    <NAvatar src="https://github.com/noook.png" alt="Neil Richter" loading="lazy" />
  </UAvatarGroup>
</template>
```

### Máximo

Use a prop `max` para limitar o número de avatares exibidos. O restante é exibido como um avatar `+X`.

```vue
<template>
  <UAvatarGroup :max="2">
    <NAvatar src="https://github.com/benjamincanac.png" alt="Benjamin Canac" loading="lazy" />
    <NAvatar src="https://github.com/romhml.png" alt="Romain Hamel" loading="lazy" />
    <NAvatar src="https://github.com/noook.png" alt="Neil Richter" loading="lazy" />
  </UAvatarGroup>
</template>
```

### Cor `4.8+`

Use a prop `color` para alterar a cor de todos os avatares.

```vue
<template>
  <UAvatarGroup color="primary">
    <NAvatar alt="Benjamin Canac" />
    <NAvatar alt="Romain Hamel" />
    <NAvatar alt="Neil Richter" />
  </UAvatarGroup>
</template>
```

## Exemplos

### Com tooltip

Envolva cada avatar com um [Tooltip](https://ui.nitro.news/docs/components/tooltip) para exibir um tooltip no hover.

:component-example{name="avatar-group-tooltip-example"}

### Com chip

Envolva cada avatar com um [Chip](https://ui.nitro.news/docs/components/chip) para exibir um chip ao redor do avatar.

:component-example{name="avatar-group-chip-example"}

### Com link

Envolva cada avatar com um [Link](https://ui.nitro.news/docs/components/link) para torná-los clicáveis.

:component-example{name="avatar-group-link-example"}

### Com máscara

Envolva um avatar com uma máscara CSS para exibi-lo com um formato personalizado.

:component-example{name="avatar-group-mask-example"}

> \[!WARNING]
>
> A prop `chip` não funciona corretamente ao usar uma máscara. Os chips podem ser cortados dependendo do formato da máscara.

## API

### Props

```ts
/**
 * Props for the AvatarGroup component
 */
interface AvatarGroupProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  size?: "md" | "xs" | "sm" | "lg" | "xl" | "3xs" | "2xs" | "2xl" | "3xl" | undefined;
  color?: "error" | "primary" | "secondary" | "accent" | "success" | "info" | "warning" | "neutral" | undefined;
  /**
   * The maximum number of avatars to display.
   */
  max?: string | number | undefined;
  ui?: { root?: SlotClass; base?: SlotClass; } | undefined;
}
```

### Slots

```ts
/**
 * Slots for the AvatarGroup component
 */
interface AvatarGroupSlots {
  default(): any;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    avatarGroup: {
      slots: {
        root: 'inline-flex flex-row-reverse justify-end',
        base: 'relative rounded-full ring-bg first:me-0'
      },
      variants: {
        size: {
          '3xs': {
            base: 'ring -me-0.5'
          },
          '2xs': {
            base: 'ring -me-0.5'
          },
          xs: {
            base: 'ring -me-0.5'
          },
          sm: {
            base: 'ring-2 -me-1.5'
          },
          md: {
            base: 'ring-2 -me-1.5'
          },
          lg: {
            base: 'ring-2 -me-1.5'
          },
          xl: {
            base: 'ring-3 -me-2'
          },
          '2xl': {
            base: 'ring-3 -me-2'
          },
          '3xl': {
            base: 'ring-3 -me-2'
          }
        },
        color: {
          primary: '',
          secondary: '',
          accent: '',
          success: '',
          info: '',
          warning: '',
          error: '',
          neutral: ''
        }
      },
      defaultVariants: {
        size: 'md',
        color: 'neutral'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/AvatarGroup.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/avatar-group.ts).


# Badge

## Uso

Use o slot padrão para definir o rótulo do Badge.

```vue
<template>
  <UBadge>
    Badge
  </UBadge>
</template>
```

### Label

Use a prop `label` para definir o rótulo do Badge.

```vue
<template>
  <UBadge label="Badge" />
</template>
```

### Cor

Use a prop `color` para alterar a cor do Badge.

```vue
<template>
  <UBadge color="neutral">
    Badge
  </UBadge>
</template>
```

### Variante

Use a prop `variant` para alterar a variante do Badge.

```vue
<template>
  <UBadge color="neutral" variant="outline">
    Badge
  </UBadge>
</template>
```

### Tamanho

Use a prop `size` para alterar o tamanho do Badge.

```vue
<template>
  <UBadge size="xl">
    Badge
  </UBadge>
</template>
```

### Ícone

Use a prop `icon` para exibir um [Icon](https://ui.nitro.news/docs/components/icon) dentro do Badge.

```vue
<template>
  <UBadge icon="i-lucide-rocket" size="md" color="primary" variant="solid">
    Badge
  </UBadge>
</template>
```

Use as props `leading` e `trailing` para definir a posição do ícone ou as props `leading-icon` e `trailing-icon` para definir um ícone diferente para cada posição.

```vue
<template>
  <UBadge trailing-icon="i-lucide-arrow-right" size="md">
    Badge
  </UBadge>
</template>
```

### Avatar

Use a prop `avatar` para exibir um [Avatar](https://ui.nitro.news/docs/components/avatar) dentro do Badge.

```vue
<template>
  <UBadge :avatar="{
  src: 'https://github.com/nuxt.png',
  loading: 'lazy'
}" size="md" color="neutral" variant="outline">
    Badge
  </UBadge>
</template>
```

## Exemplos

### `class` prop

Use a prop `class` para sobrescrever os estilos base do Badge.

```vue
<template>
  <UBadge class="font-bold rounded-full">
    Badge
  </UBadge>
</template>
```

## API

### Props

```ts
/**
 * Props for the Badge component
 */
interface BadgeProps {
  /**
   * The element or component this component should render as.
   * @default "\"span\""
   */
  as?: any;
  label?: string | number | undefined;
  color?: "error" | "primary" | "secondary" | "accent" | "success" | "info" | "warning" | "neutral" | undefined;
  variant?: "solid" | "outline" | "soft" | "subtle" | undefined;
  size?: "xs" | "sm" | "md" | "lg" | "xl" | undefined;
  /**
   * Render the badge with equal padding on all sides.
   */
  square?: boolean | undefined;
  ui?: { base?: SlotClass; label?: SlotClass; leadingIcon?: SlotClass; leadingAvatar?: SlotClass; leadingAvatarSize?: SlotClass; trailingIcon?: SlotClass; } | undefined;
  /**
   * Display an icon based on the `leading` and `trailing` props.
   */
  icon?: any;
  /**
   * Display an avatar on the left side.
   */
  avatar?: AvatarProps | undefined;
  /**
   * When `true`, the icon will be displayed on the left side.
   */
  leading?: boolean | undefined;
  /**
   * Display an icon on the left side.
   */
  leadingIcon?: any;
  /**
   * When `true`, the icon will be displayed on the right side.
   */
  trailing?: boolean | undefined;
  /**
   * Display an icon on the right side.
   */
  trailingIcon?: any;
}
```

### Slots

```ts
/**
 * Slots for the Badge component
 */
interface BadgeSlots {
  leading(): any;
  default(): any;
  trailing(): any;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    badge: {
      slots: {
        base: 'font-medium inline-flex items-center',
        label: 'truncate',
        leadingIcon: 'shrink-0',
        leadingAvatar: 'shrink-0',
        leadingAvatarSize: '',
        trailingIcon: 'shrink-0'
      },
      variants: {
        fieldGroup: {
          horizontal: 'not-only:first:rounded-e-none not-only:last:rounded-s-none not-last:not-first:rounded-none focus-visible:z-[1]',
          vertical: 'not-only:first:rounded-b-none not-only:last:rounded-t-none not-last:not-first:rounded-none focus-visible:z-[1]'
        },
        color: {
          primary: '',
          secondary: '',
          accent: '',
          success: '',
          info: '',
          warning: '',
          error: '',
          neutral: ''
        },
        variant: {
          solid: '',
          outline: '',
          soft: '',
          subtle: ''
        },
        size: {
          xs: {
            base: 'text-[8px]/3 px-1 py-0.5 gap-1 rounded-sm',
            leadingIcon: 'size-3',
            leadingAvatarSize: '3xs',
            trailingIcon: 'size-3'
          },
          sm: {
            base: 'text-[10px]/3 px-1.5 py-1 gap-1 rounded-sm',
            leadingIcon: 'size-3',
            leadingAvatarSize: '3xs',
            trailingIcon: 'size-3'
          },
          md: {
            base: 'text-xs px-2 py-1 gap-1 rounded-md',
            leadingIcon: 'size-4',
            leadingAvatarSize: '3xs',
            trailingIcon: 'size-4'
          },
          lg: {
            base: 'text-sm px-2 py-1 gap-1.5 rounded-md',
            leadingIcon: 'size-5',
            leadingAvatarSize: '2xs',
            trailingIcon: 'size-5'
          },
          xl: {
            base: 'text-base px-2.5 py-1 gap-1.5 rounded-md',
            leadingIcon: 'size-6',
            leadingAvatarSize: '2xs',
            trailingIcon: 'size-6'
          }
        },
        square: {
          true: ''
        }
      },
      compoundVariants: [
        {
          color: 'primary',
          variant: 'solid',
          class: 'bg-primary text-inverted'
        },
        {
          color: 'secondary',
          variant: 'solid',
          class: 'bg-secondary text-inverted'
        },
        {
          color: 'accent',
          variant: 'solid',
          class: 'bg-accent text-inverted'
        },
        {
          color: 'success',
          variant: 'solid',
          class: 'bg-success text-inverted'
        },
        {
          color: 'info',
          variant: 'solid',
          class: 'bg-info text-inverted'
        },
        {
          color: 'warning',
          variant: 'solid',
          class: 'bg-warning text-inverted'
        },
        {
          color: 'error',
          variant: 'solid',
          class: 'bg-error text-inverted'
        },
        {
          color: 'primary',
          variant: 'outline',
          class: 'text-primary ring ring-inset ring-primary/50'
        },
        {
          color: 'secondary',
          variant: 'outline',
          class: 'text-secondary ring ring-inset ring-secondary/50'
        },
        {
          color: 'accent',
          variant: 'outline',
          class: 'text-accent ring ring-inset ring-accent/50'
        },
        {
          color: 'success',
          variant: 'outline',
          class: 'text-success ring ring-inset ring-success/50'
        },
        {
          color: 'info',
          variant: 'outline',
          class: 'text-info ring ring-inset ring-info/50'
        },
        {
          color: 'warning',
          variant: 'outline',
          class: 'text-warning ring ring-inset ring-warning/50'
        },
        {
          color: 'error',
          variant: 'outline',
          class: 'text-error ring ring-inset ring-error/50'
        },
        {
          color: 'primary',
          variant: 'soft',
          class: 'bg-primary/10 text-primary'
        },
        {
          color: 'secondary',
          variant: 'soft',
          class: 'bg-secondary/10 text-secondary'
        },
        {
          color: 'accent',
          variant: 'soft',
          class: 'bg-accent/10 text-accent'
        },
        {
          color: 'success',
          variant: 'soft',
          class: 'bg-success/10 text-success'
        },
        {
          color: 'info',
          variant: 'soft',
          class: 'bg-info/10 text-info'
        },
        {
          color: 'warning',
          variant: 'soft',
          class: 'bg-warning/10 text-warning'
        },
        {
          color: 'error',
          variant: 'soft',
          class: 'bg-error/10 text-error'
        },
        {
          color: 'primary',
          variant: 'subtle',
          class: 'bg-primary/10 text-primary ring ring-inset ring-primary/25'
        },
        {
          color: 'secondary',
          variant: 'subtle',
          class: 'bg-secondary/10 text-secondary ring ring-inset ring-secondary/25'
        },
        {
          color: 'accent',
          variant: 'subtle',
          class: 'bg-accent/10 text-accent ring ring-inset ring-accent/25'
        },
        {
          color: 'success',
          variant: 'subtle',
          class: 'bg-success/10 text-success ring ring-inset ring-success/25'
        },
        {
          color: 'info',
          variant: 'subtle',
          class: 'bg-info/10 text-info ring ring-inset ring-info/25'
        },
        {
          color: 'warning',
          variant: 'subtle',
          class: 'bg-warning/10 text-warning ring ring-inset ring-warning/25'
        },
        {
          color: 'error',
          variant: 'subtle',
          class: 'bg-error/10 text-error ring ring-inset ring-error/25'
        },
        {
          color: 'neutral',
          variant: 'solid',
          class: 'text-inverted bg-inverted'
        },
        {
          color: 'neutral',
          variant: 'outline',
          class: 'ring ring-inset ring-accented text-default bg-default'
        },
        {
          color: 'neutral',
          variant: 'soft',
          class: 'text-default bg-elevated'
        },
        {
          color: 'neutral',
          variant: 'subtle',
          class: 'ring ring-inset ring-accented text-default bg-elevated'
        },
        {
          size: 'xs',
          square: true,
          class: 'p-0.5'
        },
        {
          size: 'sm',
          square: true,
          class: 'p-1'
        },
        {
          size: 'md',
          square: true,
          class: 'p-1'
        },
        {
          size: 'lg',
          square: true,
          class: 'p-1'
        },
        {
          size: 'xl',
          square: true,
          class: 'p-1'
        }
      ],
      defaultVariants: {
        color: 'primary',
        variant: 'solid',
        size: 'md'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/Badge.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/badge.ts).


# Banner

## Uso

### Título

Use a prop `title` para exibir um título no Banner.

```vue
<template>
  <UBanner title="This is a banner with an important message." />
</template>
```

### Ícone

Use a prop `icon` para exibir um ícone no Banner.

```vue
<template>
  <UBanner icon="i-lucide-info" title="This is a banner with an icon." />
</template>
```

### Cor

Use a prop `color` para alterar a cor do Banner.

```vue
<template>
  <UBanner color="neutral" icon="i-lucide-info" title="This is a banner with an icon." />
</template>
```

### Fechar

Use a prop `close` para exibir um [Button](https://ui.nitro.news/docs/components/button) para dispensar o Banner. O padrão é `false`.

> \[!TIP]
>
> Um evento `close` será emitido quando o botão de fechar for clicado.

::component-example
---
iframe:
  style: "height: 48px;"
overflowHidden: true
name: banner-example
---
#code
```vue
<template>
  <NBanner id="example" title="This is a closable banner." close />
</template>
```
::

> \[!NOTE]
>
> Quando fechado, `banner-${id}` será armazenado no local storage para evitar que ele seja exibido novamente. :br Para o exemplo acima, `banner-example` será armazenado no local storage.

> \[!CAUTION]
>
> Para persistir o estado de dispensado entre recarregamentos de página, você precisa especificar uma prop `id`. Sem um `id` explícito, o banner só ficará oculto na sessão atual e reaparecerá ao recarregar a página.

### Ícone de fechar

Use a prop `close-icon` para personalizar o [Icon](https://ui.nitro.news/docs/components/icon) do botão de fechar. O padrão é `i-lucide-x`.

::component-example
---
iframe:
  style: "height: 48px;"
overflowHidden: true
props:
  title: This is a closable banner with a custom close icon.
  closeIcon: i-lucide-x-circle
name: banner-example
---
#code
```vue
<template>
  <NBanner
    title="This is a closable banner with a custom close icon."
    close
    close-icon="i-lucide-x-circle"
  />
</template>
```
::

**Nuxt:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/nuxt#theme
>
> Você pode personalizar esse ícone globalmente no seu `app.config.ts` na chave `ui.icons.close`.

**Vue:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/vue#theme
>
> Você pode personalizar esse ícone globalmente no seu `vite.config.ts` na chave `ui.icons.close`.

### Ações

Use a prop `actions` para adicionar algumas ações de [Button](https://ui.nitro.news/docs/components/button) ao Banner.

```vue
<script setup lang="ts">
import type { ButtonProps } from '@nitro/ui'

const actions = ref<ButtonProps[]>([
  {
    label: "Action 1",
    variant: "outline"
  },
  {
    label: "Action 2",
    trailingIcon: "i-lucide-arrow-right"
  }
])
</script>

<template>
  <UBanner title="This is a banner with actions." :actions="actions" />
</template>
```

> \[!NOTE]
>
> Os botões de ação usam por padrão `color="neutral"` e `size="xs"`. Você pode personalizar esses valores passando-os diretamente para cada botão de ação.

### Link

Você pode passar qualquer propriedade do componente [`<NuxtLink>`](https://nuxt.com/docs/api/components/nuxt-link){rel="&#x22;nofollow&#x22;"}, como `to`, `target`, `rel`, etc.

```vue
<template>
  <UBanner to="https://nuxtlabs.com/" target="_blank" title="NuxtLabs is joining Vercel!" color="primary" />
</template>
```

> \[!NOTE]
>
> O componente `NuxtLink` herdará todos os outros atributos que você passar para o componente `User`.

## Exemplos

### Dentro de `app.vue`

Use o componente Banner no seu `app.vue` ou em um layout:

```vue [app.vue] {3}
<template>
  <NApp>
    <NBanner icon="i-lucide-construction" title="Nitro UI v4 has been released!" />

    <NHeader />

    <NMain>
      <NuxtLayout>
        <NuxtPage />
      </NuxtLayout>
    </NMain>

    <NFooter />
  </NApp>
</template>
```

## API

### Props

```ts
/**
 * Props for the Banner component
 */
interface BannerProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  /**
   * A unique id saved to local storage to remember if the banner has been dismissed.
   * Without an explicit id, the banner will not be persisted and will reappear on page reload.
   */
  id?: string | undefined;
  /**
   * The icon displayed next to the title.
   */
  icon?: any;
  title?: string | undefined;
  /**
   * Display a list of actions next to the title.
   * `{ color: 'neutral', size: 'xs' }`{lang="ts-type"}
   */
  actions?: ButtonProps[] | undefined;
  to?: string | it | et | undefined;
  target?: "_blank" | "_parent" | "_self" | "_top" | (string & {}) | null | undefined;
  color?: "error" | "primary" | "secondary" | "accent" | "success" | "info" | "warning" | "neutral" | undefined;
  /**
   * Display a close button to dismiss the banner.
   * `{ size: 'md', color: 'neutral', variant: 'ghost' }`{lang="ts-type"}
   */
  close?: boolean | Omit<ButtonProps, LinkPropsKeys> | undefined;
  /**
   * The icon displayed in the close button.
   */
  closeIcon?: any;
  ui?: { root?: SlotClass; container?: SlotClass; left?: SlotClass; center?: SlotClass; right?: SlotClass; icon?: SlotClass; title?: SlotClass; actions?: SlotClass; close?: SlotClass; } | undefined;
}
```

### Slots

```ts
/**
 * Slots for the Banner component
 */
interface BannerSlots {
  leading(): any;
  title(): any;
  actions(): any;
  close(): any;
}
```

### Emits

```ts
/**
 * Emitted events for the Banner component
 */
interface BannerEmits {
  close: (payload: []) => void;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    banner: {
      slots: {
        root: [
          'relative z-50 w-full',
          'transition-colors'
        ],
        container: 'flex items-center justify-between gap-3 h-12',
        left: 'hidden lg:flex-1 lg:flex lg:items-center',
        center: 'flex items-center gap-1.5 min-w-0',
        right: 'lg:flex-1 flex items-center justify-end',
        icon: 'size-5 shrink-0 text-inverted pointer-events-none',
        title: 'text-sm text-inverted font-medium truncate',
        actions: 'flex gap-1.5 shrink-0 isolate',
        close: 'text-inverted hover:bg-default/10 focus-visible:bg-default/10 -me-1.5 lg:me-0'
      },
      variants: {
        color: {
          primary: {
            root: 'bg-primary'
          },
          secondary: {
            root: 'bg-secondary'
          },
          accent: {
            root: 'bg-accent'
          },
          success: {
            root: 'bg-success'
          },
          info: {
            root: 'bg-info'
          },
          warning: {
            root: 'bg-warning'
          },
          error: {
            root: 'bg-error'
          },
          neutral: {
            root: 'bg-inverted'
          }
        },
        to: {
          true: ''
        }
      },
      compoundVariants: [
        {
          color: 'primary',
          to: true,
          class: {
            root: 'hover:bg-primary/90'
          }
        },
        {
          color: 'secondary',
          to: true,
          class: {
            root: 'hover:bg-secondary/90'
          }
        },
        {
          color: 'accent',
          to: true,
          class: {
            root: 'hover:bg-accent/90'
          }
        },
        {
          color: 'success',
          to: true,
          class: {
            root: 'hover:bg-success/90'
          }
        },
        {
          color: 'info',
          to: true,
          class: {
            root: 'hover:bg-info/90'
          }
        },
        {
          color: 'warning',
          to: true,
          class: {
            root: 'hover:bg-warning/90'
          }
        },
        {
          color: 'error',
          to: true,
          class: {
            root: 'hover:bg-error/90'
          }
        },
        {
          color: 'neutral',
          to: true,
          class: {
            root: 'hover:bg-inverted/90'
          }
        }
      ],
      defaultVariants: {
        color: 'primary'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/Banner.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/banner.ts).


# BlogPost

## Uso

O componente BlogPost oferece uma maneira flexível de exibir um elemento `<article>` com conteúdo personalizável, incluindo título, descrição, imagem, etc.

```vue
<template>
  <n-blog-post :authors=[{"name":"Anthony Fu","description":"antfu7","avatar":{"src":"https://github.com/antfu.png","loading":"lazy"},"to":"https://github.com/antfu","target":"_blank"}] date=2024-11-25 description=Conheça o Nuxt Icon v1 - uma solução de ícones moderna, versátil e personalizável para os seus projetos Nuxt. image=https://nuxt.com/assets/blog/nuxt-icon/cover.png target=_blank title=Apresentando o Nuxt Icon v1 to=https://nuxt.com/blog/nuxt-icon-v1-0 />
</template>
```

> \[!TIP]
> See: /docs/components/blog-posts
>
> Use o componente `BlogPosts` para exibir vários posts de blog em um layout de grade responsivo.

### Título

Use a prop `title` para exibir o título do BlogPost.

```vue
<template>
  <UBlogPost title="Introducing Nuxt Icon v1" />
</template>
```

### Descrição

Use a prop `description` para exibir a descrição do BlogPost.

```vue
<template>
  <UBlogPost title="Introducing Nuxt Icon v1" description="Discover Nuxt Icon v1 - a modern, versatile, and customizable icon solution for your Nuxt projects." />
</template>
```

### Dados

Use a prop `date` para exibir a data do BlogPost.

> \[!TIP]
>
> A data é formatada automaticamente para o [locale atual](https://ui.nitro.news/docs/getting-started/integrations/i18n/nuxt#locale). Você pode passar um objeto `Date` ou uma string.

```vue
<template>
  <UBlogPost title="Introducing Nuxt Icon v1" description="Discover Nuxt Icon v1 - a modern, versatile, and customizable icon solution for your Nuxt projects." date="2024-11-25" />
</template>
```

### Badge

Use a prop `badge` para exibir um [Badge](https://ui.nitro.news/docs/components/badge) no BlogPost.

```vue
<template>
  <UBlogPost title="Introducing Nuxt Icon v1" description="Discover Nuxt Icon v1 - a modern, versatile, and customizable icon solution for your Nuxt projects." badge="Release" />
</template>
```

Você pode passar qualquer propriedade do componente [Badge](https://ui.nitro.news/docs/components/badge#props) para personalizá-lo.

```vue
<template>
  <UBlogPost title="Introducing Nuxt Icon v1" description="Discover Nuxt Icon v1 - a modern, versatile, and customizable icon solution for your Nuxt projects." :badge="{
  label: 'Release',
  color: 'primary',
  variant: 'solid'
}" />
</template>
```

### Imagem

Use a prop `image` para exibir uma imagem no BlogPost.

> \[!NOTE]
>
> Se o [`@nuxt/image`](https://image.nuxt.com/get-started/installation){rel="&#x22;nofollow&#x22;"} estiver instalado, o componente `<NuxtImg>` será usado no lugar da tag `img` nativa.

```vue
<template>
  <UBlogPost title="Introducing Nuxt Icon v1" description="Discover Nuxt Icon v1 - a modern, versatile, and customizable icon solution for your Nuxt projects." image="https://nuxt.com/assets/blog/nuxt-icon/cover.png" date="2024-11-25" />
</template>
```

### Autores

Use a prop `authors` para exibir uma lista de [User](https://ui.nitro.news/docs/components/user) no BlogPost como um array de objetos com as seguintes propriedades:

- `name?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `description?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `avatar?: Omit<AvatarProps, 'size'>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `chip?: boolean | Omit<ChipProps, 'size' | 'inset'>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `size?: UserProps['size']`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `orientation?: UserProps['orientation']`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Você pode passar qualquer propriedade do componente [Link](https://ui.nitro.news/docs/components/link#props), como `to`, `target`, etc.

```vue
<script setup lang="ts">
import type { UserProps } from '@nitro/ui'

const authors = ref<UserProps[]>([
  {
    name: "Anthony Fu",
    description: "antfu7",
    avatar: {
      src: "https://github.com/antfu.png",
      loading: "lazy"
    },
    to: "https://github.com/antfu",
    target: "_blank"
  }
])
</script>

<template>
  <UBlogPost title="Introducing Nuxt Icon v1" description="Discover Nuxt Icon v1 - a modern, versatile, and customizable icon solution for your Nuxt projects." image="https://nuxt.com/assets/blog/nuxt-icon/cover.png" date="2024-11-25" :authors="authors" />
</template>
```

Quando a prop `authors` tem mais de um item, o componente [AvatarGroup](https://ui.nitro.news/docs/components/avatar-group) é usado.

```vue
<script setup lang="ts">
import type { UserProps } from '@nitro/ui'

const authors = ref<UserProps[]>([
  {
    name: "Anthony Fu",
    description: "antfu7",
    avatar: {
      src: "https://github.com/antfu.png",
      loading: "lazy"
    },
    to: "https://github.com/antfu",
    target: "_blank"
  },
  {
    name: "Benjamin Canac",
    description: "benjamincanac",
    avatar: {
      src: "https://github.com/benjamincanac.png",
      loading: "lazy"
    },
    to: "https://github.com/benjamincanac",
    target: "_blank"
  }
])
</script>

<template>
  <UBlogPost title="Introducing Nuxt Icon v1" description="Discover Nuxt Icon v1 - a modern, versatile, and customizable icon solution for your Nuxt projects." image="https://nuxt.com/assets/blog/nuxt-icon/cover.png" date="2024-11-25" :authors="authors" />
</template>
```

### Link

Você pode passar qualquer propriedade do componente [`<NuxtLink>`](https://nuxt.com/docs/api/components/nuxt-link){rel="&#x22;nofollow&#x22;"}, como `to`, `target`, `rel`, etc.

```vue
<template>
  <UBlogPost title="Introducing Nuxt Icon v1" description="Discover Nuxt Icon v1 - a modern, versatile, and customizable icon solution for your Nuxt projects." image="https://nuxt.com/assets/blog/nuxt-icon/cover.png" date="2024-11-25" to="https://nuxt.com/blog/nuxt-icon-v1-0" target="_blank" />
</template>
```

### Variante

Use a prop `variant` para alterar o estilo do BlogPost.

```vue
<template>
  <UBlogPost title="Introducing Nuxt Icon v1" description="Discover Nuxt Icon v1 - a modern, versatile, and customizable icon solution for your Nuxt projects." image="https://nuxt.com/assets/blog/nuxt-icon/cover.png" date="2024-11-25" to="https://nuxt.com/blog/nuxt-icon-v1-0" target="_blank" variant="naked" />
</template>
```

> \[!NOTE]
>
> A estilização será diferente conforme você forneça uma prop `to` ou uma `image`.

### Orientação

Use a prop `orientation` para alterar a orientação do BlogPost. O padrão é `vertical`.

```vue
<template>
  <UBlogPost title="Introducing Nuxt Icon v1" description="Discover Nuxt Icon v1 - a modern, versatile, and customizable icon solution for your Nuxt projects." image="https://nuxt.com/assets/blog/nuxt-icon/cover.png" date="2024-11-25" to="https://nuxt.com/blog/nuxt-icon-v1-0" target="_blank" orientation="horizontal" variant="outline" />
</template>
```

## API

### Props

```ts
/**
 * Props for the BlogPost component
 */
interface BlogPostProps {
  /**
   * The element or component this component should render as.
   * @default "\"article\""
   */
  as?: any;
  title?: string | undefined;
  description?: string | undefined;
  /**
   * The date of the blog post. Can be a string or a Date object.
   */
  date?: string | Date | undefined;
  /**
   * Display a badge on the blog post.
   * Can be a string or an object.
   * `{ color: 'neutral', variant: 'subtle' }`{lang="ts-type"}
   */
  badge?: string | BadgeProps | undefined;
  /**
   * The authors of the blog post.
   */
  authors?: UserProps[] | undefined;
  /**
   * The image of the blog post. Can be a string or an object.
   */
  image?: string | (Partial<ImgHTMLAttributes> & { [key: string]: any; }) | undefined;
  /**
   * The orientation of the blog post.
   * @default "\"vertical\""
   */
  orientation?: "vertical" | "horizontal" | undefined;
  variant?: "outline" | "soft" | "subtle" | "ghost" | "naked" | undefined;
  to?: string | it | et | undefined;
  target?: "_blank" | "_parent" | "_self" | "_top" | (string & {}) | null | undefined;
  onClick?: ((event: MouseEvent) => void) | undefined;
  ui?: { root?: SlotClass; header?: SlotClass; body?: SlotClass; footer?: SlotClass; image?: SlotClass; title?: SlotClass; description?: SlotClass; authors?: SlotClass; avatar?: SlotClass; meta?: SlotClass; date?: SlotClass; badge?: SlotClass; } | undefined;
}
```

### Slots

```ts
/**
 * Slots for the BlogPost component
 */
interface BlogPostSlots {
  date(): any;
  badge(): any;
  title(): any;
  description(): any;
  authors(): any;
  header(): any;
  body(): any;
  footer(): any;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    blogPost: {
      slots: {
        root: 'relative group/blog-post flex flex-col rounded-lg overflow-hidden',
        header: 'relative overflow-hidden aspect-[16/9] w-full pointer-events-none',
        body: 'min-w-0 flex-1 flex flex-col',
        footer: '',
        image: 'object-cover object-top w-full h-full',
        title: 'text-xl text-pretty font-semibold text-highlighted',
        description: 'mt-1 text-base text-pretty',
        authors: 'pt-4 mt-auto flex flex-wrap gap-x-3 gap-y-1.5',
        avatar: '',
        meta: 'flex items-center gap-2 mb-2',
        date: 'text-sm',
        badge: ''
      },
      variants: {
        orientation: {
          horizontal: {
            root: 'lg:grid lg:grid-cols-2 lg:items-center gap-x-8',
            body: 'justify-center p-4 sm:p-6 lg:px-0'
          },
          vertical: {
            root: 'flex flex-col',
            body: 'p-4 sm:p-6'
          }
        },
        variant: {
          outline: {
            root: 'bg-default ring ring-default',
            date: 'text-toned',
            description: 'text-muted'
          },
          soft: {
            root: 'bg-elevated/50',
            date: 'text-muted',
            description: 'text-toned'
          },
          subtle: {
            root: 'bg-elevated/50 ring ring-default',
            date: 'text-muted',
            description: 'text-toned'
          },
          ghost: {
            date: 'text-toned',
            description: 'text-muted',
            header: 'shadow-lg rounded-lg'
          },
          naked: {
            root: 'p-0 sm:p-0',
            date: 'text-toned',
            description: 'text-muted',
            header: 'shadow-lg rounded-lg'
          }
        },
        to: {
          true: {
            root: [
              'outline-primary/25 has-[>a:focus-visible]:outline-3',
              'transition'
            ],
            image: 'transform transition-transform duration-200 group-hover/blog-post:scale-110',
            avatar: 'inline-flex transform transition-transform duration-200 hover:scale-115 rounded-full outline-primary/25 focus-visible:outline-3'
          }
        },
        image: {
          true: ''
        }
      },
      compoundVariants: [
        {
          variant: 'outline',
          to: true,
          class: {
            root: 'hover:bg-elevated/50'
          }
        },
        {
          variant: 'soft',
          to: true,
          class: {
            root: 'hover:bg-elevated'
          }
        },
        {
          variant: 'subtle',
          to: true,
          class: {
            root: 'hover:bg-elevated hover:ring-accented'
          }
        },
        {
          variant: [
            'outline',
            'subtle'
          ],
          to: true,
          class: {
            root: 'has-[>a:focus-visible]:ring-primary'
          }
        },
        {
          variant: 'ghost',
          to: true,
          class: {
            root: 'hover:bg-elevated/50',
            header: [
              'group-hover/blog-post:shadow-none',
              'transition-all'
            ]
          }
        },
        {
          variant: 'ghost',
          to: true,
          orientation: 'vertical',
          class: {
            header: 'group-hover/blog-post:rounded-b-none'
          }
        },
        {
          variant: 'ghost',
          to: true,
          orientation: 'horizontal',
          class: {
            header: 'group-hover/blog-post:rounded-r-none'
          }
        },
        {
          orientation: 'vertical',
          image: false,
          variant: 'naked',
          class: {
            body: 'p-0 sm:p-0'
          }
        }
      ],
      defaultVariants: {
        variant: 'outline'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/BlogPost.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/blog-post.ts).


# BlogPosts

## Uso

O componente BlogPosts oferece um layout flexível para exibir uma lista de componentes [BlogPost](https://ui.nitro.news/docs/components/blog-post) usando o slot padrão ou a prop `posts`.

```vue {2,8}
<template>
  <NBlogPosts>
    <NBlogPost
      v-for="(post, index) in posts"
      :key="index"
      v-bind="post"
    />
  </NBlogPosts>
</template>
```

### Posts

Use a prop `posts` como um array de objetos com as propriedades do componente [BlogPost](https://ui.nitro.news/docs/components/blog-post#props).

```vue
<script setup lang="ts">
import type { BlogPostProps } from '@nitro/ui'

const posts = ref<BlogPostProps[]>([
  {
    title: "Nuxt Icon v1",
    description: "Discover Nuxt Icon v1!",
    image: "https://nuxt.com/assets/blog/nuxt-icon/cover.png",
    date: "2024-11-25"
  },
  {
    title: "Nuxt 3.14",
    description: "Nuxt 3.14 is out!",
    image: "https://nuxt.com/assets/blog/v3.14.png",
    date: "2024-11-04"
  },
  {
    title: "Nuxt 3.13",
    description: "Nuxt 3.13 is out!",
    image: "https://nuxt.com/assets/blog/v3.13.png",
    date: "2024-08-22"
  }
])
</script>

<template>
  <UBlogPosts :posts="posts" />
</template>
```

### Orientação

Use a prop `orientation` para alterar a orientação do BlogPosts. O padrão é `horizontal`.

```vue
<script setup lang="ts">
import type { BlogPostProps } from '@nitro/ui'

const posts = ref<BlogPostProps[]>([
  {
    title: "Nuxt Icon v1",
    description: "Discover Nuxt Icon v1!",
    image: "https://nuxt.com/assets/blog/nuxt-icon/cover.png",
    date: "2024-11-25"
  },
  {
    title: "Nuxt 3.14",
    description: "Nuxt 3.14 is out!",
    image: "https://nuxt.com/assets/blog/v3.14.png",
    date: "2024-11-04"
  },
  {
    title: "Nuxt 3.13",
    description: "Nuxt 3.13 is out!",
    image: "https://nuxt.com/assets/blog/v3.13.png",
    date: "2024-08-22"
  }
])
</script>

<template>
  <UBlogPosts orientation="vertical" :posts="posts" />
</template>
```

> \[!TIP]
>
> Ao usar a prop `posts` em vez do slot padrão, a `orientation` dos posts é invertida automaticamente, de `horizontal` para `vertical` e vice-versa.

## Exemplos

> \[!NOTE]
>
> Embora estes exemplos usem o [Nuxt Content](https://content.nuxt.com){rel="&#x22;nofollow&#x22;"}, os componentes podem ser integrados a qualquer sistema de gerenciamento de conteúdo.

### Dentro de uma página

Use o componente BlogPosts em uma página para criar uma página de blog:

```vue [pages/blog/index.vue] {11-18}
<script setup lang="ts">
const { data: posts } = await useAsyncData('posts', () => queryCollection('posts').all())
</script>

<template>
  <NPage>
    <NPageHero title="Blog" />

    <NPageBody>
      <NContainer>
        <NBlogPosts>
          <NBlogPost
            v-for="(post, index) in posts"
            :key="index"
            v-bind="post"
            :to="post.path"
          />
        </NBlogPosts>
      </NContainer>
    </NPageBody>
  </NPage>
</template>
```

> \[!NOTE]
>
> Neste exemplo, os `posts` são buscados usando `queryCollection` do módulo `@nuxt/content`.

> \[!TIP]
>
> A prop `to` é sobrescrita aqui, já que o `@nuxt/content` usa a propriedade `path`.

## API

### Props

```ts
/**
 * Props for the BlogPosts component
 */
interface BlogPostsProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  posts?: BlogPostProps[] | undefined;
  /**
   * The orientation of the blog posts.
   * @default "\"horizontal\""
   */
  orientation?: "horizontal" | "vertical" | undefined;
  ui?: { base?: any; } | undefined;
}
```

### Slots

```ts
/**
 * Slots for the BlogPosts component
 */
interface BlogPostsSlots {
  date(): any;
  badge(): any;
  title(): any;
  description(): any;
  authors(): any;
  header(): any;
  body(): any;
  footer(): any;
  default(): any;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    blogPosts: {
      base: 'flex flex-col gap-8 lg:gap-y-16',
      variants: {
        orientation: {
          horizontal: 'sm:grid sm:grid-cols-2 lg:grid-cols-3',
          vertical: ''
        }
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/BlogPosts.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/blog-posts.ts).


# Breadcrumb

## Uso

Use o componente Breadcrumb para mostrar a localização da página atual na hierarquia do seu site.

```vue
<script setup lang="ts">
import type { BreadcrumbItem } from '@nitro/ui'

const items = ref<BreadcrumbItem[]>([
  {
    label: "Docs",
    icon: "i-lucide-book-open",
    to: "/docs"
  },
  {
    label: "Components",
    icon: "i-lucide-box",
    to: "/docs/components"
  },
  {
    label: "Breadcrumb",
    icon: "i-lucide-link",
    to: "/docs/components/breadcrumb"
  }
])
</script>

<template>
  <UBreadcrumb :items="items" />
</template>
```

### Itens

Use a prop `items` como um array de objetos com as seguintes propriedades:

- `label?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `icon?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `avatar?: AvatarProps`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- [`slot?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}](https://ui.nitro.news/#with-custom-slot)
- `class?: any`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `ui?: { item?: ClassNameValue, link?: ClassNameValue, linkLeadingIcon?: ClassNameValue, linkLeadingAvatar?: ClassNameValue, linkLabel?: ClassNameValue, separator?: ClassNameValue, separatorIcon?: ClassNameValue }`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Você pode passar qualquer propriedade do componente [Link](https://ui.nitro.news/docs/components/link#props), como `to`, `target`, etc.

```vue
<script setup lang="ts">
import type { BreadcrumbItem } from '@nitro/ui'

const items = ref<BreadcrumbItem[]>([
  {
    label: "Docs",
    icon: "i-lucide-book-open",
    to: "/docs"
  },
  {
    label: "Components",
    icon: "i-lucide-box",
    to: "/docs/components"
  },
  {
    label: "Breadcrumb",
    icon: "i-lucide-link",
    to: "/docs/components/breadcrumb"
  }
])
</script>

<template>
  <UBreadcrumb :items="items" />
</template>
```

> \[!NOTE]
>
> Um `span` é renderizado em vez de um link quando a propriedade `to` não é definida.

### Ícone de separador

Use a prop `separator-icon` para personalizar o [Icon](https://ui.nitro.news/docs/components/icon) entre cada item. O padrão é `i-lucide-chevron-right`.

```vue
<script setup lang="ts">
import type { BreadcrumbItem } from '@nitro/ui'

const items = ref<BreadcrumbItem[]>([
  {
    label: "Docs",
    icon: "i-lucide-book-open",
    to: "/docs"
  },
  {
    label: "Components",
    icon: "i-lucide-box",
    to: "/docs/components"
  },
  {
    label: "Breadcrumb",
    icon: "i-lucide-link",
    to: "/docs/components/breadcrumb"
  }
])
</script>

<template>
  <UBreadcrumb separator-icon="i-lucide-arrow-right" :items="items" />
</template>
```

**Nuxt:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/nuxt#theme
>
> Você pode personalizar esse ícone globalmente no seu `app.config.ts` na chave `ui.icons.chevronRight`.

**Vue:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/vue#theme
>
> Você pode personalizar esse ícone globalmente no seu `vite.config.ts` na chave `ui.icons.chevronRight`.

### Cor `4.8+`

Use a prop `color` para alterar a cor do Breadcrumb ativo.

```vue
<script setup lang="ts">
import type { BreadcrumbItem } from '@nitro/ui'

const items = ref<BreadcrumbItem[]>([
  {
    label: "Docs",
    icon: "i-lucide-book-open",
    to: "/docs"
  },
  {
    label: "Components",
    icon: "i-lucide-box",
    to: "/docs/components"
  },
  {
    label: "Breadcrumb",
    icon: "i-lucide-link",
    to: "/docs/components/breadcrumb"
  }
])
</script>

<template>
  <UBreadcrumb color="secondary" :items="items" />
</template>
```

## Exemplos

### Com slot de separador

Use o slot `#separator` para personalizar o separador entre cada item.

:component-example{name="breadcrumb-separator-slot-example"}

### Com slot personalizado

Use a propriedade `slot` para personalizar um item específico.

Você terá acesso aos seguintes slots:

- `#{{ item.slot }}`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `#{{ item.slot }}-leading`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `#{{ item.slot }}-label`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `#{{ item.slot }}-trailing`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

:component-example{name="breadcrumb-custom-slot-example"}

> \[!TIP]
> See: #slots
>
> Você também pode usar os slots `#item`, `#item-leading`, `#item-label` e `#item-trailing` para personalizar todos os itens.

## API

### Props

```ts
/**
 * Props for the Breadcrumb component
 */
interface BreadcrumbProps {
  /**
   * The element or component this component should render as.
   * @default "\"nav\""
   */
  as?: any;
  items?: T[] | undefined;
  /**
   * The icon to use as a separator.
   */
  separatorIcon?: any;
  /**
   * The key used to get the label from the item.
   * @default "\"label\""
   */
  labelKey?: GetItemKeys<T> | undefined;
  ui?: { root?: SlotClass; list?: SlotClass; item?: SlotClass; link?: SlotClass; linkLeadingIcon?: SlotClass; linkLeadingAvatar?: SlotClass; linkLeadingAvatarSize?: SlotClass; linkLabel?: SlotClass; separator?: SlotClass; separatorIcon?: SlotClass; } | undefined;
}
```

### Slots

```ts
/**
 * Slots for the Breadcrumb component
 */
interface BreadcrumbSlots {
  item(): any;
  item-leading(): any;
  item-label(): any;
  item-trailing(): any;
  separator(): any;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    breadcrumb: {
      slots: {
        root: 'relative min-w-0',
        list: 'flex items-center gap-1.5',
        item: 'flex min-w-0',
        link: 'group relative flex items-center gap-1.5 text-sm min-w-0 rounded-md',
        linkLeadingIcon: 'shrink-0 size-5',
        linkLeadingAvatar: 'shrink-0',
        linkLeadingAvatarSize: '2xs',
        linkLabel: 'truncate',
        separator: 'flex',
        separatorIcon: 'shrink-0 size-5 text-muted'
      },
      variants: {
        active: {
          true: {
            link: 'font-semibold'
          },
          false: {
            link: 'text-muted font-medium'
          }
        },
        disabled: {
          true: {
            link: 'cursor-not-allowed opacity-75'
          }
        },
        to: {
          true: ''
        },
        color: {
          primary: {
            link: 'outline-primary/25 focus-visible:outline-3'
          },
          secondary: {
            link: 'outline-secondary/25 focus-visible:outline-3'
          },
          accent: {
            link: 'outline-accent/25 focus-visible:outline-3'
          },
          success: {
            link: 'outline-success/25 focus-visible:outline-3'
          },
          info: {
            link: 'outline-info/25 focus-visible:outline-3'
          },
          warning: {
            link: 'outline-warning/25 focus-visible:outline-3'
          },
          error: {
            link: 'outline-error/25 focus-visible:outline-3'
          },
          neutral: {
            link: 'outline-inverted/25 focus-visible:outline-3'
          }
        }
      },
      compoundVariants: [
        {
          disabled: false,
          active: false,
          to: true,
          class: {
            link: [
              'hover:text-default',
              'transition-colors'
            ]
          }
        },
        {
          color: 'primary',
          active: true,
          class: {
            link: 'text-primary'
          }
        },
        {
          color: 'secondary',
          active: true,
          class: {
            link: 'text-secondary'
          }
        },
        {
          color: 'accent',
          active: true,
          class: {
            link: 'text-accent'
          }
        },
        {
          color: 'success',
          active: true,
          class: {
            link: 'text-success'
          }
        },
        {
          color: 'info',
          active: true,
          class: {
            link: 'text-info'
          }
        },
        {
          color: 'warning',
          active: true,
          class: {
            link: 'text-warning'
          }
        },
        {
          color: 'error',
          active: true,
          class: {
            link: 'text-error'
          }
        },
        {
          color: 'neutral',
          active: true,
          class: {
            link: 'text-highlighted'
          }
        }
      ],
      defaultVariants: {
        color: 'primary'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/Breadcrumb.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/breadcrumb.ts).


# Button

## Uso

Use o slot padrão para definir o rótulo do Button.

```vue
<template>
  <UButton>
    Button
  </UButton>
</template>
```

### Label

Use a prop `label` para definir o rótulo do Button.

```vue
<template>
  <UButton label="Button" />
</template>
```

### Cor

Use a prop `color` para alterar a cor do Button.

```vue
<template>
  <UButton color="neutral">
    Button
  </UButton>
</template>
```

### Variante

Use a prop `variant` para alterar a variante do Button.

```vue
<template>
  <UButton color="neutral" variant="outline">
    Button
  </UButton>
</template>
```

### Tamanho

Use a prop `size` para alterar o tamanho do Button.

```vue
<template>
  <UButton size="xl">
    Button
  </UButton>
</template>
```

### Ícone

Use a prop `icon` para exibir um [Icon](https://ui.nitro.news/docs/components/icon) dentro do Button.

```vue
<template>
  <UButton icon="i-lucide-rocket" size="md" color="primary" variant="solid">
    Button
  </UButton>
</template>
```

Use as props `leading` e `trailing` para definir a posição do ícone ou as props `leading-icon` e `trailing-icon` para definir um ícone diferente para cada posição.

```vue
<template>
  <UButton trailing-icon="i-lucide-arrow-right" size="md">
    Button
  </UButton>
</template>
```

O `label`, como prop ou slot, é opcional, então você pode usar o Button como um botão apenas com ícone.

```vue
<template>
  <UButton icon="i-lucide-search" size="md" color="primary" variant="solid" />
</template>
```

### Avatar

Use a prop `avatar` para exibir um [Avatar](https://ui.nitro.news/docs/components/avatar) dentro do Button.

```vue
<template>
  <UButton :avatar="{
  src: 'https://github.com/nuxt.png',
  loading: 'lazy'
}" size="md" color="neutral" variant="outline">
    Button
  </UButton>
</template>
```

O `label`, como prop ou slot, é opcional, então você pode usar o Button como um botão apenas com avatar.

```vue
<template>
  <UButton :avatar="{
  src: 'https://github.com/nuxt.png',
  loading: 'lazy'
}" size="md" color="neutral" variant="outline" />
</template>
```

### Link

Você pode passar qualquer propriedade do componente [Link](https://ui.nitro.news/docs/components/link#props), como `to`, `target`, etc.

```vue
<template>
  <UButton to="https://github.com/nuxt/ui" target="_blank">
    Button
  </UButton>
</template>
```

Quando o Button é um link ou ao usar a prop `active`, você pode usar as props `active-color` e `active-variant` para personalizar o estado ativo.

```vue
<template>
  <UButton active color="neutral" variant="outline" active-color="primary" active-variant="solid">
    Button
  </UButton>
</template>
```

Você também pode usar as props `active-class` e `inactive-class` para personalizar o estado ativo.

```vue
<template>
  <UButton active active-class="font-bold" inactive-class="font-light">
    Button
  </UButton>
</template>
```

> \[!TIP]
>
> Você pode configurar esses estilos globalmente no seu arquivo `app.config.ts`, na chave `ui.button.variants.active`.
>
> ```ts
> export default defineAppConfig({
>   ui: {
>     button: {
>       variants: {
>         active: {
>           true: {
>             base: 'font-bold'
>           }
>         }
>       }
>     }
>   }
> })
> ```

### Carregando

Use a prop `loading` para exibir um ícone de carregamento e desabilitar o Button.

```vue
<template>
  <UButton loading :trailing="false">
    Button
  </UButton>
</template>
```

Use a prop `loading-auto` para exibir o ícone de carregamento automaticamente enquanto a promise do `@click` está pendente.

:component-example{name="button-loading-auto-example"}

Isso também funciona com o componente [Form](https://ui.nitro.news/docs/components/form).

:component-example{name="button-loading-auto-form-example"}

### Ícone de carregamento

Use a prop `loading-icon` para personalizar o ícone de carregamento. O padrão é `i-lucide-loader-circle`.

```vue
<template>
  <UButton loading loading-icon="i-lucide-loader">
    Button
  </UButton>
</template>
```

**Nuxt:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/nuxt#theme
>
> Você pode personalizar esse ícone globalmente no seu `app.config.ts` na chave `ui.icons.loading`.

**Vue:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/vue#theme
>
> Você pode personalizar esse ícone globalmente no seu `vite.config.ts` na chave `ui.icons.loading`.

### Desabilitado

Use a prop `disabled` para desabilitar o Button.

```vue
<template>
  <UButton disabled>
    Button
  </UButton>
</template>
```

## Exemplos

### `class` prop

Use a prop `class` para sobrescrever os estilos base do Button.

```vue
<template>
  <UButton class="font-bold rounded-full">
    Button
  </UButton>
</template>
```

### `ui` prop

Use a prop `ui` para sobrescrever os estilos dos slots do Button.

```vue
<template>
  <UButton icon="i-lucide-rocket" color="neutral" variant="outline" :ui="{
  leadingIcon: 'text-primary'
}">
    Button
  </UButton>
</template>
```

## API

### Props

```ts
/**
 * Props for the Button component
 */
interface ButtonProps {
  label?: string | undefined;
  color?: "error" | "primary" | "secondary" | "accent" | "success" | "info" | "warning" | "neutral" | undefined;
  activeColor?: "error" | "primary" | "secondary" | "accent" | "success" | "info" | "warning" | "neutral" | undefined;
  variant?: "solid" | "outline" | "soft" | "subtle" | "ghost" | "link" | undefined;
  activeVariant?: "solid" | "outline" | "soft" | "subtle" | "ghost" | "link" | undefined;
  size?: "xs" | "sm" | "md" | "lg" | "xl" | undefined;
  /**
   * Render the button with equal padding on all sides.
   */
  square?: boolean | undefined;
  /**
   * Render the button full width.
   */
  block?: boolean | undefined;
  /**
   * Set loading state automatically based on the `@click` promise state
   */
  loadingAuto?: boolean | undefined;
  onClick?: ((event: MouseEvent) => void) | ((event: MouseEvent) => void)[] | undefined;
  ui?: { base?: SlotClass; label?: SlotClass; leadingIcon?: SlotClass; leadingAvatar?: SlotClass; leadingAvatarSize?: SlotClass; trailingIcon?: SlotClass; } | undefined;
  /**
   * Display an icon based on the `leading` and `trailing` props.
   */
  icon?: any;
  /**
   * Display an avatar on the left side.
   */
  avatar?: AvatarProps | undefined;
  /**
   * When `true`, the icon will be displayed on the left side.
   */
  leading?: boolean | undefined;
  /**
   * Display an icon on the left side.
   */
  leadingIcon?: any;
  /**
   * When `true`, the icon will be displayed on the right side.
   */
  trailing?: boolean | undefined;
  /**
   * Display an icon on the right side.
   */
  trailingIcon?: any;
  /**
   * When `true`, the loading icon will be displayed.
   */
  loading?: boolean | undefined;
  /**
   * The icon when the `loading` prop is `true`.
   */
  loadingIcon?: any;
  /**
   * Route Location the link should navigate to when clicked on.
   */
  to?: string | it | et | undefined;
  /**
   * Class to apply when the link is active
   */
  activeClass?: string | undefined;
  /**
   * Class to apply when the link is exact active
   */
  exactActiveClass?: string | undefined;
  /**
   * Value passed to the attribute `aria-current` when the link is exact active.
   */
  ariaCurrentValue?: "page" | "step" | "location" | "date" | "time" | "true" | "false" | undefined;
  /**
   * Pass the returned promise of `router.push()` to `document.startViewTransition()` if supported.
   */
  viewTransition?: boolean | undefined;
  /**
   * Calls `router.replace` instead of `router.push`.
   */
  replace?: boolean | undefined;
  autofocus?: Booleanish | undefined;
  disabled?: boolean | undefined;
  form?: string | undefined;
  formaction?: string | undefined;
  formenctype?: string | undefined;
  formmethod?: string | undefined;
  formnovalidate?: Booleanish | undefined;
  formtarget?: string | undefined;
  name?: string | undefined;
  /**
   * The type of the button when not a link.
   */
  type?: "reset" | "submit" | "button" | undefined;
  download?: any;
  /**
   * An alias for `to`. If used with `to`, `href` will be ignored
   */
  href?: string | it | et | undefined;
  hreflang?: string | undefined;
  media?: string | undefined;
  ping?: string | undefined;
  /**
   * A rel attribute value to apply on the link. Defaults to "noopener noreferrer" for external links.
   */
  rel?: "noopener" | "noreferrer" | "nofollow" | "sponsored" | "ugc" | (string & {}) | null | undefined;
  /**
   * Where to display the linked URL, as the name for a browsing context.
   */
  target?: (string & {}) | "_blank" | "_parent" | "_self" | "_top" | null | undefined;
  referrerpolicy?: HTMLAttributeReferrerPolicy | undefined;
  /**
   * The element or component this component should render as when not a link.
   */
  as?: any;
  /**
   * Force the link to be active independent of the current route.
   */
  active?: boolean | undefined;
  /**
   * Will only be active if the current route is an exact match.
   */
  exact?: boolean | undefined;
  /**
   * Allows controlling how the current route query sets the link as active.
   */
  exactQuery?: boolean | "partial" | undefined;
  /**
   * Will only be active if the current route hash is an exact match.
   */
  exactHash?: boolean | undefined;
  /**
   * The class to apply when the link is inactive.
   */
  inactiveClass?: string | undefined;
  /**
   * Control i18n auto-localization when `@nuxtjs/i18n` is installed.
   * - `undefined` / `true` (default): auto-localizes to the current locale using `$localePath`.
   *   Paths already carrying a locale prefix (from e.g. `switchLocalePath()`) are detected
   *   and left untouched to prevent double-prefixing.
   * - `false`: explicitly disables auto-localization.
   * - `string`: localizes to a specific locale (e.g. `'fr'`).
   */
  locale?: string | boolean | undefined;
  /**
   * Forces the link to be considered as external (true) or internal (false). This is helpful to handle edge-cases
   */
  external?: boolean | undefined;
  /**
   * If set to true, no rel attribute will be added to the link
   */
  noRel?: boolean | undefined;
  /**
   * A class to apply to links that have been prefetched.
   */
  prefetchedClass?: string | undefined;
  /**
   * When enabled will prefetch middleware, layouts and payloads of links in the viewport.
   */
  prefetch?: boolean | undefined;
  /**
   * Allows controlling when to prefetch links. By default, prefetch is triggered only on visibility.
   */
  prefetchOn?: "visibility" | "interaction" | Partial<{ visibility: boolean; interaction: boolean; }> | undefined;
  /**
   * Escape hatch to disable `prefetch` attribute.
   */
  noPrefetch?: boolean | undefined;
  /**
   * An option to either add or remove trailing slashes in the `href` for this specific link.
   * Overrides the global `trailingSlash` option if provided.
   */
  trailingSlash?: "remove" | "append" | undefined;
}
```

> \[!NOTE]
> See: https\://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attributes
>
> Este componente também suporta todos os atributos HTML nativos de `<button>`.

> \[!NOTE]
> See: https\://gitlab.nitro.news/nitro/ui/-/blob/main/src/runtime/components/Link.vue#L13
>
> O componente `Button` estende o componente `Link`. Confira o código-fonte no GitHub.

### Slots

```ts
/**
 * Slots for the Button component
 */
interface ButtonSlots {
  leading(): any;
  default(): any;
  trailing(): any;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    button: {
      slots: {
        base: [
          'rounded-full font-medium inline-flex items-center disabled:cursor-not-allowed aria-disabled:cursor-not-allowed disabled:opacity-75 aria-disabled:opacity-75',
          'transition-colors'
        ],
        label: 'truncate uppercase',
        leadingIcon: 'shrink-0',
        leadingAvatar: 'shrink-0',
        leadingAvatarSize: '',
        trailingIcon: 'shrink-0'
      },
      variants: {
        fieldGroup: {
          horizontal: 'not-only:first:rounded-e-none not-only:last:rounded-s-none not-last:not-first:rounded-none focus-visible:z-[1]',
          vertical: 'not-only:first:rounded-b-none not-only:last:rounded-t-none not-last:not-first:rounded-none focus-visible:z-[1]'
        },
        color: {
          primary: '',
          secondary: '',
          accent: '',
          success: '',
          info: '',
          warning: '',
          error: '',
          neutral: ''
        },
        variant: {
          solid: '',
          outline: '',
          soft: '',
          subtle: '',
          ghost: '',
          link: ''
        },
        size: {
          xs: {
            base: 'px-2 py-1 text-xs gap-1',
            leadingIcon: 'size-4',
            leadingAvatarSize: '3xs',
            trailingIcon: 'size-4'
          },
          sm: {
            base: 'px-2.5 py-1.5 text-xs gap-1.5',
            leadingIcon: 'size-4',
            leadingAvatarSize: '3xs',
            trailingIcon: 'size-4'
          },
          md: {
            base: 'px-2.5 py-1.5 text-sm gap-1.5',
            leadingIcon: 'size-5',
            leadingAvatarSize: '2xs',
            trailingIcon: 'size-5'
          },
          lg: {
            base: 'px-3 py-2 text-sm gap-2',
            leadingIcon: 'size-5',
            leadingAvatarSize: '2xs',
            trailingIcon: 'size-5'
          },
          xl: {
            base: 'px-3 py-2 text-base gap-2',
            leadingIcon: 'size-6',
            leadingAvatarSize: 'xs',
            trailingIcon: 'size-6'
          }
        },
        block: {
          true: {
            base: 'w-full justify-center',
            trailingIcon: 'ms-auto'
          }
        },
        square: {
          true: ''
        },
        leading: {
          true: ''
        },
        trailing: {
          true: ''
        },
        loading: {
          true: ''
        },
        active: {
          true: {
            base: ''
          },
          false: {
            base: ''
          }
        }
      },
      compoundVariants: [
        {
          color: 'primary',
          variant: 'solid',
          class: 'text-inverted bg-primary hover:bg-primary/75 active:bg-primary/75 disabled:bg-primary aria-disabled:bg-primary outline-primary/25 focus-visible:outline-3'
        },
        {
          color: 'secondary',
          variant: 'solid',
          class: 'text-inverted bg-secondary hover:bg-secondary/75 active:bg-secondary/75 disabled:bg-secondary aria-disabled:bg-secondary outline-secondary/25 focus-visible:outline-3'
        },
        {
          color: 'accent',
          variant: 'solid',
          class: 'text-inverted bg-accent hover:bg-accent/75 active:bg-accent/75 disabled:bg-accent aria-disabled:bg-accent outline-accent/25 focus-visible:outline-3'
        },
        {
          color: 'success',
          variant: 'solid',
          class: 'text-inverted bg-success hover:bg-success/75 active:bg-success/75 disabled:bg-success aria-disabled:bg-success outline-success/25 focus-visible:outline-3'
        },
        {
          color: 'info',
          variant: 'solid',
          class: 'text-inverted bg-info hover:bg-info/75 active:bg-info/75 disabled:bg-info aria-disabled:bg-info outline-info/25 focus-visible:outline-3'
        },
        {
          color: 'warning',
          variant: 'solid',
          class: 'text-inverted bg-warning hover:bg-warning/75 active:bg-warning/75 disabled:bg-warning aria-disabled:bg-warning outline-warning/25 focus-visible:outline-3'
        },
        {
          color: 'error',
          variant: 'solid',
          class: 'text-inverted bg-error hover:bg-error/75 active:bg-error/75 disabled:bg-error aria-disabled:bg-error outline-error/25 focus-visible:outline-3'
        },
        {
          color: 'primary',
          variant: 'outline',
          class: 'ring ring-inset ring-primary/50 text-primary hover:bg-primary/10 active:bg-primary/10 disabled:bg-transparent aria-disabled:bg-transparent dark:disabled:bg-transparent dark:aria-disabled:bg-transparent outline-primary/25 focus-visible:outline-3 focus-visible:ring-primary'
        },
        {
          color: 'secondary',
          variant: 'outline',
          class: 'ring ring-inset ring-secondary/50 text-secondary hover:bg-secondary/10 active:bg-secondary/10 disabled:bg-transparent aria-disabled:bg-transparent dark:disabled:bg-transparent dark:aria-disabled:bg-transparent outline-secondary/25 focus-visible:outline-3 focus-visible:ring-secondary'
        },
        {
          color: 'accent',
          variant: 'outline',
          class: 'ring ring-inset ring-accent/50 text-accent hover:bg-accent/10 active:bg-accent/10 disabled:bg-transparent aria-disabled:bg-transparent dark:disabled:bg-transparent dark:aria-disabled:bg-transparent outline-accent/25 focus-visible:outline-3 focus-visible:ring-accent'
        },
        {
          color: 'success',
          variant: 'outline',
          class: 'ring ring-inset ring-success/50 text-success hover:bg-success/10 active:bg-success/10 disabled:bg-transparent aria-disabled:bg-transparent dark:disabled:bg-transparent dark:aria-disabled:bg-transparent outline-success/25 focus-visible:outline-3 focus-visible:ring-success'
        },
        {
          color: 'info',
          variant: 'outline',
          class: 'ring ring-inset ring-info/50 text-info hover:bg-info/10 active:bg-info/10 disabled:bg-transparent aria-disabled:bg-transparent dark:disabled:bg-transparent dark:aria-disabled:bg-transparent outline-info/25 focus-visible:outline-3 focus-visible:ring-info'
        },
        {
          color: 'warning',
          variant: 'outline',
          class: 'ring ring-inset ring-warning/50 text-warning hover:bg-warning/10 active:bg-warning/10 disabled:bg-transparent aria-disabled:bg-transparent dark:disabled:bg-transparent dark:aria-disabled:bg-transparent outline-warning/25 focus-visible:outline-3 focus-visible:ring-warning'
        },
        {
          color: 'error',
          variant: 'outline',
          class: 'ring ring-inset ring-error/50 text-error hover:bg-error/10 active:bg-error/10 disabled:bg-transparent aria-disabled:bg-transparent dark:disabled:bg-transparent dark:aria-disabled:bg-transparent outline-error/25 focus-visible:outline-3 focus-visible:ring-error'
        },
        {
          color: 'primary',
          variant: 'soft',
          class: 'text-primary bg-primary/10 hover:bg-primary/15 active:bg-primary/15 outline-primary/25 focus-visible:outline-3 disabled:bg-primary/10 aria-disabled:bg-primary/10'
        },
        {
          color: 'secondary',
          variant: 'soft',
          class: 'text-secondary bg-secondary/10 hover:bg-secondary/15 active:bg-secondary/15 outline-secondary/25 focus-visible:outline-3 disabled:bg-secondary/10 aria-disabled:bg-secondary/10'
        },
        {
          color: 'accent',
          variant: 'soft',
          class: 'text-accent bg-accent/10 hover:bg-accent/15 active:bg-accent/15 outline-accent/25 focus-visible:outline-3 disabled:bg-accent/10 aria-disabled:bg-accent/10'
        },
        {
          color: 'success',
          variant: 'soft',
          class: 'text-success bg-success/10 hover:bg-success/15 active:bg-success/15 outline-success/25 focus-visible:outline-3 disabled:bg-success/10 aria-disabled:bg-success/10'
        },
        {
          color: 'info',
          variant: 'soft',
          class: 'text-info bg-info/10 hover:bg-info/15 active:bg-info/15 outline-info/25 focus-visible:outline-3 disabled:bg-info/10 aria-disabled:bg-info/10'
        },
        {
          color: 'warning',
          variant: 'soft',
          class: 'text-warning bg-warning/10 hover:bg-warning/15 active:bg-warning/15 outline-warning/25 focus-visible:outline-3 disabled:bg-warning/10 aria-disabled:bg-warning/10'
        },
        {
          color: 'error',
          variant: 'soft',
          class: 'text-error bg-error/10 hover:bg-error/15 active:bg-error/15 outline-error/25 focus-visible:outline-3 disabled:bg-error/10 aria-disabled:bg-error/10'
        },
        {
          color: 'primary',
          variant: 'subtle',
          class: 'text-primary ring ring-inset ring-primary/25 bg-primary/10 hover:bg-primary/15 active:bg-primary/15 disabled:bg-primary/10 aria-disabled:bg-primary/10 outline-primary/25 focus-visible:outline-3 focus-visible:ring-primary'
        },
        {
          color: 'secondary',
          variant: 'subtle',
          class: 'text-secondary ring ring-inset ring-secondary/25 bg-secondary/10 hover:bg-secondary/15 active:bg-secondary/15 disabled:bg-secondary/10 aria-disabled:bg-secondary/10 outline-secondary/25 focus-visible:outline-3 focus-visible:ring-secondary'
        },
        {
          color: 'accent',
          variant: 'subtle',
          class: 'text-accent ring ring-inset ring-accent/25 bg-accent/10 hover:bg-accent/15 active:bg-accent/15 disabled:bg-accent/10 aria-disabled:bg-accent/10 outline-accent/25 focus-visible:outline-3 focus-visible:ring-accent'
        },
        {
          color: 'success',
          variant: 'subtle',
          class: 'text-success ring ring-inset ring-success/25 bg-success/10 hover:bg-success/15 active:bg-success/15 disabled:bg-success/10 aria-disabled:bg-success/10 outline-success/25 focus-visible:outline-3 focus-visible:ring-success'
        },
        {
          color: 'info',
          variant: 'subtle',
          class: 'text-info ring ring-inset ring-info/25 bg-info/10 hover:bg-info/15 active:bg-info/15 disabled:bg-info/10 aria-disabled:bg-info/10 outline-info/25 focus-visible:outline-3 focus-visible:ring-info'
        },
        {
          color: 'warning',
          variant: 'subtle',
          class: 'text-warning ring ring-inset ring-warning/25 bg-warning/10 hover:bg-warning/15 active:bg-warning/15 disabled:bg-warning/10 aria-disabled:bg-warning/10 outline-warning/25 focus-visible:outline-3 focus-visible:ring-warning'
        },
        {
          color: 'error',
          variant: 'subtle',
          class: 'text-error ring ring-inset ring-error/25 bg-error/10 hover:bg-error/15 active:bg-error/15 disabled:bg-error/10 aria-disabled:bg-error/10 outline-error/25 focus-visible:outline-3 focus-visible:ring-error'
        },
        {
          color: 'primary',
          variant: 'ghost',
          class: 'text-primary hover:bg-primary/10 active:bg-primary/10 outline-primary/25 focus-visible:outline-3 disabled:bg-transparent aria-disabled:bg-transparent dark:disabled:bg-transparent dark:aria-disabled:bg-transparent'
        },
        {
          color: 'secondary',
          variant: 'ghost',
          class: 'text-secondary hover:bg-secondary/10 active:bg-secondary/10 outline-secondary/25 focus-visible:outline-3 disabled:bg-transparent aria-disabled:bg-transparent dark:disabled:bg-transparent dark:aria-disabled:bg-transparent'
        },
        {
          color: 'accent',
          variant: 'ghost',
          class: 'text-accent hover:bg-accent/10 active:bg-accent/10 outline-accent/25 focus-visible:outline-3 disabled:bg-transparent aria-disabled:bg-transparent dark:disabled:bg-transparent dark:aria-disabled:bg-transparent'
        },
        {
          color: 'success',
          variant: 'ghost',
          class: 'text-success hover:bg-success/10 active:bg-success/10 outline-success/25 focus-visible:outline-3 disabled:bg-transparent aria-disabled:bg-transparent dark:disabled:bg-transparent dark:aria-disabled:bg-transparent'
        },
        {
          color: 'info',
          variant: 'ghost',
          class: 'text-info hover:bg-info/10 active:bg-info/10 outline-info/25 focus-visible:outline-3 disabled:bg-transparent aria-disabled:bg-transparent dark:disabled:bg-transparent dark:aria-disabled:bg-transparent'
        },
        {
          color: 'warning',
          variant: 'ghost',
          class: 'text-warning hover:bg-warning/10 active:bg-warning/10 outline-warning/25 focus-visible:outline-3 disabled:bg-transparent aria-disabled:bg-transparent dark:disabled:bg-transparent dark:aria-disabled:bg-transparent'
        },
        {
          color: 'error',
          variant: 'ghost',
          class: 'text-error hover:bg-error/10 active:bg-error/10 outline-error/25 focus-visible:outline-3 disabled:bg-transparent aria-disabled:bg-transparent dark:disabled:bg-transparent dark:aria-disabled:bg-transparent'
        },
        {
          color: 'primary',
          variant: 'link',
          class: 'text-primary hover:text-primary/75 active:text-primary/75 disabled:text-primary aria-disabled:text-primary outline-primary/25 focus-visible:outline-3'
        },
        {
          color: 'secondary',
          variant: 'link',
          class: 'text-secondary hover:text-secondary/75 active:text-secondary/75 disabled:text-secondary aria-disabled:text-secondary outline-secondary/25 focus-visible:outline-3'
        },
        {
          color: 'accent',
          variant: 'link',
          class: 'text-accent hover:text-accent/75 active:text-accent/75 disabled:text-accent aria-disabled:text-accent outline-accent/25 focus-visible:outline-3'
        },
        {
          color: 'success',
          variant: 'link',
          class: 'text-success hover:text-success/75 active:text-success/75 disabled:text-success aria-disabled:text-success outline-success/25 focus-visible:outline-3'
        },
        {
          color: 'info',
          variant: 'link',
          class: 'text-info hover:text-info/75 active:text-info/75 disabled:text-info aria-disabled:text-info outline-info/25 focus-visible:outline-3'
        },
        {
          color: 'warning',
          variant: 'link',
          class: 'text-warning hover:text-warning/75 active:text-warning/75 disabled:text-warning aria-disabled:text-warning outline-warning/25 focus-visible:outline-3'
        },
        {
          color: 'error',
          variant: 'link',
          class: 'text-error hover:text-error/75 active:text-error/75 disabled:text-error aria-disabled:text-error outline-error/25 focus-visible:outline-3'
        },
        {
          color: 'neutral',
          variant: 'solid',
          class: 'text-inverted bg-inverted hover:bg-inverted/90 active:bg-inverted/90 disabled:bg-inverted aria-disabled:bg-inverted outline-inverted/25 focus-visible:outline-3'
        },
        {
          color: 'neutral',
          variant: 'outline',
          class: 'ring ring-inset ring-accented text-default bg-default hover:bg-elevated active:bg-elevated disabled:bg-default aria-disabled:bg-default outline-inverted/25 focus-visible:outline-3 focus-visible:ring-inverted'
        },
        {
          color: 'neutral',
          variant: 'soft',
          class: 'text-default bg-elevated hover:bg-accented/75 active:bg-accented/75 outline-inverted/25 focus-visible:outline-3 disabled:bg-elevated aria-disabled:bg-elevated'
        },
        {
          color: 'neutral',
          variant: 'subtle',
          class: 'ring ring-inset ring-accented text-default bg-elevated hover:bg-accented/75 active:bg-accented/75 disabled:bg-elevated aria-disabled:bg-elevated outline-inverted/25 focus-visible:outline-3 focus-visible:ring-inverted'
        },
        {
          color: 'neutral',
          variant: 'ghost',
          class: 'text-default hover:bg-elevated active:bg-elevated outline-inverted/25 focus-visible:outline-3 hover:disabled:bg-transparent dark:hover:disabled:bg-transparent hover:aria-disabled:bg-transparent dark:hover:aria-disabled:bg-transparent'
        },
        {
          color: 'neutral',
          variant: 'link',
          class: 'text-muted hover:text-default active:text-default disabled:text-muted aria-disabled:text-muted outline-inverted/25 focus-visible:outline-3'
        },
        {
          size: 'xs',
          square: true,
          class: 'p-1'
        },
        {
          size: 'sm',
          square: true,
          class: 'p-1.5'
        },
        {
          size: 'md',
          square: true,
          class: 'p-1.5'
        },
        {
          size: 'lg',
          square: true,
          class: 'p-2'
        },
        {
          size: 'xl',
          square: true,
          class: 'p-2'
        },
        {
          loading: true,
          leading: true,
          class: {
            leadingIcon: 'animate-spin'
          }
        },
        {
          loading: true,
          leading: false,
          trailing: true,
          class: {
            trailingIcon: 'animate-spin'
          }
        }
      ],
      defaultVariants: {
        color: 'primary',
        variant: 'solid',
        size: 'md'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/Button.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/button.ts).


# Calendar

## Uso

Use a diretiva `v-model` para controlar a data selecionada.

```vue
<script setup lang="ts">
import { CalendarDate } from '@internationalized/date'

const value = shallowRef(new CalendarDate(2022, 2, 3))
</script>

<template>
  <UCalendar v-model="value" />
</template>
```

Use a prop `default-value` para definir o valor inicial quando você não precisa controlar o estado.

```vue
<script setup lang="ts">
import { CalendarDate } from '@internationalized/date'

const defaultValue = shallowRef(new CalendarDate(2022, 2, 6))
</script>

<template>
  <UCalendar :default-value="defaultValue" />
</template>
```

**Nuxt:**

> \[!NOTE]
> See: /docs/getting-started/integrations/i18n/nuxt#locale
>
> Este componente usa o pacote `@internationalized/date` para formatação sensível ao locale. O formato da data é determinado pela prop `locale` do componente App.

**Vue:**

> \[!NOTE]
> See: /docs/getting-started/integrations/i18n/vue#locale
>
> Este componente usa o pacote `@internationalized/date` para formatação sensível ao locale. O formato da data é determinado pela prop `locale` do componente App.

### Tipo `4.9+`

Use a prop `type` para alterar o que o calendário seleciona. O padrão é `date`.

Ao usar `date`, clique no título para alternar da visualização de dia para a de mês e depois de ano, para uma navegação rápida, e então retorne para escolher uma data.

```vue
<script setup lang="ts">
import { CalendarDate } from '@internationalized/date'

const value = shallowRef(new CalendarDate(2022, 2, 1))
</script>

<template>
  <UCalendar type="month" v-model="value" />
</template>
```

Use `type="year"` para renderizar um seletor de ano independente.

```vue
<script setup lang="ts">
import { CalendarDate } from '@internationalized/date'

const value = shallowRef(new CalendarDate(2022, 1, 1))
</script>

<template>
  <UCalendar type="year" v-model="value" />
</template>
```

### Múltiplo

Use a prop `multiple` para permitir múltiplas seleções.

```vue
<script setup lang="ts">
import { CalendarDate } from '@internationalized/date'

const value = shallowRef([new CalendarDate(2022, 2, 4), new CalendarDate(2022, 2, 6), new CalendarDate(2022, 2, 8)])
</script>

<template>
  <UCalendar multiple v-model="value" />
</template>
```

### Intervalo

Use a prop `range` para selecionar um intervalo de datas.

```vue
<script setup lang="ts">
import { CalendarDate } from '@internationalized/date'

const value = shallowRef({ start: new CalendarDate(2022, 2, 3), end: new CalendarDate(2022, 2, 20) })
</script>

<template>
  <UCalendar range v-model="value" />
</template>
```

A prop `range` também funciona com `type="month"` e `type="year"`, permitindo selecionar um intervalo de meses ou anos.

```vue
<script setup lang="ts">
import { CalendarDate } from '@internationalized/date'

const value = shallowRef({ start: new CalendarDate(2022, 2, 1), end: new CalendarDate(2022, 6, 1) })
</script>

<template>
  <UCalendar type="month" range v-model="value" />
</template>
```

### Número de meses

Use a prop `numberOfMonths` para alterar o número de meses no calendário.

```vue
<template>
  <UCalendar :number-of-months="3" />
</template>
```

### Controles de mês

Use a prop `month-controls` para exibir os controles de mês. O padrão é `true`.

```vue
<template>
  <UCalendar :month-controls="false" />
</template>
```

Use as props `prev-month` e `next-month` para sobrescrever os botões de mês.

```vue
<template>
  <UCalendar :prev-month="{
  color: 'primary',
  variant: 'soft'
}" :next-month="{
  color: 'primary',
  variant: 'soft'
}" />
</template>
```

### Controles de ano

Use a prop `year-controls` para exibir os controles de ano. O padrão é `true`.

```vue
<template>
  <UCalendar :year-controls="false" />
</template>
```

Use as props `prev-year` e `next-year` para sobrescrever os botões de ano.

```vue
<template>
  <UCalendar :prev-year="{
  color: 'primary',
  variant: 'soft'
}" :next-year="{
  color: 'primary',
  variant: 'soft'
}" />
</template>
```

### Controle de visualização `4.9+`

Use a prop `view-control` para tornar o título um botão que alterna entre as visualizações de dia, mês e ano. O padrão é `true`.

```vue
<template>
  <UCalendar :view-control="false" />
</template>
```

Defina a prop `view-control` como um objeto para sobrescrever o botão do título.

```vue
<template>
  <UCalendar :view-control="{
  color: 'primary',
  variant: 'soft'
}" />
</template>
```

### Semanas fixas

Use a prop `fixed-weeks` para exibir o calendário com semanas fixas.

```vue
<template>
  <UCalendar :fixed-weeks="false" />
</template>
```

### Números das semanas `4.4+`

Use a prop `week-numbers` para exibir os números das semanas no calendário.

```vue
<template>
  <UCalendar week-numbers fixed-weeks />
</template>
```

### Cor

Use a prop `color` para alterar a cor do calendário.

```vue
<template>
  <UCalendar color="neutral" />
</template>
```

### Variante

Use a prop `variant` para alterar a variante do calendário.

```vue
<template>
  <UCalendar variant="subtle" />
</template>
```

### Tamanho

Use a prop `size` para alterar o tamanho do calendário.

```vue
<template>
  <UCalendar size="xl" />
</template>
```

### Desabilitado

Use a prop `disabled` para desabilitar o calendário.

```vue
<template>
  <UCalendar disabled />
</template>
```

## Exemplos

### Com eventos de chip

Use o componente [Chip](https://ui.nitro.news/docs/components/chip) para adicionar eventos a dias específicos.

:component-example{name="calendar-events-example"}

### Com datas desabilitadas

Use a prop `is-date-disabled` com uma função para marcar datas específicas como desabilitadas. Ao usar `type="month"` ou `type="year"`, use a prop `is-month-disabled` ou `is-year-disabled`.

:component-example{name="calendar-disabled-dates-example"}

### Com datas indisponíveis

Use a prop `is-date-unavailable` com uma função para marcar datas específicas como indisponíveis. Ao usar `type="month"` ou `type="year"`, use a prop `is-month-unavailable` ou `is-year-unavailable`.

:component-example{name="calendar-unavailable-dates-example"}

### Com datas mín/máx

Use as props `min-value` e `max-value` para limitar as datas.

:component-example{name="calendar-min-max-dates-example"}

### Com outros sistemas de calendário

Você pode usar outros calendários do `@internationalized/date` para implementar um sistema de calendário diferente.

:component-example{name="calendar-other-system-example"}

> \[!NOTE]
> See: https\://react-spectrum.adobe.com/internationalized/date/Calendar.html#implementations
>
> Você pode conferir todos os calendários disponíveis na documentação do `@internationalized/date`.

### Com controles externos

Você pode controlar o calendário com controles externos manipulando a data passada no `v-model`.

:component-example{name="calendar-external-controls-example"}

### Com a data de hoje

Use a função `today` do `@internationalized/date` com `getLocalTimeZone` para definir o valor como a data atual.

:component-example{name="calendar-today-example"}

### Como seletor de data

Use a [Button](https://ui.nitro.news/docs/components/button) and a [Popover](https://ui.nitro.news/docs/components/popover) component to create a date picker.

:component-example{name="calendar-date-picker-example"}

### Como seletor de intervalo de datas

Use a [Button](https://ui.nitro.news/docs/components/button) and a [Popover](https://ui.nitro.news/docs/components/popover) component to create a date range picker with preset ranges.

:component-example{name="calendar-date-range-picker-example"}

## API

### Props

```ts
/**
 * Props for the Calendar component
 */
interface CalendarProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  /**
   * The type of picker.
   * - `date` renders a day calendar whose heading can switch to a month then year view.
   * - `month` renders a standalone month picker.
   * - `year` renders a standalone year picker.
   * @default "\"date\""
   */
  type?: CalendarType | undefined;
  /**
   * The icon to use for the next year control.
   */
  nextYearIcon?: any;
  /**
   * Configure the next year button.
   * `{ color: 'neutral', variant: 'ghost' }`{lang="ts-type"}
   */
  nextYear?: Omit<ButtonProps, LinkPropsKeys> | undefined;
  /**
   * The icon to use for the next month control.
   */
  nextMonthIcon?: any;
  /**
   * Configure the next month button.
   * `{ color: 'neutral', variant: 'ghost' }`{lang="ts-type"}
   */
  nextMonth?: Omit<ButtonProps, LinkPropsKeys> | undefined;
  /**
   * The icon to use for the previous year control.
   */
  prevYearIcon?: any;
  /**
   * Configure the prev year button.
   * `{ color: 'neutral', variant: 'ghost' }`{lang="ts-type"}
   */
  prevYear?: Omit<ButtonProps, LinkPropsKeys> | undefined;
  /**
   * The icon to use for the previous month control.
   */
  prevMonthIcon?: any;
  /**
   * Configure the prev month button.
   * `{ color: 'neutral', variant: 'ghost' }`{lang="ts-type"}
   */
  prevMonth?: Omit<ButtonProps, LinkPropsKeys> | undefined;
  /**
   * Whether to make the heading a button that switches between the day, month and year views.
   * Has no effect when `type` is `year`. Can be an object to override the button props.
   * `{ color: 'neutral', variant: 'ghost', block: true }`{lang="ts-type"}
   * @default "true"
   */
  viewControl?: boolean | Omit<ButtonProps, LinkPropsKeys> | undefined;
  color?: "primary" | "secondary" | "accent" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
  variant?: "solid" | "outline" | "soft" | "subtle" | undefined;
  size?: "xs" | "sm" | "md" | "lg" | "xl" | undefined;
  /**
   * Whether or not a range of dates can be selected
   */
  range?: R | undefined;
  /**
   * Whether or not multiple dates can be selected
   */
  multiple?: M | undefined;
  /**
   * Show month controls
   * @default "true"
   */
  monthControls?: boolean | undefined;
  /**
   * Show year controls
   * @default "true"
   */
  yearControls?: boolean | undefined;
  defaultValue?: CalendarDate | CalendarDateTime | ZonedDateTime | DateRange | DateValue[];
  modelValue?: null | CalendarDate | CalendarDateTime | ZonedDateTime | DateRange | DateValue[];
  weekNumbers?: boolean | undefined;
  ui?: { root?: SlotClass; header?: SlotClass; body?: SlotClass; heading?: SlotClass; headingLabel?: SlotClass; grid?: SlotClass; gridRow?: SlotClass; gridWeekDaysRow?: SlotClass; gridBody?: SlotClass; headCell?: SlotClass; headCellWeek?: SlotClass; cell?: SlotClass; cellTrigger?: SlotClass; cellWeek?: SlotClass; } | undefined;
  defaultPlaceholder?: CalendarDate | CalendarDateTime | ZonedDateTime;
  placeholder?: CalendarDate | CalendarDateTime | ZonedDateTime;
  /**
   * When combined with `isDateUnavailable`, determines whether non-contiguous ranges, i.e. ranges containing unavailable dates, may be selected.
   */
  allowNonContiguousRanges?: boolean | undefined;
  /**
   * This property causes the previous and next buttons to navigate by the number of months displayed at once, rather than one month
   */
  pagedNavigation?: boolean | undefined;
  /**
   * Whether or not to prevent the user from deselecting a date without selecting another date first
   */
  preventDeselect?: boolean | undefined;
  /**
   * The maximum number of days that can be selected in a range
   */
  maximumDays?: number | undefined;
  /**
   * The day of the week to start the calendar on
   */
  weekStartsOn?: WeekStartsOn | undefined;
  /**
   * The format to use for the weekday strings provided via the weekdays slot prop
   */
  weekdayFormat?: WeekDayFormat | undefined;
  /**
   * Whether or not to always display 6 weeks in the calendar
   * @default "true"
   */
  fixedWeeks?: boolean | undefined;
  maxValue?: CalendarDate | CalendarDateTime | ZonedDateTime;
  minValue?: CalendarDate | CalendarDateTime | ZonedDateTime;
  /**
   * The locale to use for formatting dates
   */
  locale?: string | undefined;
  /**
   * The number of months to display at once
   */
  numberOfMonths?: number | undefined;
  /**
   * Whether or not the calendar is disabled
   */
  disabled?: boolean | undefined;
  /**
   * Whether or not the calendar is readonly
   */
  readonly?: boolean | undefined;
  /**
   * If true, the calendar will focus the selected day, today, or the first day of the month depending on what is visible when the calendar is mounted
   */
  initialFocus?: boolean | undefined;
  /**
   * A function that returns whether or not a date is disabled
   */
  isDateDisabled?: Matcher | undefined;
  /**
   * A function that returns whether or not a date is unavailable
   */
  isDateUnavailable?: Matcher | undefined;
  /**
   * A function that returns whether or not a date is hightable
   */
  isDateHighlightable?: Matcher | undefined;
  /**
   * A function that returns the next page of the calendar. It receives the current placeholder as an argument inside the component.
   */
  nextPage?: ((placeholder: DateValue) => DateValue) | undefined;
  /**
   * A function that returns the previous page of the calendar. It receives the current placeholder as an argument inside the component.
   */
  prevPage?: ((placeholder: DateValue) => DateValue) | undefined;
  /**
   * Whether or not to disable days outside the current view.
   */
  disableDaysOutsideCurrentView?: boolean | undefined;
  /**
   * Which part of the range should be fixed
   */
  fixedDate?: "start" | "end" | undefined;
  /**
   * A function that returns whether or not a month is disabled
   */
  isMonthDisabled?: Matcher | undefined;
  /**
   * A function that returns whether or not a month is unavailable
   */
  isMonthUnavailable?: Matcher | undefined;
  /**
   * A function that returns whether or not a year is disabled
   */
  isYearDisabled?: Matcher | undefined;
  /**
   * A function that returns whether or not a year is unavailable
   */
  isYearUnavailable?: Matcher | undefined;
}
```

### Slots

```ts
/**
 * Slots for the Calendar component
 */
interface CalendarSlots {
  heading(): any;
  day(): any;
  week-day(): any;
  month-cell(): any;
  year-cell(): any;
}
```

### Emits

```ts
/**
 * Emitted events for the Calendar component
 */
interface CalendarEmits {
  update:modelValue: (payload: [value: CalendarModelValue<R, M>]) => void;
  update:placeholder: (payload: [date: DateValue]) => void;
  update:validModelValue: (payload: [date: DateRange]) => void;
  update:startValue: (payload: [date: DateValue | undefined]) => void;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    calendar: {
      slots: {
        root: '',
        header: 'flex items-center justify-between',
        body: 'flex flex-col space-y-4 pt-4 sm:flex-row sm:space-x-4 sm:space-y-0',
        heading: 'flex-1 min-w-0 text-center',
        headingLabel: 'font-medium block truncate p-1.5',
        grid: 'w-full border-collapse select-none space-y-1 focus:outline-none',
        gridRow: 'grid',
        gridWeekDaysRow: 'mb-1 grid w-full grid-cols-7',
        gridBody: 'grid',
        headCell: 'rounded-md',
        headCellWeek: 'rounded-md text-muted',
        cell: 'relative text-center',
        cellTrigger: [
          'm-0.5 relative flex items-center justify-center whitespace-nowrap focus-visible:outline-3 data-disabled:text-muted data-unavailable:line-through data-unavailable:text-muted data-unavailable:pointer-events-none data-today:font-semibold',
          'transition'
        ],
        cellWeek: 'relative text-center text-muted'
      },
      variants: {
        color: {
          primary: {
            headCell: 'text-primary',
            cellTrigger: 'outline-primary/25'
          },
          secondary: {
            headCell: 'text-secondary',
            cellTrigger: 'outline-secondary/25'
          },
          accent: {
            headCell: 'text-accent',
            cellTrigger: 'outline-accent/25'
          },
          success: {
            headCell: 'text-success',
            cellTrigger: 'outline-success/25'
          },
          info: {
            headCell: 'text-info',
            cellTrigger: 'outline-info/25'
          },
          warning: {
            headCell: 'text-warning',
            cellTrigger: 'outline-warning/25'
          },
          error: {
            headCell: 'text-error',
            cellTrigger: 'outline-error/25'
          },
          neutral: {
            headCell: 'text-highlighted',
            cellTrigger: 'outline-inverted/25'
          }
        },
        variant: {
          solid: '',
          outline: '',
          soft: '',
          subtle: ''
        },
        size: {
          xs: {
            headingLabel: 'text-xs',
            cell: 'text-xs',
            cellWeek: 'text-xs',
            headCell: 'text-[10px]',
            headCellWeek: 'text-[10px]',
            body: 'space-y-2 pt-2'
          },
          sm: {
            headingLabel: 'text-xs',
            headCell: 'text-xs',
            headCellWeek: 'text-xs',
            cellWeek: 'text-xs',
            cell: 'text-xs'
          },
          md: {
            headingLabel: 'text-sm',
            headCell: 'text-xs',
            headCellWeek: 'text-xs',
            cellWeek: 'text-xs',
            cell: 'text-sm'
          },
          lg: {
            headingLabel: 'text-md',
            headCell: 'text-md',
            headCellWeek: 'text-md'
          },
          xl: {
            headingLabel: 'text-lg',
            headCell: 'text-lg',
            headCellWeek: 'text-lg'
          }
        },
        view: {
          day: {
            gridRow: 'grid-cols-7 place-items-center',
            cellTrigger: 'rounded-full data-outside-view:text-muted'
          },
          month: {
            gridRow: 'grid-cols-4',
            cellTrigger: 'rounded-md'
          },
          year: {
            gridRow: 'grid-cols-4',
            cellTrigger: 'rounded-md'
          }
        },
        weekNumbers: {
          true: ''
        }
      },
      compoundVariants: [
        {
          color: 'primary',
          variant: 'solid',
          class: {
            cellTrigger: 'data-selected:bg-primary data-selected:text-inverted data-today:not-data-selected:text-primary data-highlighted:bg-primary/20 hover:not-data-selected:bg-primary/20'
          }
        },
        {
          color: 'secondary',
          variant: 'solid',
          class: {
            cellTrigger: 'data-selected:bg-secondary data-selected:text-inverted data-today:not-data-selected:text-secondary data-highlighted:bg-secondary/20 hover:not-data-selected:bg-secondary/20'
          }
        },
        {
          color: 'accent',
          variant: 'solid',
          class: {
            cellTrigger: 'data-selected:bg-accent data-selected:text-inverted data-today:not-data-selected:text-accent data-highlighted:bg-accent/20 hover:not-data-selected:bg-accent/20'
          }
        },
        {
          color: 'success',
          variant: 'solid',
          class: {
            cellTrigger: 'data-selected:bg-success data-selected:text-inverted data-today:not-data-selected:text-success data-highlighted:bg-success/20 hover:not-data-selected:bg-success/20'
          }
        },
        {
          color: 'info',
          variant: 'solid',
          class: {
            cellTrigger: 'data-selected:bg-info data-selected:text-inverted data-today:not-data-selected:text-info data-highlighted:bg-info/20 hover:not-data-selected:bg-info/20'
          }
        },
        {
          color: 'warning',
          variant: 'solid',
          class: {
            cellTrigger: 'data-selected:bg-warning data-selected:text-inverted data-today:not-data-selected:text-warning data-highlighted:bg-warning/20 hover:not-data-selected:bg-warning/20'
          }
        },
        {
          color: 'error',
          variant: 'solid',
          class: {
            cellTrigger: 'data-selected:bg-error data-selected:text-inverted data-today:not-data-selected:text-error data-highlighted:bg-error/20 hover:not-data-selected:bg-error/20'
          }
        },
        {
          color: 'primary',
          variant: 'outline',
          class: {
            cellTrigger: 'data-selected:ring data-selected:ring-inset data-selected:ring-primary/50 data-selected:text-primary data-selected:focus-visible:ring-primary data-today:not-data-selected:text-primary data-highlighted:bg-primary/10 hover:not-data-selected:bg-primary/10'
          }
        },
        {
          color: 'secondary',
          variant: 'outline',
          class: {
            cellTrigger: 'data-selected:ring data-selected:ring-inset data-selected:ring-secondary/50 data-selected:text-secondary data-selected:focus-visible:ring-secondary data-today:not-data-selected:text-secondary data-highlighted:bg-secondary/10 hover:not-data-selected:bg-secondary/10'
          }
        },
        {
          color: 'accent',
          variant: 'outline',
          class: {
            cellTrigger: 'data-selected:ring data-selected:ring-inset data-selected:ring-accent/50 data-selected:text-accent data-selected:focus-visible:ring-accent data-today:not-data-selected:text-accent data-highlighted:bg-accent/10 hover:not-data-selected:bg-accent/10'
          }
        },
        {
          color: 'success',
          variant: 'outline',
          class: {
            cellTrigger: 'data-selected:ring data-selected:ring-inset data-selected:ring-success/50 data-selected:text-success data-selected:focus-visible:ring-success data-today:not-data-selected:text-success data-highlighted:bg-success/10 hover:not-data-selected:bg-success/10'
          }
        },
        {
          color: 'info',
          variant: 'outline',
          class: {
            cellTrigger: 'data-selected:ring data-selected:ring-inset data-selected:ring-info/50 data-selected:text-info data-selected:focus-visible:ring-info data-today:not-data-selected:text-info data-highlighted:bg-info/10 hover:not-data-selected:bg-info/10'
          }
        },
        {
          color: 'warning',
          variant: 'outline',
          class: {
            cellTrigger: 'data-selected:ring data-selected:ring-inset data-selected:ring-warning/50 data-selected:text-warning data-selected:focus-visible:ring-warning data-today:not-data-selected:text-warning data-highlighted:bg-warning/10 hover:not-data-selected:bg-warning/10'
          }
        },
        {
          color: 'error',
          variant: 'outline',
          class: {
            cellTrigger: 'data-selected:ring data-selected:ring-inset data-selected:ring-error/50 data-selected:text-error data-selected:focus-visible:ring-error data-today:not-data-selected:text-error data-highlighted:bg-error/10 hover:not-data-selected:bg-error/10'
          }
        },
        {
          color: 'primary',
          variant: 'soft',
          class: {
            cellTrigger: 'data-selected:bg-primary/10 data-selected:text-primary data-today:not-data-selected:text-primary data-highlighted:bg-primary/20 hover:not-data-selected:bg-primary/20'
          }
        },
        {
          color: 'secondary',
          variant: 'soft',
          class: {
            cellTrigger: 'data-selected:bg-secondary/10 data-selected:text-secondary data-today:not-data-selected:text-secondary data-highlighted:bg-secondary/20 hover:not-data-selected:bg-secondary/20'
          }
        },
        {
          color: 'accent',
          variant: 'soft',
          class: {
            cellTrigger: 'data-selected:bg-accent/10 data-selected:text-accent data-today:not-data-selected:text-accent data-highlighted:bg-accent/20 hover:not-data-selected:bg-accent/20'
          }
        },
        {
          color: 'success',
          variant: 'soft',
          class: {
            cellTrigger: 'data-selected:bg-success/10 data-selected:text-success data-today:not-data-selected:text-success data-highlighted:bg-success/20 hover:not-data-selected:bg-success/20'
          }
        },
        {
          color: 'info',
          variant: 'soft',
          class: {
            cellTrigger: 'data-selected:bg-info/10 data-selected:text-info data-today:not-data-selected:text-info data-highlighted:bg-info/20 hover:not-data-selected:bg-info/20'
          }
        },
        {
          color: 'warning',
          variant: 'soft',
          class: {
            cellTrigger: 'data-selected:bg-warning/10 data-selected:text-warning data-today:not-data-selected:text-warning data-highlighted:bg-warning/20 hover:not-data-selected:bg-warning/20'
          }
        },
        {
          color: 'error',
          variant: 'soft',
          class: {
            cellTrigger: 'data-selected:bg-error/10 data-selected:text-error data-today:not-data-selected:text-error data-highlighted:bg-error/20 hover:not-data-selected:bg-error/20'
          }
        },
        {
          color: 'primary',
          variant: 'subtle',
          class: {
            cellTrigger: 'data-selected:bg-primary/10 data-selected:text-primary data-selected:ring data-selected:ring-inset data-selected:ring-primary/25 data-selected:focus-visible:ring-primary data-today:not-data-selected:text-primary data-highlighted:bg-primary/20 hover:not-data-selected:bg-primary/20'
          }
        },
        {
          color: 'secondary',
          variant: 'subtle',
          class: {
            cellTrigger: 'data-selected:bg-secondary/10 data-selected:text-secondary data-selected:ring data-selected:ring-inset data-selected:ring-secondary/25 data-selected:focus-visible:ring-secondary data-today:not-data-selected:text-secondary data-highlighted:bg-secondary/20 hover:not-data-selected:bg-secondary/20'
          }
        },
        {
          color: 'accent',
          variant: 'subtle',
          class: {
            cellTrigger: 'data-selected:bg-accent/10 data-selected:text-accent data-selected:ring data-selected:ring-inset data-selected:ring-accent/25 data-selected:focus-visible:ring-accent data-today:not-data-selected:text-accent data-highlighted:bg-accent/20 hover:not-data-selected:bg-accent/20'
          }
        },
        {
          color: 'success',
          variant: 'subtle',
          class: {
            cellTrigger: 'data-selected:bg-success/10 data-selected:text-success data-selected:ring data-selected:ring-inset data-selected:ring-success/25 data-selected:focus-visible:ring-success data-today:not-data-selected:text-success data-highlighted:bg-success/20 hover:not-data-selected:bg-success/20'
          }
        },
        {
          color: 'info',
          variant: 'subtle',
          class: {
            cellTrigger: 'data-selected:bg-info/10 data-selected:text-info data-selected:ring data-selected:ring-inset data-selected:ring-info/25 data-selected:focus-visible:ring-info data-today:not-data-selected:text-info data-highlighted:bg-info/20 hover:not-data-selected:bg-info/20'
          }
        },
        {
          color: 'warning',
          variant: 'subtle',
          class: {
            cellTrigger: 'data-selected:bg-warning/10 data-selected:text-warning data-selected:ring data-selected:ring-inset data-selected:ring-warning/25 data-selected:focus-visible:ring-warning data-today:not-data-selected:text-warning data-highlighted:bg-warning/20 hover:not-data-selected:bg-warning/20'
          }
        },
        {
          color: 'error',
          variant: 'subtle',
          class: {
            cellTrigger: 'data-selected:bg-error/10 data-selected:text-error data-selected:ring data-selected:ring-inset data-selected:ring-error/25 data-selected:focus-visible:ring-error data-today:not-data-selected:text-error data-highlighted:bg-error/20 hover:not-data-selected:bg-error/20'
          }
        },
        {
          color: 'neutral',
          variant: 'solid',
          class: {
            cellTrigger: 'data-selected:bg-inverted data-selected:text-inverted data-today:not-data-selected:text-highlighted data-highlighted:bg-inverted/20 hover:not-data-selected:bg-inverted/10'
          }
        },
        {
          color: 'neutral',
          variant: 'outline',
          class: {
            cellTrigger: 'data-selected:ring data-selected:ring-inset data-selected:ring-accented data-selected:text-default data-selected:bg-default data-selected:focus-visible:ring-inverted data-today:not-data-selected:text-highlighted data-highlighted:bg-inverted/10 hover:not-data-selected:bg-inverted/10'
          }
        },
        {
          color: 'neutral',
          variant: 'soft',
          class: {
            cellTrigger: 'data-selected:bg-elevated data-selected:text-default data-today:not-data-selected:text-highlighted data-highlighted:bg-inverted/20 hover:not-data-selected:bg-inverted/10'
          }
        },
        {
          color: 'neutral',
          variant: 'subtle',
          class: {
            cellTrigger: 'data-selected:bg-elevated data-selected:text-default data-selected:ring data-selected:ring-inset data-selected:ring-accented data-selected:focus-visible:ring-inverted data-today:not-data-selected:text-highlighted data-highlighted:bg-inverted/20 hover:not-data-selected:bg-inverted/10'
          }
        },
        {
          size: 'xs',
          view: 'day',
          class: {
            cellTrigger: 'size-7'
          }
        },
        {
          size: 'sm',
          view: 'day',
          class: {
            cellTrigger: 'size-7'
          }
        },
        {
          size: 'md',
          view: 'day',
          class: {
            cellTrigger: 'size-8'
          }
        },
        {
          size: 'lg',
          view: 'day',
          class: {
            cellTrigger: 'size-9 text-md'
          }
        },
        {
          size: 'xl',
          view: 'day',
          class: {
            cellTrigger: 'size-10 text-lg'
          }
        },
        {
          size: 'xs',
          view: [
            'month',
            'year'
          ],
          class: {
            cellTrigger: 'h-7 px-2'
          }
        },
        {
          size: 'sm',
          view: [
            'month',
            'year'
          ],
          class: {
            cellTrigger: 'h-7 px-2'
          }
        },
        {
          size: 'md',
          view: [
            'month',
            'year'
          ],
          class: {
            cellTrigger: 'h-8 px-3'
          }
        },
        {
          size: 'lg',
          view: [
            'month',
            'year'
          ],
          class: {
            cellTrigger: 'h-9 px-4 text-md'
          }
        },
        {
          size: 'xl',
          view: [
            'month',
            'year'
          ],
          class: {
            cellTrigger: 'h-10 px-5 text-lg'
          }
        },
        {
          view: 'day',
          weekNumbers: true,
          class: {
            gridRow: 'grid-cols-8',
            gridWeekDaysRow: 'grid-cols-8 [&>*:first-child]:col-start-2'
          }
        }
      ],
      defaultVariants: {
        size: 'md',
        color: 'accent',
        variant: 'solid',
        view: 'day'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/Calendar.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/calendar.ts).


# Card

## Uso

Use os slots `header`, `default` e `footer` para adicionar conteúdo ao Card.

```vue
<template>
  <UCard>
    <Placeholder class="h-32" />
  
    <template #header>
      <Placeholder class="h-8" />
    </template>
    <template #footer>
      <Placeholder class="h-8" />
    </template></UCard>
</template>
```

### Título `4.7+`

Use a prop `title` para definir o título do cabeçalho do Card.

```vue
<template>
  <UCard title="Card with title" class="w-full">
    <Placeholder class="h-32" />
  </UCard>
</template>
```

### Descrição `4.7+`

Use a prop `description` para definir a descrição do cabeçalho do Card.

```vue
<template>
  <UCard title="Card with description" description="Lorem ipsum dolor sit amet, consectetur adipiscing elit." class="w-full">
    <Placeholder class="h-32" />
  </UCard>
</template>
```

### Variante

Use a prop `variant` para alterar a variante do Card.

```vue
<template>
  <UCard variant="subtle">
    <Placeholder class="h-32" />
  
    <template #header>
      <Placeholder class="h-8" />
    </template>
    <template #footer>
      <Placeholder class="h-8" />
    </template></UCard>
</template>
```

## API

### Props

```ts
/**
 * Props for the Card component
 */
interface CardProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  title?: string | undefined;
  description?: string | undefined;
  variant?: "solid" | "outline" | "soft" | "subtle" | undefined;
  ui?: { root?: SlotClass; header?: SlotClass; title?: SlotClass; description?: SlotClass; body?: SlotClass; footer?: SlotClass; } | undefined;
}
```

### Slots

```ts
/**
 * Slots for the Card component
 */
interface CardSlots {
  header(): any;
  title(): any;
  description(): any;
  default(): any;
  footer(): any;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    card: {
      slots: {
        root: 'rounded-lg overflow-hidden',
        header: 'p-4 sm:px-6',
        title: 'text-highlighted font-semibold',
        description: 'mt-1 text-muted text-sm',
        body: 'p-4 sm:p-6',
        footer: 'p-4 sm:px-6'
      },
      variants: {
        variant: {
          solid: {
            root: 'bg-inverted text-inverted',
            title: 'text-inverted',
            description: 'text-dimmed'
          },
          outline: {
            root: 'bg-default ring ring-default divide-y divide-default'
          },
          soft: {
            root: 'bg-elevated/50 divide-y divide-default'
          },
          subtle: {
            root: 'bg-elevated/50 ring ring-default divide-y divide-default'
          }
        }
      },
      defaultVariants: {
        variant: 'outline'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/Card.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/card.ts).


# Carousel

## Uso

Use o componente Carousel para exibir uma lista de itens em um carrossel.

::component-example
---
collapse: true
overflowHidden: true
class: "!p-0"
name: carousel-example
---
::

> \[!NOTE]
>
> Use o mouse para arrastar o carrossel horizontalmente no desktop.

### Itens

Use a prop `items` como um array e renderize cada item usando o slot padrão:

:component-example{.p-8 name="carousel-items-example"}

Você também pode passar um array de objetos com as seguintes propriedades:

- `class?: any`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `ui?: { item?: ClassNameValue }`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Você pode controlar quantos itens ficam visíveis usando as classes utilitárias [`basis`](https://tailwindcss.com/docs/flex-basis){rel="&#x22;nofollow&#x22;"} / [`width`](https://tailwindcss.com/docs/width){rel="&#x22;nofollow&#x22;"} no `item`:

:component-example{.p-8.px-16 name="carousel-items-multiple-example"}

### Orientação

Use a prop `orientation` para alterar a orientação do Progress. O padrão é `horizontal`.

> \[!NOTE]
>
> Use o mouse para arrastar o carrossel verticalmente no desktop.

:component-example{.p-8 name="carousel-orientation-example"}

> \[!CAUTION]
>
> Você precisa especificar um `height` no container na orientação vertical.

### Setas

Use a prop `arrows` para exibir os botões de anterior e próximo.

:component-example{.p-8 name="carousel-arrows-example"}

### Anterior / Próximo

Use as props `prev` e `next` para personalizar os botões de anterior e próximo com quaisquer props do [Button](https://ui.nitro.news/docs/components/button).

:component-example{.p-8 name="carousel-prev-next-example"}

### Ícones de anterior / próximo

Use as props `prev-icon` e `next-icon` para personalizar o [Icon](https://ui.nitro.news/docs/components/icon) dos botões. O padrão é `i-lucide-arrow-left` / `i-lucide-arrow-right`.

::component-example
---
options:
  - name: prevIcon
    label: prevIcon
    default: i-lucide-chevron-left
  - name: nextIcon
    label: nextIcon
    default: i-lucide-chevron-right
class: p-8
name: carousel-prev-next-icon-example
---
::

**Nuxt:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/nuxt#theme
>
> Você pode personalizar esses ícones globalmente no seu `app.config.ts` nas chaves `ui.icons.arrowLeft` / `ui.icons.arrowRight`.

**Vue:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/vue#theme
>
> Você pode personalizar esses ícones globalmente no seu `vite.config.ts` nas chaves `ui.icons.arrowLeft` / `ui.icons.arrowRight`.

### Pontos

Use a prop `dots` para exibir uma lista de pontos para rolar até um slide específico.

:component-example{.p-8.pb-12 name="carousel-dots-example"}

O número de pontos é baseado no número de slides exibidos na visualização:

:component-example{.p-8.px-16.pb-12 name="carousel-dots-multiple-example"}

## Plugins

O componente Carousel implementa os [plugins oficiais do Embla Carousel](https://www.embla-carousel.com/plugins/){rel="&#x22;nofollow&#x22;"}.

### Reprodução automática

Este plugin é usado para estender o Embla Carousel com a funcionalidade de **reprodução automática**.

Use a prop `autoplay` como um booleano ou um objeto para configurar o [plugin Autoplay](https://www.embla-carousel.com/plugins/autoplay/){rel="&#x22;nofollow&#x22;"}.

:component-example{.p-8.px-16.pb-12 name="carousel-autoplay-example"}

> \[!NOTE]
>
> Neste exemplo, usamos a prop `loop` para um carrossel infinito.

### Rolagem automática

Este plugin é usado para estender o Embla Carousel com a funcionalidade de **rolagem automática**.

Use a prop `auto-scroll` como um booleano ou um objeto para configurar o [plugin Auto Scroll](https://www.embla-carousel.com/plugins/auto-scroll/){rel="&#x22;nofollow&#x22;"}.

:component-example{.p-8.px-16.pb-12 name="carousel-auto-scroll-example"}

> \[!NOTE]
>
> Neste exemplo, usamos a prop `loop` para um carrossel infinito.

### Altura automática

Este plugin é usado para estender o Embla Carousel com a funcionalidade de **altura automática**. Ele altera a altura do container do carrossel para se ajustar à altura do slide mais alto em exibição.

Use a prop `auto-height` como um booleano ou um objeto para configurar o [plugin Auto Height](https://www.embla-carousel.com/plugins/auto-height/){rel="&#x22;nofollow&#x22;"}.

:component-example{.p-8.pt-16 name="carousel-auto-height-example"}

> \[!NOTE]
>
> Neste exemplo, adicionamos a classe `transition-[height]` no container para animar a mudança de altura.

### Nomes de classe

O Class Names é um plugin utilitário de **alternância de nomes de classe** para o Embla Carousel que permite automatizar a alternância de nomes de classe no seu carrossel.

Use a prop `class-names` como um booleano ou um objeto para configurar o [plugin Class Names](https://www.embla-carousel.com/plugins/class-names/){rel="&#x22;nofollow&#x22;"}.

:component-example{.p-8 name="carousel-class-names-example"}

> \[!NOTE]
>
> Neste exemplo, adicionamos as classes `transition-opacity [&:not(.is-snapped)]:opacity-10` no `item` para animar a mudança de opacidade.

### Fade

Este plugin é usado para substituir a funcionalidade de rolagem do Embla Carousel por **transições de fade**.

Use a prop `fade` como um booleano ou um objeto para configurar o [plugin Fade](https://www.embla-carousel.com/plugins/fade/){rel="&#x22;nofollow&#x22;"}.

:component-example{.p-8.pb-12 name="carousel-fade-example"}

### Gestos de roda do mouse

Este plugin é usado para estender o Embla Carousel com a capacidade de **usar a roda do mouse/trackpad** para navegar pelo carrossel.

Use a prop `wheel-gestures` como um booleano ou um objeto para configurar o [plugin Wheel Gestures](https://www.embla-carousel.com/plugins/wheel-gestures/){rel="&#x22;nofollow&#x22;"}.

> \[!NOTE]
>
> Use a roda do mouse para rolar o carrossel.

:component-example{.p-8.px-16 name="carousel-wheel-gestures-example"}

## Exemplos

### Com miniaturas

Você pode usar a função [scrollTo](https://www.embla-carousel.com/api/methods/#scrollto){rel="&#x22;nofollow&#x22;"} da [`emblaApi`](https://ui.nitro.news/#expose) para exibir miniaturas sob o carrossel que permitem navegar até um slide específico.

:component-example{.p-8.px-16 name="carousel-thumbnails-example"}

## API

### Props

```ts
/**
 * Props for the Carousel component
 */
interface CarouselProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  /**
   * Configure the prev button when arrows are enabled.
   */
  prev?: Omit<ButtonProps, LinkPropsKeys> | undefined;
  /**
   * The icon displayed in the prev button.
   */
  prevIcon?: any;
  /**
   * Configure the next button when arrows are enabled.
   */
  next?: Omit<ButtonProps, LinkPropsKeys> | undefined;
  /**
   * The icon displayed in the next button.
   */
  nextIcon?: any;
  /**
   * Display prev and next buttons to scroll the carousel.
   * @default "false"
   */
  arrows?: boolean | undefined;
  /**
   * Display dots to scroll to a specific slide.
   * @default "false"
   */
  dots?: boolean | undefined;
  /**
   * The orientation of the carousel.
   * @default "\"horizontal\""
   */
  orientation?: "vertical" | "horizontal" | undefined;
  items?: T[] | undefined;
  /**
   * Enable Autoplay plugin
   * @default "false"
   */
  autoplay?: boolean | Partial<CreateOptionsType<OptionsType>> | undefined;
  /**
   * Enable Auto Scroll plugin
   * @default "false"
   */
  autoScroll?: boolean | Partial<CreateOptionsType<OptionsType>> | undefined;
  /**
   * Enable Auto Height plugin
   * @default "false"
   */
  autoHeight?: boolean | Partial<CreateOptionsType<{ active: boolean; breakpoints: { [key: string]: Omit<Partial<any>, "breakpoints">; }; }>> | undefined;
  /**
   * Enable Class Names plugin
   * @default "false"
   */
  classNames?: boolean | Partial<CreateOptionsType<OptionsType>> | undefined;
  /**
   * Enable Fade plugin
   * @default "false"
   */
  fade?: boolean | Partial<CreateOptionsType<{ active: boolean; breakpoints: { [key: string]: Omit<Partial<any>, "breakpoints">; }; }>> | undefined;
  /**
   * Enable Wheel Gestures plugin
   * @default "false"
   */
  wheelGestures?: boolean | WheelGesturesPluginOptions | undefined;
  ui?: { root?: SlotClass; viewport?: SlotClass; container?: SlotClass; item?: SlotClass; controls?: SlotClass; arrows?: SlotClass; prev?: SlotClass; next?: SlotClass; dots?: SlotClass; dot?: SlotClass; } | undefined;
  /**
   * @default "\"center\""
   */
  align?: AlignmentOptionType | undefined;
  /**
   * @default "\"trimSnaps\""
   */
  containScroll?: ScrollContainOptionType | undefined;
  /**
   * @default "1"
   */
  slidesToScroll?: SlidesToScrollOptionType | undefined;
  /**
   * @default "false"
   */
  dragFree?: boolean | undefined;
  /**
   * @default "10"
   */
  dragThreshold?: number | undefined;
  /**
   * @default "0"
   */
  inViewThreshold?: number | number[] | undefined;
  /**
   * @default "false"
   */
  loop?: boolean | undefined;
  /**
   * @default "false"
   */
  skipSnaps?: boolean | undefined;
  /**
   * @default "25"
   */
  duration?: number | undefined;
  /**
   * @default "0"
   */
  startIndex?: number | undefined;
  /**
   * @default "true"
   */
  watchDrag?: DragHandlerOptionType | undefined;
  /**
   * @default "true"
   */
  watchResize?: ResizeHandlerOptionType | undefined;
  /**
   * @default "true"
   */
  watchSlides?: SlidesHandlerOptionType | undefined;
  /**
   * @default "true"
   */
  watchFocus?: FocusHandlerOptionType | undefined;
  /**
   * @default "true"
   */
  active?: boolean | undefined;
  /**
   * @default "{}"
   */
  breakpoints?: { [key: string]: Omit<Partial<CreateOptionsType<{ align: AlignmentOptionType; axis: AxisOptionType; container: string | HTMLElement | null; slides: string | HTMLElement[] | NodeListOf<HTMLElement> | null; containScroll: ScrollContainOptionType; direction: AxisDirectionOptionType; slidesToScroll: SlidesToScrollOptionType; dragFree: boolean; dragThreshold: number; inViewThreshold: number | number[] | undefined; loop: boolean; skipSnaps: boolean; duration: number; startIndex: number; watchDrag: DragHandlerOptionType; watchResize: ResizeHandlerOptionType; watchSlides: SlidesHandlerOptionType; watchFocus: FocusHandlerOptionType; }>>, "breakpoints">; } | undefined;
}
```

### Slots

```ts
/**
 * Slots for the Carousel component
 */
interface CarouselSlots {
  default(): any;
}
```

### Emits

```ts
/**
 * Emitted events for the Carousel component
 */
interface CarouselEmits {
  select: (payload: [selectedIndex: number]) => void;
}
```

### Expose

Você pode acessar a instância tipada do componente usando [`useTemplateRef`](https://vuejs.org/api/composition-api-helpers.html#usetemplateref){rel="&#x22;nofollow&#x22;"}.

```vue
<script setup lang="ts">
const carousel = useTemplateRef('carousel')
</script>

<template>
  <NCarousel ref="carousel" />
</template>
```

Isso dará a você acesso ao seguinte:

| Name                                                                                                                           | Type                                                                                                                                                                                                                                      |
| ------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `emblaRef`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | `Ref<HTMLElement | null>`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"}                                                                                             |
| `emblaApi`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | [`Ref<EmblaCarouselType | null>`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"}](https://www.embla-carousel.com/api/methods/#typescript){rel="&#x22;nofollow&#x22;"} |

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    carousel: {
      slots: {
        root: 'relative focus:outline-none',
        viewport: 'overflow-hidden',
        container: 'flex items-start',
        item: 'min-w-0 shrink-0 basis-full',
        controls: '',
        arrows: '',
        prev: 'absolute rounded-full',
        next: 'absolute rounded-full',
        dots: 'absolute inset-x-0 -bottom-7 flex flex-wrap items-center justify-center gap-3',
        dot: 'cursor-pointer size-3 bg-accented rounded-full transition'
      },
      variants: {
        orientation: {
          vertical: {
            container: 'flex-col -mt-4',
            item: 'pt-4',
            prev: 'top-4 sm:-top-12 left-1/2 -translate-x-1/2 rotate-90 rtl:-rotate-90',
            next: 'bottom-4 sm:-bottom-12 left-1/2 -translate-x-1/2 rotate-90 rtl:-rotate-90'
          },
          horizontal: {
            container: 'flex-row -ms-4',
            item: 'ps-4',
            prev: 'start-4 sm:-start-12 top-1/2 -translate-y-1/2',
            next: 'end-4 sm:-end-12 top-1/2 -translate-y-1/2'
          }
        },
        active: {
          true: {
            dot: 'data-[state=active]:bg-inverted'
          }
        }
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/Carousel.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/carousel.ts).


# ChangelogVersion

## Uso

O componente ChangelogVersion oferece uma maneira flexível de exibir um elemento `<article>` com conteúdo personalizável, incluindo título, descrição, imagem, etc.

```vue
<template>
  <n-changelog-version :authors=[{"name":"Benjamin Canac","description":"@benjamincanac","avatar":{"src":"https://github.com/benjamincanac.png","loading":"lazy"},"to":"https://x.com/benjamincanac","target":"_blank"},{"name":"Sebastien Chopin","description":"@atinux","avatar":{"src":"https://github.com/atinux.png","loading":"lazy"},"to":"https://x.com/atinux","target":"_blank"},{"name":"Hugo Richard","description":"@hugorcd__","avatar":{"src":"https://github.com/hugorcd.png","loading":"lazy"},"to":"https://x.com/hugorcd__","target":"_blank"}] :ui={"container":"max-w-lg"} date=2025-03-12 description=O Nitro UI v3 chegou! Após mais de 1500 commits, esse grande redesign traz acessibilidade aprimorada, suporte ao Tailwind CSS e compatibilidade total com Vue. image=https://nuxt.com/assets/blog/nuxt-ui-v3.png target=_blank title=Apresentando o Nitro UI v3 to=https://nuxt.com/blog/nuxt-ui-v3 />
</template>
```

> \[!TIP]
> See: /docs/components/changelog-versions
>
> Use o componente `ChangelogVersions` para exibir várias versões de changelog em uma linha do tempo, com uma barra indicadora à esquerda.

### Título

Use a prop `title` para exibir o título do ChangelogVersion.

```vue
<template>
  <UChangelogVersion title="Introducing Nitro UI v3" />
</template>
```

### Descrição

Use a prop `description` para exibir a descrição do ChangelogVersion.

```vue
<template>
  <UChangelogVersion title="Introducing Nitro UI v3" description="Nitro UI v3 is out! After 1500+ commits, this major redesign brings improved accessibility, Tailwind CSS support, and full Vue compatibility." />
</template>
```

### Dados

Use a prop `date` para exibir a data do ChangelogVersion.

> \[!TIP]
>
> A data é formatada automaticamente para o [locale atual](https://ui.nitro.news/docs/getting-started/integrations/i18n/nuxt#locale). Você pode passar um objeto `Date` ou uma string.

```vue
<template>
  <UChangelogVersion title="Introducing Nitro UI v3" description="Nitro UI v3 is out! After 1500+ commits, this major redesign brings improved accessibility, Tailwind CSS support, and full Vue compatibility." date="2025-03-12" />
</template>
```

### Badge

Use a prop `badge` para exibir um [Badge](https://ui.nitro.news/docs/components/badge) no ChangelogVersion.

```vue
<template>
  <UChangelogVersion title="Introducing Nitro UI v3" description="Nitro UI v3 is out! After 1500+ commits, this major redesign brings improved accessibility, Tailwind CSS support, and full Vue compatibility." date="2025-03-12" badge="Release" />
</template>
```

Você pode passar qualquer propriedade do componente [Badge](https://ui.nitro.news/docs/components/badge#props) para personalizá-lo.

```vue
<template>
  <UChangelogVersion title="Introducing Nitro UI v3" description="Nitro UI v3 is out! After 1500+ commits, this major redesign brings improved accessibility, Tailwind CSS support, and full Vue compatibility." date="2025-03-12" :badge="{
  label: 'Release',
  color: 'primary',
  variant: 'outline'
}" />
</template>
```

### Imagem

Use a prop `image` para exibir uma imagem no BlogPost.

> \[!NOTE]
>
> Se o [`@nuxt/image`](https://image.nuxt.com/get-started/installation){rel="&#x22;nofollow&#x22;"} estiver instalado, o componente `<NuxtImg>` será usado no lugar da tag `img` nativa.

```vue
<template>
  <UChangelogVersion title="Introducing Nitro UI v3" description="Nitro UI v3 is out! After 1500+ commits, this major redesign brings improved accessibility, Tailwind CSS support, and full Vue compatibility." date="2025-03-12" image="https://nuxt.com/assets/blog/nuxt-ui-v3.png" />
</template>
```

### Autores

Use a prop `authors` para exibir uma lista de [User](https://ui.nitro.news/docs/components/user) no ChangelogVersion como um array de objetos com as seguintes propriedades:

- `name?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `description?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `avatar?: Omit<AvatarProps, 'size'>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `chip?: boolean | Omit<ChipProps, 'size' | 'inset'>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `size?: UserProps['size']`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `orientation?: UserProps['orientation']`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Você pode passar qualquer propriedade do componente [Link](https://ui.nitro.news/docs/components/link#props), como `to`, `target`, etc.

```vue
<script setup lang="ts">
import type { UserProps } from '@nitro/ui'

const authors = ref<UserProps[]>([
  {
    name: "Benjamin Canac",
    description: "@benjamincanac",
    avatar: {
      src: "https://github.com/benjamincanac.png",
      loading: "lazy"
    },
    to: "https://x.com/benjamincanac",
    target: "_blank"
  },
  {
    name: "Sebastien Chopin",
    description: "@atinux",
    avatar: {
      src: "https://github.com/atinux.png",
      loading: "lazy"
    },
    to: "https://x.com/atinux",
    target: "_blank"
  },
  {
    name: "Hugo Richard",
    description: "@hugorcd__",
    avatar: {
      src: "https://github.com/hugorcd.png",
      loading: "lazy"
    },
    to: "https://x.com/hugorcd__",
    target: "_blank"
  }
])
</script>

<template>
  <UChangelogVersion title="Introducing Nitro UI v3" description="Nitro UI v3 is out! After 1500+ commits, this major redesign brings improved accessibility, Tailwind CSS support, and full Vue compatibility." date="2025-03-12" image="https://nuxt.com/assets/blog/nuxt-ui-v3.png" :authors="authors" />
</template>
```

### Link

Você pode passar qualquer propriedade do componente [`<NuxtLink>`](https://nuxt.com/docs/api/components/nuxt-link){rel="&#x22;nofollow&#x22;"}, como `to`, `target`, `rel`, etc.

```vue
<template>
  <UChangelogVersion title="Introducing Nitro UI v3" description="Nitro UI v3 is out! After 1500+ commits, this major redesign brings improved accessibility, Tailwind CSS support, and full Vue compatibility." date="2025-03-12" image="https://nuxt.com/assets/blog/nuxt-ui-v3.png" to="https://nuxt.com/blog/nuxt-ui-v3" target="_blank" />
</template>
```

### Indicador

Use a prop `indicator` para ocultar o ponto indicador à esquerda. O padrão é `true`.

```vue
<template>
  <UChangelogVersion title="Introducing Nitro UI v3" description="Nitro UI v3 is out! After 1500+ commits, this major redesign brings improved accessibility, Tailwind CSS support, and full Vue compatibility." date="2025-03-12" image="https://nuxt.com/assets/blog/nuxt-ui-v3.png" :indicator="false" />
</template>
```

> \[!NOTE]
>
> Quando a prop `indicator` é `false`, a data é exibida sobre o título.

## Exemplos

### Com slot de corpo

Você pode usar o slot `body` para exibir conteúdo personalizado entre a imagem e os autores com:

- the [MDC](https://github.com/nuxt-content/mdc?tab=readme-ov-file#mdc){rel="&#x22;nofollow&#x22;"} component from `@nuxtjs/mdc` to display some markdown.
- the [ContentRenderer](https://content.nuxt.com/docs/components/content-renderer){rel="&#x22;nofollow&#x22;"} component from `@nuxt/content` to render the content of the page or list.
- or use the `:n-changelog-version` component directly in your content with markdown inside the `body` slot as Nitro UI provides pre-styled prose components.

::component-example{collapse prettier name="changelog-version-markdown-example"}
::

## API

### Props

```ts
/**
 * Props for the ChangelogVersion component
 */
interface ChangelogVersionProps {
  /**
   * The element or component this component should render as.
   * @default "\"article\""
   */
  as?: any;
  title?: string | undefined;
  description?: string | undefined;
  /**
   * The date of the changelog version. Can be a string or a Date object.
   */
  date?: string | Date | undefined;
  /**
   * Display a badge on the changelog version.
   * Can be a string or an object.
   * `{ color: 'neutral', variant: 'solid' }`{lang="ts-type"}
   */
  badge?: string | BadgeProps | undefined;
  /**
   * The authors of the changelog version.
   */
  authors?: UserProps[] | undefined;
  /**
   * The image of the changelog version. Can be a string or an object.
   */
  image?: string | (Partial<ImgHTMLAttributes> & { [key: string]: any; }) | undefined;
  /**
   * Display an indicator dot on the left.
   * @default "true"
   */
  indicator?: boolean | undefined;
  to?: string | it | et | undefined;
  target?: "_blank" | "_parent" | "_self" | "_top" | (string & {}) | null | undefined;
  onClick?: ((event: MouseEvent) => void) | undefined;
  ui?: { root?: SlotClass; container?: SlotClass; header?: SlotClass; meta?: SlotClass; date?: SlotClass; badge?: SlotClass; title?: SlotClass; description?: SlotClass; imageWrapper?: SlotClass; image?: SlotClass; authors?: SlotClass; footer?: SlotClass; indicator?: SlotClass; dot?: SlotClass; dotInner?: SlotClass; } | undefined;
}
```

### Slots

```ts
/**
 * Slots for the ChangelogVersion component
 */
interface ChangelogVersionSlots {
  header(): any;
  badge(): any;
  date(): any;
  title(): any;
  description(): any;
  image(): any;
  body(): any;
  footer(): any;
  authors(): any;
  actions(): any;
  indicator(): any;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    changelogVersion: {
      slots: {
        root: 'relative',
        container: 'flex flex-col mx-auto max-w-2xl',
        header: '',
        meta: 'flex items-center gap-3 mb-2',
        date: 'text-sm/6 text-toned truncate',
        badge: '',
        title: 'relative text-xl text-pretty font-semibold text-highlighted',
        description: 'text-base text-pretty text-muted mt-1',
        imageWrapper: 'relative overflow-hidden rounded-lg aspect-[16/9] mt-5 group/changelog-version-image',
        image: 'object-cover object-top w-full h-full',
        authors: 'flex flex-wrap gap-x-4 gap-y-1.5',
        footer: 'border-t border-default pt-5 flex items-center justify-between',
        indicator: 'absolute start-0 top-0 w-32 hidden lg:flex items-center justify-end gap-3 min-w-0',
        dot: 'size-4 rounded-full bg-default ring ring-default flex items-center justify-center my-1',
        dotInner: 'size-2 rounded-full bg-primary'
      },
      variants: {
        body: {
          false: {
            footer: 'mt-5'
          }
        },
        badge: {
          false: {
            meta: 'lg:hidden'
          }
        },
        to: {
          true: {
            title: [
              'has-focus-visible:ring-2 has-focus-visible:ring-primary rounded-xs',
              'transition'
            ],
            image: 'transform transition-transform duration-200 group-hover/changelog-version-image:scale-105 group-has-focus-visible/changelog-version-image:scale-105'
          }
        },
        hidden: {
          true: {
            date: 'lg:hidden'
          }
        }
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/ChangelogVersion.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/changelog-version.ts).


# ChangelogVersions

## Uso

O componente ChangelogVersions oferece um layout flexível para exibir uma lista de componentes [ChangelogVersion](https://ui.nitro.news/docs/components/changelog-version) usando o slot padrão ou a prop `versions`.

```vue {2,8}
<template>
  <NChangelogVersions>
    <NChangelogVersion
      v-for="(version, index) in versions"
      :key="index"
      v-bind="version"
    />
  </NChangelogVersions>
</template>
```

### Versões

Use a prop `versions` como um array de objetos com as propriedades do componente [ChangelogVersion](https://ui.nitro.news/docs/components/changelog-version#props).

```vue
<script setup lang="ts">
import type { ChangelogVersionProps } from '@nitro/ui'

const versions = ref<ChangelogVersionProps[]>([
  {
    title: "Nuxt 3.17",
    description: "Nuxt 3.17 is out - bringing a major reworking of the async data layer, a new built-in component, better warnings, and performance improvements!",
    image: "https://nuxt.com/assets/blog/v3.17.png",
    date: "2025-04-27",
    to: "https://nuxt.com/blog/v3-17",
    target: "_blank",
    ui: {
      container: "max-w-lg"
    }
  },
  {
    title: "Nuxt 3.16",
    description: "Nuxt 3.16 is out - packed with features and performance improvements!",
    image: "https://nuxt.com/assets/blog/v3.16.png",
    date: "2025-03-07",
    to: "https://nuxt.com/blog/v3-16",
    target: "_blank",
    ui: {
      container: "max-w-lg"
    }
  },
  {
    title: "Nuxt 3.15",
    description: "Nuxt 3.15 is out - with Vite 6, better HMR and faster performance!",
    image: "https://nuxt.com/assets/blog/v3.15.png",
    date: "2024-12-24",
    to: "https://nuxt.com/blog/v3-15",
    target: "_blank",
    ui: {
      container: "max-w-lg"
    }
  }
])
</script>

<template>
  <UChangelogVersions :versions="versions" />
</template>
```

### Indicador

Use a prop `indicator` para ocultar a barra indicadora à esquerda. O padrão é `true`.

```vue
<script setup lang="ts">
import type { ChangelogVersionProps } from '@nitro/ui'

const versions = ref<ChangelogVersionProps[]>([
  {
    title: "Nuxt 3.17",
    description: "Nuxt 3.17 is out - bringing a major reworking of the async data layer, a new built-in component, better warnings, and performance improvements!",
    image: "https://nuxt.com/assets/blog/v3.17.png",
    date: "2025-04-27",
    to: "https://nuxt.com/blog/v3-17",
    target: "_blank",
    ui: {
      container: "max-w-lg"
    }
  },
  {
    title: "Nuxt 3.16",
    description: "Nuxt 3.16 is out - packed with features and performance improvements!",
    image: "https://nuxt.com/assets/blog/v3.16.png",
    date: "2025-03-07",
    to: "https://nuxt.com/blog/v3-16",
    target: "_blank",
    ui: {
      container: "max-w-lg"
    }
  },
  {
    title: "Nuxt 3.15",
    description: "Nuxt 3.15 is out - with Vite 6, better HMR and faster performance!",
    image: "https://nuxt.com/assets/blog/v3.15.png",
    date: "2024-12-24",
    to: "https://nuxt.com/blog/v3-15",
    target: "_blank",
    ui: {
      container: "max-w-lg"
    }
  }
])
</script>

<template>
  <UChangelogVersions :indicator="false" :versions="versions" />
</template>
```

### Movimento do indicador

Use a prop `indicator-motion` para personalizar ou ocultar o efeito de movimento na barra indicadora. O padrão é `true` com `{ damping: 30, restDelta: 0.001 }` [opções de transição spring](https://motion.dev/docs/vue-transitions#spring){rel="&#x22;nofollow&#x22;"}.

```vue
<script setup lang="ts">
import type { ChangelogVersionProps } from '@nitro/ui'

const versions = ref<ChangelogVersionProps[]>([
  {
    title: "Nuxt 3.17",
    description: "Nuxt 3.17 is out - bringing a major reworking of the async data layer, a new built-in component, better warnings, and performance improvements!",
    image: "https://nuxt.com/assets/blog/v3.17.png",
    date: "2025-04-27",
    to: "https://nuxt.com/blog/v3-17",
    target: "_blank",
    ui: {
      container: "max-w-lg"
    }
  },
  {
    title: "Nuxt 3.16",
    description: "Nuxt 3.16 is out - packed with features and performance improvements!",
    image: "https://nuxt.com/assets/blog/v3.16.png",
    date: "2025-03-07",
    to: "https://nuxt.com/blog/v3-16",
    target: "_blank",
    ui: {
      container: "max-w-lg"
    }
  },
  {
    title: "Nuxt 3.15",
    description: "Nuxt 3.15 is out - with Vite 6, better HMR and faster performance!",
    image: "https://nuxt.com/assets/blog/v3.15.png",
    date: "2024-12-24",
    to: "https://nuxt.com/blog/v3-15",
    target: "_blank",
    ui: {
      container: "max-w-lg"
    }
  }
])
</script>

<template>
  <UChangelogVersions indicator-motion :versions="versions" />
</template>
```

## Exemplos

> \[!NOTE]
>
> Embora estes exemplos usem o [Nuxt Content](https://content.nuxt.com){rel="&#x22;nofollow&#x22;"}, os componentes podem ser integrados a qualquer sistema de gerenciamento de conteúdo.

### Dentro de uma página

Use o componente ChangelogVersions em uma página para criar uma página de changelog:

```vue [pages/changelog.vue] {10-17}
<script setup lang="ts">
const { data: versions } = await useAsyncData('versions', () => queryCollection('versions').all())
</script>

<template>
  <NPage>
    <NPageHero title="Changelog" />

    <NPageBody>
      <NChangelogVersions>
        <NChangelogVersion
          v-for="(version, index) in versions"
          :key="index"
          v-bind="version"
          :to="version.path"
        />
      </NChangelogVersions>
    </NPageBody>
  </NPage>
</template>
```

> \[!NOTE]
>
> Neste exemplo, as `versions` são buscadas usando `queryCollection` do módulo `@nuxt/content`.

> \[!TIP]
>
> A prop `to` é sobrescrita aqui, já que o `@nuxt/content` usa a propriedade `path`.

### Com indicador fixo

Você pode usar a prop `ui` e os diferentes slots para tornar os indicadores fixos:

::component-example
---
collapse: true
prettier: true
props:
  class: w-full
class: p-8
name: changelog-versions-sticky-example
---
::

### Com container de rolagem `4.4+`

Passe um objeto para a prop `indicator` para configurar o container de rolagem. Por padrão, o indicador acompanha a rolagem da janela/página (<https://motion.dev/docs/vue-use-scroll#page-scroll>{rel="&#x22;nofollow&#x22;"}).

```vue
<script setup lang="ts">
const scrollContainer = ref<HTMLElement>()
</script>

<template>
  <div ref="scrollContainer" class="max-h-96 overflow-y-auto">
    <NChangelogVersions v-if="scrollContainer" :indicator="{ container: scrollContainer }" />
  </div>
</template>
```

> \[!WARNING]
>
> Ao usar um `container` personalizado, certifique-se de que o elemento do container esteja montado antes do `UChangelogVersions`.

## API

### Props

```ts
/**
 * Props for the ChangelogVersions component
 */
interface ChangelogVersionsProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  versions?: T[] | undefined;
  /**
   * Display an indicator bar on the left.
   * By default, the indicator will track the scroll of the page. (https://motion.dev/docs/vue-use-scroll#page-scroll)
   * @default "true"
   */
  indicator?: boolean | UseScrollOptions | undefined;
  /**
   * Enable scrolling motion effect on the indicator bar.
   * `{ damping: 30, restDelta: 0.001 }`{lang="ts-type"}
   * @default "true"
   */
  indicatorMotion?: boolean | SpringOptions | undefined;
  ui?: { root?: SlotClass; container?: SlotClass; indicator?: SlotClass; beam?: SlotClass; } | undefined;
}
```

### Slots

```ts
/**
 * Slots for the ChangelogVersions component
 */
interface ChangelogVersionsSlots {
  header(): any;
  badge(): any;
  date(): any;
  title(): any;
  description(): any;
  image(): any;
  body(): any;
  footer(): any;
  authors(): any;
  actions(): any;
  indicator(): any;
  default(): any;
}
```

> \[!TIP]
>
> Você pode usar todos os slots do componente [`ChangelogVersion`](https://ui.nitro.news/docs/components/changelog-version#slots) dentro do ChangelogVersions; eles são repassados automaticamente, permitindo personalizar versões individuais ao usar a prop `versions`.
>
> ```vue {3-5}
> <template>
>   <NChangelogVersions :versions="versions">
>     <template #body="{ version }">
>       <MDC v-if="version.content" :value="version.content" />
>     </template>
>   </NChangelogVersions>
> </template>
> ```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    changelogVersions: {
      slots: {
        root: 'relative',
        container: 'flex flex-col gap-y-8 sm:gap-y-12 lg:gap-y-16',
        indicator: 'absolute hidden lg:block overflow-hidden inset-y-3 start-32 h-full w-px bg-border -ms-[8.5px]',
        beam: 'absolute start-0 top-0 w-full bg-primary will-change-[height]'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/ChangelogVersions.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/changelog-versions.ts).


# Chat

O Nitro UI fornece um conjunto de componentes projetados para construir interfaces de chat com IA. Eles se integram perfeitamente ao [Vercel AI SDK](https://ai-sdk.dev/){rel="&#x22;nofollow&#x22;"} para respostas em streaming, raciocínio, chamada de ferramentas e mais.

> \[!NOTE]
>
> Confira os templates de Chat de IA para [`Nuxt`](https://github.com/nuxt-ui-templates/chat){rel="&#x22;nofollow&#x22;"} e [`Vue`](https://github.com/nuxt-ui-templates/chat-vue){rel="&#x22;nofollow&#x22;"} no GitHub para implementações prontas para produção.

## Componentes

| Component                                                                    | Description                                                     |
| ---------------------------------------------------------------------------- | --------------------------------------------------------------- |
| [ChatMessages](https://ui.nitro.news/docs/components/chat-messages)          | Scrollable message list with auto-scroll and loading indicator. |
| [ChatMessage](https://ui.nitro.news/docs/components/chat-message)            | Individual message bubble with avatar, actions, and slots.      |
| [ChatPrompt](https://ui.nitro.news/docs/components/chat-prompt)              | Enhanced textarea for submitting prompts.                       |
| [ChatPromptSubmit](https://ui.nitro.news/docs/components/chat-prompt-submit) | Submit button with automatic status handling.                   |
| [ChatReasoning](https://ui.nitro.news/docs/components/chat-reasoning)        | Collapsible block for AI reasoning / thinking process.          |
| [ChatTool](https://ui.nitro.news/docs/components/chat-tool)                  | Collapsible block for AI tool invocation status.                |
| [ChatShimmer](https://ui.nitro.news/docs/components/chat-shimmer)            | Text shimmer animation for streaming states.                    |
| [ChatPalette](https://ui.nitro.news/docs/components/chat-palette)            | Layout wrapper for embedding chat in modals or drawers.         |

## Instalação

Os componentes de Chat são projetados para serem usados com o [Vercel AI SDK](https://ai-sdk.dev/){rel="&#x22;nofollow&#x22;"}, especificamente a classe [`Chat`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat){rel="&#x22;nofollow&#x22;"} para gerenciar o estado do chat e as respostas em streaming.

Install the required dependencies:

**Nuxt:**

```bash [pnpm]
pnpm add ai @ai-sdk/gateway @ai-sdk/vue @comark/nuxt
```

```bash [yarn]
yarn add ai @ai-sdk/gateway @ai-sdk/vue @comark/nuxt
```

```bash [npm]
npm install ai @ai-sdk/gateway @ai-sdk/vue @comark/nuxt
```

```bash [bun]
bun add ai @ai-sdk/gateway @ai-sdk/vue @comark/nuxt
```

Adicione `@comark/nuxt` aos seus módulos:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: [
    '@nitro/ui',
    '@comark/nuxt'
  ]
})
```

> \[!NOTE]
>
> [`@comark/nuxt`](https://comark.dev/rendering/nuxt){rel="&#x22;nofollow&#x22;"} provides the `Comark` component used to render AI responses as streaming Markdown, it incrementally renders tokens as they arrive, avoiding the flicker and re-parsing that traditional Markdown renderers cause. It also automatically enables Nitro UI's [prose components](https://ui.nitro.news/docs/typography) so your content is styled to match your theme.

**Vue:**

```bash [pnpm]
pnpm add ai @ai-sdk/gateway @ai-sdk/vue @comark/vue
```

```bash [yarn]
yarn add ai @ai-sdk/gateway @ai-sdk/vue @comark/vue
```

```bash [npm]
npm install ai @ai-sdk/gateway @ai-sdk/vue @comark/vue
```

```bash [bun]
bun add ai @ai-sdk/gateway @ai-sdk/vue @comark/vue
```

> \[!NOTE]
>
> [`@comark/vue`](https://comark.dev/rendering/vue){rel="&#x22;nofollow&#x22;"} provides the `Comark` component used to render AI responses as streaming Markdown, it incrementally renders tokens as they arrive, avoiding the flicker and re-parsing that traditional Markdown renderers cause.
> :br:br Para usar os [componentes de prose](https://ui.nitro.news/docs/typography) do Nitro UI com o Comark, habilite a opção `prose` no seu `vite.config.ts`:
>
> ```ts [vite.config.ts] {9}
> import { defineConfig } from 'vite'
> import vue from '@vitejs/plugin-vue'
> import ui from '@nitro/ui/vite'
>
> export default defineConfig({
>   plugins: [
>     vue(),
>     ui({
>       prose: true
>     })
>   ]
> })
> ```

## Configuração do servidor

Crie um endpoint de API no servidor para tratar as requisições de chat usando [`streamText`](https://ai-sdk.dev/docs/reference/ai-sdk-core/stream-text){rel="&#x22;nofollow&#x22;"}. Você pode usar o [Vercel AI Gateway](https://vercel.com/ai-gateway){rel="&#x22;nofollow&#x22;"} para acessar modelos de IA por meio de um endpoint centralizado:

```ts [server/api/chat.post.ts]
import { streamText, convertToModelMessages, toUIMessageStream, createUIMessageStreamResponse } from 'ai'
import { gateway } from '@ai-sdk/gateway'

export default defineEventHandler(async (event) => {
  const { messages } = await readBody(event)

  const result = streamText({
    model: gateway('anthropic/claude-sonnet-5'),
    maxOutputTokens: 10000,
    instructions: 'You are a helpful assistant.',
    messages: await convertToModelMessages(messages)
  })

  const stream = toUIMessageStream({ stream: result.stream })
  return createUIMessageStreamResponse({ stream })
})
```

### Raciocínio

Para habilitar o [raciocínio](https://ai-sdk.dev/docs/ai-sdk-ui/chatbot#reasoning){rel="&#x22;nofollow&#x22;"}, configure `providerOptions` para o seu provedor ([Anthropic](https://ai-sdk.dev/docs/guides/providers/anthropic#reasoning){rel="&#x22;nofollow&#x22;"}, [Google](https://ai-sdk.dev/providers/ai-sdk-providers/google-generative-ai#thinking){rel="&#x22;nofollow&#x22;"}, [OpenAI](https://ai-sdk.dev/docs/guides/providers/openai#reasoning){rel="&#x22;nofollow&#x22;"}):

```ts [server/api/chat.post.ts]
import { streamText, convertToModelMessages, toUIMessageStream, createUIMessageStreamResponse } from 'ai'
import { gateway } from '@ai-sdk/gateway'

export default defineEventHandler(async (event) => {
  const { messages } = await readBody(event)

  const result = streamText({
    model: gateway('anthropic/claude-sonnet-5'),
    maxOutputTokens: 10000,
    instructions: 'You are a helpful assistant.',
    messages: await convertToModelMessages(messages),
    providerOptions: {
      anthropic: {
        thinking: {
          type: 'adaptive'
        },
        effort: 'low'
      },
      google: {
        thinkingConfig: {
          includeThoughts: true,
          thinkingLevel: 'low'
        }
      },
      openai: {
        reasoningEffort: 'low',
        reasoningSummary: 'detailed'
      }
    }
  })

  const stream = toUIMessageStream({ stream: result.stream })
  return createUIMessageStreamResponse({ stream })
})
```

### Busca na web

Some providers offer built-in web search tools: [Anthropic](https://ai-sdk.dev/docs/guides/providers/anthropic#web-search-tool){rel="&#x22;nofollow&#x22;"}, [Google](https://ai-sdk.dev/providers/ai-sdk-providers/google-generative-ai#google-search){rel="&#x22;nofollow&#x22;"}, [OpenAI](https://ai-sdk.dev/providers/ai-sdk-providers/openai#web-search-tool){rel="&#x22;nofollow&#x22;"}.

```ts [Anthropic]
import { streamText, convertToModelMessages, toUIMessageStream, createUIMessageStreamResponse } from 'ai'
import { anthropic } from '@ai-sdk/anthropic'
import { gateway } from '@ai-sdk/gateway'

export default defineEventHandler(async (event) => {
  const { messages } = await readBody(event)

  const result = streamText({
    model: gateway('anthropic/claude-sonnet-5'),
    instructions: 'You are a helpful assistant.',
    messages: await convertToModelMessages(messages),
    tools: {
      web_search: anthropic.tools.webSearch_20250305({})
    }
  })

  const stream = toUIMessageStream({ stream: result.stream })
  return createUIMessageStreamResponse({ stream })
})
```

```ts [Google]
import { streamText, convertToModelMessages, toUIMessageStream, createUIMessageStreamResponse } from 'ai'
import { google } from '@ai-sdk/google'
import { gateway } from '@ai-sdk/gateway'

export default defineEventHandler(async (event) => {
  const { messages } = await readBody(event)

  const result = streamText({
    model: gateway('google/gemini-3-flash'),
    instructions: 'You are a helpful assistant.',
    messages: await convertToModelMessages(messages),
    tools: {
      google_search: google.tools.googleSearch({})
    }
  })

  const stream = toUIMessageStream({ stream: result.stream })
  return createUIMessageStreamResponse({ stream })
})
```

```ts [OpenAI]
import { streamText, convertToModelMessages, toUIMessageStream, createUIMessageStreamResponse } from 'ai'
import { openai } from '@ai-sdk/openai'
import { gateway } from '@ai-sdk/gateway'

export default defineEventHandler(async (event) => {
  const { messages } = await readBody(event)

  const result = streamText({
    model: gateway('openai/gpt-5-nano'),
    instructions: 'You are a helpful assistant.',
    messages: await convertToModelMessages(messages),
    tools: {
      web_search: openai.tools.webSearch({})
    }
  })

  const stream = toUIMessageStream({ stream: result.stream })
  return createUIMessageStreamResponse({ stream })
})
```

### Cliente MCP

Potencialize seu chatbot com recursos avançados de chamada de ferramentas usando o [Model Context Protocol (MCP)](https://ai-sdk.dev/docs/ai-sdk-core/mcp-tools){rel="&#x22;nofollow&#x22;"} de `@ai-sdk/mcp`. O MCP permite que sua IA execute ações dinâmicas, como buscar na sua documentação ou executar tarefas personalizadas, para fornecer respostas mais relevantes e precisas.

Para começar, instale o pacote MCP:

```bash [npm]
npm install @ai-sdk/mcp
```

```bash [pnpm]
pnpm add @ai-sdk/mcp
```

```bash [yarn]
yarn add @ai-sdk/mcp
```

Depois, configure o endpoint do seu servidor para usar ferramentas MCP:

```ts [server/api/chat.post.ts]
import { streamText, convertToModelMessages, isStepCount, toUIMessageStream, createUIMessageStreamResponse } from 'ai'
import { createMCPClient } from '@ai-sdk/mcp'
import { gateway } from '@ai-sdk/gateway'

export default defineEventHandler(async (event) => {
  const { messages } = await readBody(event)

  const httpClient = await createMCPClient({
    transport: { type: 'http', url: 'https://your-app.com/mcp' }
  })
  try {
    const tools = await httpClient.tools()

    const result = streamText({
      model: gateway('anthropic/claude-sonnet-5'),
      maxOutputTokens: 10000,
      instructions: 'You are a helpful assistant. Use your tools to search for relevant information before answering questions.',
      messages: await convertToModelMessages(messages),
      stopWhen: isStepCount(6),
      tools,
      onEnd: async () => {
        await httpClient.close()
      },
      onError: async (error) => {
        console.error(error)
        await httpClient.close()
      }
    })

    const stream = toUIMessageStream({ stream: result.stream })
    return createUIMessageStreamResponse({ stream })
  } catch (error) {
    // Close the MCP client if setup fails before streaming starts
    await httpClient.close()
    throw error
  }
})
```

### Aprovação de ferramenta

Exija uma confirmação do usuário antes de uma ferramenta executar com a opção [`toolApproval`](https://ai-sdk.dev/docs/agents/tool-approvals){rel="&#x22;nofollow&#x22;"}. O tool part pausa no estado `approval-requested` até o usuário responder:

```ts [server/api/chat.post.ts]
import { streamText, convertToModelMessages, toUIMessageStream, createUIMessageStreamResponse, tool } from 'ai'
import { gateway } from '@ai-sdk/gateway'
import { z } from 'zod'

export default defineEventHandler(async (event) => {
  const { messages } = await readBody(event)

  const result = streamText({
    model: gateway('anthropic/claude-sonnet-5'),
    maxOutputTokens: 10000,
    instructions: 'You are a helpful assistant.',
    messages: await convertToModelMessages(messages),
    tools: {
      deleteFile: tool({
        description: 'Delete a file from the project',
        inputSchema: z.object({ path: z.string() }),
        execute: async ({ path }) => ({ deleted: path })
      })
    },
    toolApproval: {
      deleteFile: 'user-approval'
    }
  })

  const stream = toUIMessageStream({ stream: result.stream })
  return createUIMessageStreamResponse({ stream })
})
```

## Configuração do cliente

Use o composable `useChat` de `@ai-sdk/vue` para gerenciar o estado do chat e conectar-se ao endpoint do seu servidor:

**Nuxt:**

```vue
<script setup lang="ts">
import { isReasoningUIPart, isTextUIPart, isToolUIPart, getToolName, lastAssistantMessageIsCompleteWithApprovalResponses } from 'ai'
import { useChat } from '@ai-sdk/vue'
import { isPartStreaming, isToolStreaming } from '@nitro/ui/utils/ai'
import highlight from '@comark/nuxt/plugins/highlight'

const input = ref('')

const { messages, status, error, sendMessage, regenerate, stop, addToolApprovalResponse } = useChat({
  sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithApprovalResponses,
  onError(error) {
    console.error(error)
  }
})

function onSubmit() {
  sendMessage({ text: input.value })

  input.value = ''
}
</script>

<template>
  <NChatMessages
    :messages="messages"
    :status="status"
  >
    <template #content="{ message }">
      <template
        v-for="(part, index) in message.parts"
        :key="`${message.id}-${part.type}-${index}`"
      >
        <NChatReasoning
          v-if="isReasoningUIPart(part)"
          :text="part.text"
          :streaming="isPartStreaming(part)"
        >
          <Comark
            :markdown="part.text"
            :streaming="isPartStreaming(part)"
            :plugins="[highlight()]"
            class="*:first:mt-0 *:last:mb-0"
          />
        </NChatReasoning>

        <NChatTool
          v-else-if="isToolUIPart(part)"
          :text="getToolName(part)"
          :streaming="isToolStreaming(part)"
          :actions="part.state === 'approval-requested' ? [
            { label: 'Approve', onClick: () => addToolApprovalResponse({ id: part.approval.id, approved: true }) },
            { label: 'Deny', color: 'neutral', variant: 'ghost', onClick: () => addToolApprovalResponse({ id: part.approval.id, approved: false }) }
          ] : undefined"
        />

        <template v-else-if="isTextUIPart(part)">
          <Comark
            v-if="message.role === 'assistant'"
            :markdown="part.text"
            :streaming="isPartStreaming(part)"
            :plugins="[highlight()]"
            class="*:first:mt-0 *:last:mb-0"
          />
          <p v-else-if="message.role === 'user'" class="whitespace-pre-wrap">
            {{ part.text }}
          </p>
        </template>
      </template>
    </template>
  </NChatMessages>

  <NChatPrompt
    v-model="input"
    :error="error"
    @submit="onSubmit"
  >
    <NChatPromptSubmit
      :status="status"
      @stop="stop()"
      @reload="regenerate()"
    />
  </NChatPrompt>
</template>
```

**Vue:**

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { isReasoningUIPart, isTextUIPart, isToolUIPart, getToolName, lastAssistantMessageIsCompleteWithApprovalResponses } from 'ai'
import { useChat } from '@ai-sdk/vue'
import { isPartStreaming, isToolStreaming } from '@nitro/ui/utils/ai'
import { Comark } from '@comark/vue'
import highlight from '@comark/vue/plugins/highlight'

const input = ref('')

const { messages, status, error, sendMessage, regenerate, stop, addToolApprovalResponse } = useChat({
  sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithApprovalResponses,
  onError(error) {
    console.error(error)
  }
})

function onSubmit() {
  sendMessage({ text: input.value })

  input.value = ''
}
</script>

<template>
  <NChatMessages
    :messages="messages"
    :status="status"
  >
    <template #content="{ message }">
      <template
        v-for="(part, index) in message.parts"
        :key="`${message.id}-${part.type}-${index}`"
      >
        <NChatReasoning
          v-if="isReasoningUIPart(part)"
          :text="part.text"
          :streaming="isPartStreaming(part)"
        >
          <Comark
            :markdown="part.text"
            :streaming="isPartStreaming(part)"
            :plugins="[highlight()]"
            class="*:first:mt-0 *:last:mb-0"
          />
        </NChatReasoning>

        <NChatTool
          v-else-if="isToolUIPart(part)"
          :text="getToolName(part)"
          :streaming="isToolStreaming(part)"
          :actions="part.state === 'approval-requested' ? [
            { label: 'Approve', onClick: () => addToolApprovalResponse({ id: part.approval.id, approved: true }) },
            { label: 'Deny', color: 'neutral', variant: 'ghost', onClick: () => addToolApprovalResponse({ id: part.approval.id, approved: false }) }
          ] : undefined"
        />

        <template v-else-if="isTextUIPart(part)">
          <Comark
            v-if="message.role === 'assistant'"
            :markdown="part.text"
            :streaming="isPartStreaming(part)"
            :plugins="[highlight()]"
            class="*:first:mt-0 *:last:mb-0"
          />
          <p v-else-if="message.role === 'user'" class="whitespace-pre-wrap">
            {{ part.text }}
          </p>
        </template>
      </template>
    </template>
  </NChatMessages>

  <NChatPrompt
    v-model="input"
    :error="error"
    @submit="onSubmit"
  >
    <NChatPromptSubmit
      :status="status"
      @stop="stop()"
      @reload="regenerate()"
    />
  </NChatPrompt>
</template>
```

> \[!TIP]
>
> Para uma configuração reutilizável do Comark (plugins, class, etc.), use [`defineComarkComponent`](https://comark.dev/rendering/vue#code-definecomarkcomponent){rel="&#x22;nofollow&#x22;"} para criar um componente personalizado em vez de passar as props inline a cada vez.
>
> ```ts [components/chat/Comark.ts]
> import highlight from '@comark/nuxt/plugins/highlight'
>
> export default defineComarkComponent({
>   name: 'ChatComark',
>   plugins: [highlight()],
>   class: '*:first:mt-0 *:last:mb-0'
> })
> ```
>
> ```ts [components/chat/Comark.ts]
> import { defineComarkComponent } from '@comark/vue'
> import highlight from '@comark/vue/plugins/highlight'
>
> export default defineComarkComponent({
>   name: 'ChatComark',
>   plugins: [highlight()],
>   class: '*:first:mt-0 *:last:mb-0'
> })
> ```

> \[!NOTE]
>
> Ao usar o plugin `highlight`, adicione o seguinte CSS à sua folha de estilo para dar suporte ao modo escuro:
>
> ```css [main.css]
> html.dark .shiki span {
>   color: var(--shiki-dark) !important;
>   background-color: var(--shiki-dark-bg) !important;
>   font-style: var(--shiki-dark-font-style) !important;
>   font-weight: var(--shiki-dark-font-weight) !important;
>   text-decoration: var(--shiki-dark-text-decoration) !important;
> }
> ```


# ChatMessage

## Uso

O componente ChatMessage renderiza um elemento `<article>` para uma mensagem de chat de `user` ou `assistant`.

```vue
<template>
  <n-chat-message :avatar={"src":"https://github.com/benjamincanac.png","loading":"lazy"} :parts=[{"type":"text","id":"1","text":"Hello! Tell me more about building AI chatbots with Nitro UI."}] id=1 role=user side=right variant=soft />
</template>
```

> \[!TIP]
> See: /docs/components/chat-messages
>
> Use o componente `ChatMessages` para exibir uma lista de mensagens de chat.

### Partes

Use a prop `parts` para exibir o conteúdo da mensagem usando o formato do AI SDK.

```vue
<template>
  <UChatMessage :parts="[
  {
    type: 'text',
    id: '1',
    text: 'Hello! Tell me more about building AI chatbots with Nitro UI.'
  }
]" role="user" id="1" />
</template>
```

> \[!NOTE]
>
> A prop `parts` é o formato recomendado para o AI SDK. Cada part tem um `type` (ex.: 'text') e o conteúdo correspondente. O componente ChatMessage também suporta a prop `content` (obsoleta) para compatibilidade retroativa.

### Lado

Use a prop `side` para exibir a mensagem à esquerda ou à direita.

```vue
<template>
  <UChatMessage side="right" :parts="[
  {
    type: 'text',
    id: '1',
    text: 'Hello! Tell me more about building AI chatbots with Nitro UI.'
  }
]" role="user" id="1" />
</template>
```

> \[!NOTE]
>
> Ao usar o componente [`ChatMessages`](https://ui.nitro.news/docs/components/chat-messages), a prop `side` é definida como `left` para mensagens de `assistant` e `right` para mensagens de `user`.

### Variante

Use a prop `variant` para alterar o estilo da mensagem.

```vue
<template>
  <UChatMessage variant="soft" :parts="[
  {
    type: 'text',
    id: '1',
    text: 'Hello! Tell me more about building AI chatbots with Nitro UI.'
  }
]" role="user" id="1" />
</template>
```

> \[!NOTE]
>
> Ao usar o componente [`ChatMessages`](https://ui.nitro.news/docs/components/chat-messages), a prop `variant` é definida como `naked` para mensagens de `assistant` e `soft` para mensagens de `user`.

### Cor `4.8+`

Use a prop `color` para alterar a cor da mensagem.

```vue
<template>
  <UChatMessage variant="soft" color="primary" :parts="[
  {
    type: 'text',
    id: '1',
    text: 'Hello! Tell me more about building AI chatbots with Nitro UI.'
  }
]" role="user" id="1" />
</template>
```

### Ícone

Use a prop `icon` para exibir um componente [Icon](https://ui.nitro.news/docs/components/icon) ao lado da mensagem.

```vue
<template>
  <UChatMessage icon="i-lucide-user" variant="soft" side="right" :parts="[
  {
    type: 'text',
    id: '1',
    text: 'Hello! Tell me more about building AI chatbots with Nitro UI.'
  }
]" role="user" id="1" />
</template>
```

### Avatar

Use a prop `avatar` para exibir um componente [Avatar](https://ui.nitro.news/docs/components/avatar) ao lado da mensagem.

```vue
<template>
  <UChatMessage :avatar="{
  src: 'https://github.com/benjamincanac.png',
  loading: 'lazy'
}" variant="soft" side="right" :parts="[
  {
    type: 'text',
    id: '1',
    text: 'Hello! Tell me more about building AI chatbots with Nitro UI.'
  }
]" role="user" id="1" />
</template>
```

Você também pode usar a prop `avatar.icon` para exibir um ícone como avatar.

```vue
<template>
  <UChatMessage :avatar="{
  icon: 'i-lucide-bot'
}" :parts="[
  {
    type: 'text',
    id: '1',
    text: 'Nitro UI offers several features for building AI chatbots including the ChatMessage, ChatMessages, and ChatPrompt components. Best practices include using the Chat class from AI SDK, implementing proper message styling with variants, and utilizing the built-in actions for message interactions. The components are fully customizable with theming support and responsive design.'
  }
]" role="assistant" id="1" />
</template>
```

### Ações

Use a prop `actions` para exibir ações abaixo da mensagem, que serão mostradas ao passar o mouse sobre a mensagem.

```vue
<script setup lang="ts">
import type { ButtonProps } from '@nitro/ui'

const actions = ref<ButtonProps[]>([
  {
    label: "Copy to clipboard",
    icon: "i-lucide-copy"
  }
])
</script>

<template>
  <UChatMessage :actions="actions" :parts="[
  {
    type: 'text',
    id: '1',
    text: 'Nitro UI offers several features for building AI chatbots including the ChatMessage, ChatMessages, and ChatPrompt components. Best practices include using the Chat class from AI SDK, implementing proper message styling with variants, and utilizing the built-in actions for message interactions. The components are fully customizable with theming support and responsive design.'
  }
]" role="user" id="1" />
</template>
```

## Exemplos

> \[!TIP]
> See: /docs/components/chat
>
> Confira a página de visão geral do **Chat** para instruções de instalação, configuração do servidor e exemplos de uso.

## API

### Props

```ts
/**
 * Props for the ChatMessage component
 */
interface ChatMessageProps {
  /**
   * A unique identifier for the message.
   */
  id: string;
  /**
   * The role of the message.
   */
  role: "system" | "user" | "assistant";
  /**
   * The parts of the message. Use this for rendering the message in the UI.
   * 
   * System messages should be avoided (set the system prompt on the server instead).
   * They can have text parts.
   * 
   * User messages can have text parts and file parts.
   * 
   * Assistant messages can have text, reasoning, tool invocation, and file parts.
   */
  parts: UIMessagePart<TDataParts, TTools>[];
  /**
   * The element or component this component should render as.
   * @default "\"article\""
   */
  as?: any;
  icon?: any;
  avatar?: (AvatarProps & { [key: string]: any; }) | undefined;
  variant?: "solid" | "outline" | "soft" | "subtle" | "naked" | undefined;
  color?: "primary" | "secondary" | "accent" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
  side?: "left" | "right" | undefined;
  /**
   * Display a list of actions under the message.
   * The `label` will be used in a tooltip.
   * `{ size: 'xs', color: 'neutral', variant: 'ghost' }`{lang="ts-type"}
   */
  actions?: (Omit<ButtonProps, "onClick"> & { onClick?: ((e: MouseEvent, message: UIMessage<TMetadata, TDataParts, TTools>) => void) | undefined; })[] | undefined;
  /**
   * Render the message in a compact style.
   * This is done automatically when used inside a `UChatPalette`{lang="ts-type"}.
   */
  compact?: boolean | undefined;
  content?: string | undefined;
  ui?: { root?: SlotClass; header?: SlotClass; container?: SlotClass; body?: SlotClass; leading?: SlotClass; leadingIcon?: SlotClass; leadingAvatar?: SlotClass; leadingAvatarSize?: SlotClass; files?: SlotClass; content?: SlotClass; actions?: SlotClass; } | undefined;
  /**
   * The metadata of the message.
   */
  metadata?: TMetadata | undefined;
}
```

### Slots

```ts
/**
 * Slots for the ChatMessage component
 */
interface ChatMessageSlots {
  header(): any;
  leading(): any;
  files(): any;
  body(): any;
  content(): any;
  actions(): any;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    chatMessage: {
      slots: {
        root: 'group/message relative w-full',
        header: 'flex mb-1.5',
        container: 'relative flex items-start',
        body: 'min-w-0',
        leading: 'inline-flex items-center justify-center min-h-6',
        leadingIcon: 'shrink-0',
        leadingAvatar: 'shrink-0',
        leadingAvatarSize: '',
        files: 'flex items-center gap-1.5',
        content: 'relative text-pretty wrap-break-word *:first:mt-0 *:last:mb-0',
        actions: [
          '[@media(hover:hover)]:opacity-0 group-hover/message:opacity-100 absolute bottom-0 flex items-center',
          'transition-opacity'
        ]
      },
      variants: {
        variant: {
          solid: '',
          outline: '',
          soft: '',
          subtle: '',
          naked: ''
        },
        color: {
          primary: '',
          secondary: '',
          accent: '',
          success: '',
          info: '',
          warning: '',
          error: '',
          neutral: ''
        },
        side: {
          left: {},
          right: {
            container: 'justify-end ms-auto max-w-[75%]',
            header: 'justify-end',
            actions: 'right-0'
          }
        },
        leading: {
          true: ''
        },
        actions: {
          true: ''
        },
        compact: {
          true: {
            root: 'scroll-mt-3',
            container: 'gap-1.5 pb-3',
            content: 'space-y-2',
            leadingIcon: 'size-5',
            leadingAvatarSize: '2xs'
          },
          false: {
            root: 'scroll-mt-4 sm:scroll-mt-6',
            container: 'gap-3 pb-8',
            content: 'space-y-4',
            leadingIcon: 'size-8',
            leadingAvatarSize: 'md'
          }
        }
      },
      compoundVariants: [
        {
          compact: true,
          actions: true,
          class: {
            container: 'pb-8'
          }
        },
        {
          variant: [
            'solid',
            'outline',
            'soft',
            'subtle'
          ],
          compact: false,
          class: {
            content: 'px-4 py-3 rounded-lg min-h-12',
            leading: 'mt-2'
          }
        },
        {
          variant: [
            'solid',
            'outline',
            'soft',
            'subtle'
          ],
          compact: true,
          class: {
            content: 'px-2 py-1 rounded-lg min-h-8',
            leading: 'mt-1'
          }
        },
        {
          variant: 'naked',
          side: 'left',
          class: {
            body: 'w-full',
            content: 'w-full'
          }
        },
        {
          color: 'primary',
          variant: 'solid',
          class: {
            content: 'bg-primary text-inverted'
          }
        },
        {
          color: 'secondary',
          variant: 'solid',
          class: {
            content: 'bg-secondary text-inverted'
          }
        },
        {
          color: 'accent',
          variant: 'solid',
          class: {
            content: 'bg-accent text-inverted'
          }
        },
        {
          color: 'success',
          variant: 'solid',
          class: {
            content: 'bg-success text-inverted'
          }
        },
        {
          color: 'info',
          variant: 'solid',
          class: {
            content: 'bg-info text-inverted'
          }
        },
        {
          color: 'warning',
          variant: 'solid',
          class: {
            content: 'bg-warning text-inverted'
          }
        },
        {
          color: 'error',
          variant: 'solid',
          class: {
            content: 'bg-error text-inverted'
          }
        },
        {
          color: 'primary',
          variant: 'outline',
          class: {
            content: 'text-primary ring ring-primary/25'
          }
        },
        {
          color: 'secondary',
          variant: 'outline',
          class: {
            content: 'text-secondary ring ring-secondary/25'
          }
        },
        {
          color: 'accent',
          variant: 'outline',
          class: {
            content: 'text-accent ring ring-accent/25'
          }
        },
        {
          color: 'success',
          variant: 'outline',
          class: {
            content: 'text-success ring ring-success/25'
          }
        },
        {
          color: 'info',
          variant: 'outline',
          class: {
            content: 'text-info ring ring-info/25'
          }
        },
        {
          color: 'warning',
          variant: 'outline',
          class: {
            content: 'text-warning ring ring-warning/25'
          }
        },
        {
          color: 'error',
          variant: 'outline',
          class: {
            content: 'text-error ring ring-error/25'
          }
        },
        {
          color: 'primary',
          variant: 'soft',
          class: {
            content: 'bg-primary/10 text-primary'
          }
        },
        {
          color: 'secondary',
          variant: 'soft',
          class: {
            content: 'bg-secondary/10 text-secondary'
          }
        },
        {
          color: 'accent',
          variant: 'soft',
          class: {
            content: 'bg-accent/10 text-accent'
          }
        },
        {
          color: 'success',
          variant: 'soft',
          class: {
            content: 'bg-success/10 text-success'
          }
        },
        {
          color: 'info',
          variant: 'soft',
          class: {
            content: 'bg-info/10 text-info'
          }
        },
        {
          color: 'warning',
          variant: 'soft',
          class: {
            content: 'bg-warning/10 text-warning'
          }
        },
        {
          color: 'error',
          variant: 'soft',
          class: {
            content: 'bg-error/10 text-error'
          }
        },
        {
          color: 'primary',
          variant: 'subtle',
          class: {
            content: 'bg-primary/10 text-primary ring ring-primary/25'
          }
        },
        {
          color: 'secondary',
          variant: 'subtle',
          class: {
            content: 'bg-secondary/10 text-secondary ring ring-secondary/25'
          }
        },
        {
          color: 'accent',
          variant: 'subtle',
          class: {
            content: 'bg-accent/10 text-accent ring ring-accent/25'
          }
        },
        {
          color: 'success',
          variant: 'subtle',
          class: {
            content: 'bg-success/10 text-success ring ring-success/25'
          }
        },
        {
          color: 'info',
          variant: 'subtle',
          class: {
            content: 'bg-info/10 text-info ring ring-info/25'
          }
        },
        {
          color: 'warning',
          variant: 'subtle',
          class: {
            content: 'bg-warning/10 text-warning ring ring-warning/25'
          }
        },
        {
          color: 'error',
          variant: 'subtle',
          class: {
            content: 'bg-error/10 text-error ring ring-error/25'
          }
        },
        {
          color: 'primary',
          variant: 'naked',
          class: {
            content: 'text-primary'
          }
        },
        {
          color: 'secondary',
          variant: 'naked',
          class: {
            content: 'text-secondary'
          }
        },
        {
          color: 'accent',
          variant: 'naked',
          class: {
            content: 'text-accent'
          }
        },
        {
          color: 'success',
          variant: 'naked',
          class: {
            content: 'text-success'
          }
        },
        {
          color: 'info',
          variant: 'naked',
          class: {
            content: 'text-info'
          }
        },
        {
          color: 'warning',
          variant: 'naked',
          class: {
            content: 'text-warning'
          }
        },
        {
          color: 'error',
          variant: 'naked',
          class: {
            content: 'text-error'
          }
        },
        {
          color: 'neutral',
          variant: 'solid',
          class: {
            content: 'bg-inverted text-inverted'
          }
        },
        {
          color: 'neutral',
          variant: 'outline',
          class: {
            content: 'bg-default ring ring-default'
          }
        },
        {
          color: 'neutral',
          variant: 'soft',
          class: {
            content: 'bg-elevated/50'
          }
        },
        {
          color: 'neutral',
          variant: 'subtle',
          class: {
            content: 'bg-elevated/50 ring ring-default'
          }
        }
      ],
      defaultVariants: {
        side: 'left',
        variant: 'naked',
        color: 'neutral'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/ChatMessage.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/chat-message.ts).


# ChatMessages

## Uso

O componente ChatMessages exibe uma lista de componentes [ChatMessage](https://ui.nitro.news/docs/components/chat-message) usando o slot padrão ou a prop `messages`.

```vue {2,8}
<template>
  <NChatMessages>
    <NChatMessage
      v-for="(message, index) in messages"
      :key="index"
      v-bind="message"
    />
  </NChatMessages>
</template>
```

> \[!NOTE]
>
> Este componente foi feito sob medida para chatbots de IA, com recursos como:
>
> - Initial scroll to the bottom upon loading ([`shouldScrollToBottom`](https://ui.nitro.news/#should-scroll-to-bottom)).
> - Continuous scrolling down as new messages arrive ([`shouldAutoScroll`](https://ui.nitro.news/#should-auto-scroll)).
> - An "Auto scroll" button appears when scrolled up, allowing users to jump back to the latest messages ([`autoScroll`](https://ui.nitro.news/#auto-scroll)).
> - A loading indicator displays while the assistant is processing ([`status`](https://ui.nitro.news/#status)).
> - Submitted messages are scrolled to the top of the viewport and the height of the last user message is dynamically adjusted.

### Mensagens

Use a prop `messages` para exibir uma lista de mensagens de chat.

```vue
<script setup lang="ts">
const messages = ref([
  {
    id: "6045235a-a435-46b8-989d-2df38ca2eb47",
    role: "user",
    parts: [
      {
        type: "text",
        text: "Hello, how are you?"
      }
    ]
  },
  {
    id: "7a92b3c1-d5f8-4e76-b8a9-3c1e5fb2e0d8",
    role: "assistant",
    parts: [
      {
        type: "text",
        text: "I am doing well, thank you for asking! How can I assist you today?"
      }
    ]
  },
  {
    id: "9c84d6a7-8b23-4f12-a1d5-e7f3b9c05e2a",
    role: "user",
    parts: [
      {
        type: "text",
        text: "What is the current weather in Tokyo?"
      }
    ]
  },
  {
    id: "b2e5f8c3-a1d9-4e67-b3f2-c9d8e7a6b5f4",
    role: "assistant",
    parts: [
      {
        type: "text",
        text: "Based on the latest data, Tokyo is currently experiencing sunny weather with temperatures around 24°C (75°F). It's a beautiful day with clear skies."
      }
    ]
  }
])
</script>

<template>
  <UChatMessages :messages="messages" />
</template>
```

### Status

Use a prop `status` para exibir um indicador visual quando o assistente está processando.

```vue
<script setup lang="ts">
const messages = ref([
  {
    id: "6045235a-a435-46b8-989d-2df38ca2eb47",
    role: "user",
    parts: [
      {
        type: "text",
        text: "Hello, how are you?"
      }
    ]
  }
])
</script>

<template>
  <UChatMessages status="submitted" :messages="messages" />
</template>
```

> \[!NOTE]
>
> Aqui está o detalhamento dos diferentes status do composable `useChat` do AI SDK:
>
> - `submitted`: The message has been sent to the API and we're awaiting the start of the response stream.
> - `streaming`: The response is actively streaming in from the API, receiving chunks of data.
> - `ready`: The full response has been received and processed; a new user message can be submitted.
> - `error`: An error occurred during the API request, preventing successful completion.

### Usuário

Use a prop `user` para alterar as props do [ChatMessage](https://ui.nitro.news/docs/components/chat-message) para mensagens de `user`. O padrão é:

- `side: 'right'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `variant: 'soft'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

```vue
<script setup lang="ts">
const messages = ref([
  {
    id: "6045235a-a435-46b8-989d-2df38ca2eb47",
    role: "user",
    parts: [
      {
        type: "text",
        text: "Hello, how are you?"
      }
    ]
  },
  {
    id: "7a92b3c1-d5f8-4e76-b8a9-3c1e5fb2e0d8",
    role: "assistant",
    parts: [
      {
        type: "text",
        text: "I am doing well, thank you for asking! How can I assist you today?"
      }
    ]
  },
  {
    id: "9c84d6a7-8b23-4f12-a1d5-e7f3b9c05e2a",
    role: "user",
    parts: [
      {
        type: "text",
        text: "What is the current weather in Tokyo?"
      }
    ]
  },
  {
    id: "b2e5f8c3-a1d9-4e67-b3f2-c9d8e7a6b5f4",
    role: "assistant",
    parts: [
      {
        type: "text",
        text: "Based on the latest data, Tokyo is currently experiencing sunny weather with temperatures around 24°C (75°F). It's a beautiful day with clear skies."
      }
    ]
  }
])
</script>

<template>
  <UChatMessages :user="{
  side: 'left',
  variant: 'solid',
  avatar: {
    src: 'https://github.com/benjamincanac.png',
    loading: 'lazy'
  }
}" :messages="messages" />
</template>
```

### Assistente

Use a prop `assistant` para alterar as props do [ChatMessage](https://ui.nitro.news/docs/components/chat-message) para mensagens de `assistant`. O padrão é:

- `side: 'left'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `variant: 'naked'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

```vue
<script setup lang="ts">
const messages = ref([
  {
    id: "6045235a-a435-46b8-989d-2df38ca2eb47",
    role: "user",
    parts: [
      {
        type: "text",
        text: "Hello, how are you?"
      }
    ]
  },
  {
    id: "7a92b3c1-d5f8-4e76-b8a9-3c1e5fb2e0d8",
    role: "assistant",
    parts: [
      {
        type: "text",
        text: "I am doing well, thank you for asking! How can I assist you today?"
      }
    ]
  },
  {
    id: "9c84d6a7-8b23-4f12-a1d5-e7f3b9c05e2a",
    role: "user",
    parts: [
      {
        type: "text",
        text: "What is the current weather in Tokyo?"
      }
    ]
  },
  {
    id: "b2e5f8c3-a1d9-4e67-b3f2-c9d8e7a6b5f4",
    role: "assistant",
    parts: [
      {
        type: "text",
        text: "Based on the latest data, Tokyo is currently experiencing sunny weather with temperatures around 24°C (75°F). It's a beautiful day with clear skies."
      }
    ]
  }
])
</script>

<template>
  <UChatMessages :assistant="{
  side: 'left',
  variant: 'outline',
  avatar: {
    icon: 'i-lucide-bot'
  },
  actions: [
    {
      label: 'Copy to clipboard',
      icon: 'i-lucide-copy'
    }
  ]
}" :messages="messages" />
</template>
```

### Rolagem automática

Use a prop `auto-scroll` para personalizar ou ocultar o botão de rolagem automática (com o valor `false`) exibido ao rolar para o topo do chat. O padrão é:

- `color: 'neutral'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `variant: 'outline'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Você pode passar qualquer propriedade do componente [Button](https://ui.nitro.news/docs/components/button) para personalizá-lo.

```vue
<script setup lang="ts">
const messages = ref([
  {
    id: "6045235a-a435-46b8-989d-2df38ca2eb47",
    role: "user",
    parts: [
      {
        type: "text",
        text: "Hello, how are you?"
      }
    ]
  },
  {
    id: "7a92b3c1-d5f8-4e76-b8a9-3c1e5fb2e0d8",
    role: "assistant",
    parts: [
      {
        type: "text",
        text: "I am doing well, thank you for asking! How can I assist you today?"
      }
    ]
  },
  {
    id: "9c84d6a7-8b23-4f12-a1d5-e7f3b9c05e2a",
    role: "user",
    parts: [
      {
        type: "text",
        text: "What is the current weather in Tokyo?"
      }
    ]
  },
  {
    id: "b2e5f8c3-a1d9-4e67-b3f2-c9d8e7a6b5f4",
    role: "assistant",
    parts: [
      {
        type: "text",
        text: "Based on the latest data, Tokyo is currently experiencing sunny weather with temperatures around 24°C (75°F). It's a beautiful day with clear skies. The forecast for the rest of the week shows a slight chance of rain on Thursday, with temperatures gradually rising to 28°C by the weekend. Humidity levels are moderate at around 65%, and wind speeds are light at 8 km/h from the southeast. Air quality is good with an index of 42. The UV index is high at 7, so it's recommended to wear sunscreen if you're planning to spend time outdoors. Sunrise was at 5:24 AM and sunset will be at 6:48 PM, giving Tokyo approximately 13 hours and 24 minutes of daylight today. The moon is currently in its waxing gibbous phase."
      }
    ]
  },
  {
    id: "c3e5f8c3-a1d9-4e67-b3f2-c9d8e7a6b5f4",
    role: "user",
    parts: [
      {
        type: "text",
        text: "Can you recommend some popular tourist attractions in Kyoto?"
      }
    ]
  },
  {
    id: "d4f5g8c3-a1d9-4e67-b3f2-c9d8e7a6b5f4",
    role: "assistant",
    parts: [
      {
        type: "text",
        text: "Kyoto is known for its beautiful temples, traditional tea houses, and gardens. Some popular attractions include Kinkaku-ji (Golden Pavilion) with its stunning gold leaf exterior reflecting in the mirror pond, Fushimi Inari Shrine with its thousands of vermilion torii gates winding up the mountainside, Arashiyama Bamboo Grove where towering stalks create an otherworldly atmosphere, Kiyomizu-dera Temple perched on a hillside offering panoramic views of the city, and the historic Gion district where you might spot geisha hurrying to evening appointments through narrow stone-paved streets lined with traditional wooden machiya houses."
      }
    ]
  }
])
</script>

<template>
  <UChatMessages :auto-scroll="{
  color: 'neutral',
  variant: 'outline'
}" :should-scroll-to-bottom="false" :messages="messages" />
</template>
```

### Ícone de rolagem automática

Use a prop `auto-scroll-icon` para personalizar o [Icon](https://ui.nitro.news/docs/components/icon) do botão de rolagem automática. O padrão é `i-lucide-arrow-down`.

```vue
<script setup lang="ts">
const messages = ref([
  {
    id: "6045235a-a435-46b8-989d-2df38ca2eb47",
    role: "user",
    parts: [
      {
        type: "text",
        text: "Hello, how are you?"
      }
    ]
  },
  {
    id: "7a92b3c1-d5f8-4e76-b8a9-3c1e5fb2e0d8",
    role: "assistant",
    parts: [
      {
        type: "text",
        text: "I am doing well, thank you for asking! How can I assist you today?"
      }
    ]
  },
  {
    id: "9c84d6a7-8b23-4f12-a1d5-e7f3b9c05e2a",
    role: "user",
    parts: [
      {
        type: "text",
        text: "What is the current weather in Tokyo?"
      }
    ]
  },
  {
    id: "b2e5f8c3-a1d9-4e67-b3f2-c9d8e7a6b5f4",
    role: "assistant",
    parts: [
      {
        type: "text",
        text: "Based on the latest data, Tokyo is currently experiencing sunny weather with temperatures around 24°C (75°F). It's a beautiful day with clear skies. The forecast for the rest of the week shows a slight chance of rain on Thursday, with temperatures gradually rising to 28°C by the weekend. Humidity levels are moderate at around 65%, and wind speeds are light at 8 km/h from the southeast. Air quality is good with an index of 42. The UV index is high at 7, so it's recommended to wear sunscreen if you're planning to spend time outdoors. Sunrise was at 5:24 AM and sunset will be at 6:48 PM, giving Tokyo approximately 13 hours and 24 minutes of daylight today. The moon is currently in its waxing gibbous phase."
      }
    ]
  },
  {
    id: "c3e5f8c3-a1d9-4e67-b3f2-c9d8e7a6b5f4",
    role: "user",
    parts: [
      {
        type: "text",
        text: "Can you recommend some popular tourist attractions in Kyoto?"
      }
    ]
  },
  {
    id: "d4f5g8c3-a1d9-4e67-b3f2-c9d8e7a6b5f4",
    role: "assistant",
    parts: [
      {
        type: "text",
        text: "Kyoto is known for its beautiful temples, traditional tea houses, and gardens. Some popular attractions include Kinkaku-ji (Golden Pavilion) with its stunning gold leaf exterior reflecting in the mirror pond, Fushimi Inari Shrine with its thousands of vermilion torii gates winding up the mountainside, Arashiyama Bamboo Grove where towering stalks create an otherworldly atmosphere, Kiyomizu-dera Temple perched on a hillside offering panoramic views of the city, and the historic Gion district where you might spot geisha hurrying to evening appointments through narrow stone-paved streets lined with traditional wooden machiya houses."
      }
    ]
  }
])
</script>

<template>
  <UChatMessages auto-scroll-icon="i-lucide-chevron-down" :should-scroll-to-bottom="false" :messages="messages" />
</template>
```

**Nuxt:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/nuxt#theme
>
> Você pode personalizar esse ícone globalmente no seu `app.config.ts` na chave `ui.icons.arrowDown`.

**Vue:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/vue#theme
>
> Você pode personalizar esse ícone globalmente no seu `vite.config.ts` na chave `ui.icons.arrowDown`.

### Rolagem automática

Use a prop `should-auto-scroll` para habilitar/desabilitar a rolagem automática contínua enquanto as mensagens são transmitidas. O padrão é `false`.

```vue
<template>
  <NChatMessages :messages="messages" should-auto-scroll />
</template>
```

### Rolar até o fim

Use a prop `should-scroll-to-bottom` para habilitar/desabilitar a rolagem automática até o fim quando o componente é montado. O padrão é `true`.

```vue
<template>
  <NChatMessages :messages="messages" :should-scroll-to-bottom="false" />
</template>
```

## Exemplos

> \[!TIP]
> See: /docs/components/chat
>
> Confira a página de visão geral do **Chat** para instruções de instalação, configuração do servidor e exemplos de uso.

### Com slot de indicador

Use o slot `#indicator` para personalizar o indicador de carregamento com um efeito [`ChatShimmer`](https://ui.nitro.news/docs/components/chat-shimmer).

::component-example
---
collapse: true
class: overflow-y-auto
name: chat-messages-indicator-slot-example
---
::

## API

### Props

```ts
/**
 * Props for the ChatMessages component
 */
interface ChatMessagesProps {
  messages?: T | undefined;
  status?: ChatStatus | undefined;
  /**
   * Whether to automatically scroll to the bottom when a message is streaming.
   * @default "false"
   */
  shouldAutoScroll?: boolean | undefined;
  /**
   * Whether to scroll to the bottom on mounted.
   * @default "true"
   */
  shouldScrollToBottom?: boolean | undefined;
  /**
   * Display an auto scroll button.
   * `{ size: 'md', color: 'neutral', variant: 'outline' }`{lang="ts-type"}
   * @default "true"
   */
  autoScroll?: boolean | Omit<ButtonProps, LinkPropsKeys> | undefined;
  /**
   * The icon displayed in the auto scroll button.
   */
  autoScrollIcon?: any;
  /**
   * The `user` messages props.
   * `{ side: 'right', variant: 'soft' }`{lang="ts-type"}
   */
  user?: Pick<PropsBase<T>, "actions" | "ui" | "variant" | "icon" | "avatar" | "side"> | undefined;
  /**
   * The `assistant` messages props.
   * `{ side: 'left', variant: 'naked' }`{lang="ts-type"}
   */
  assistant?: Pick<PropsBase<T>, "actions" | "ui" | "variant" | "icon" | "avatar" | "side"> | undefined;
  /**
   * Render the messages in a compact style.
   * This is done automatically when used inside a `UChatPalette`{lang="ts-type"}.
   */
  compact?: boolean | undefined;
  /**
   * The spacing offset for the last message in px. Can be useful when the prompt is sticky for example.
   * @default "0"
   */
  spacingOffset?: number | undefined;
  ui?: { root?: SlotClass; indicator?: SlotClass; viewport?: SlotClass; autoScroll?: SlotClass; } | undefined;
}
```

### Slots

```ts
/**
 * Slots for the ChatMessages component
 */
interface ChatMessagesSlots {
  default(): any;
  indicator(): any;
  viewport(): any;
  header(): any;
  leading(): any;
  files(): any;
  body(): any;
  content(): any;
  actions(): any;
}
```

> \[!TIP]
>
> Você pode usar todos os slots do componente [`ChatMessage`](https://ui.nitro.news/docs/components/chat-message#slots) dentro do ChatMessages; eles são repassados automaticamente, permitindo personalizar mensagens individuais ao usar a prop `messages`.
>
> ```vue {7-15}
> <script setup lang="ts">
> import { isTextUIPart } from 'ai'
> </script>
>
> <template>
>   <NChatMessages :messages="messages" :status="status">
>     <template #content="{ message }">
>       <template
>         v-for="(part, index) in message.parts"
>         :key="`${message.id}-${part.type}-${index}`"
>       >
>         <p v-if="isTextUIPart(part)" class="whitespace-pre-wrap">
>           {{ part.text }}
>         </p>
>       </template>
>     </template>
>   </NChatMessages>
> </template>
> ```

### Expose

Ao acessar o componente por meio de um template ref, você pode usar o seguinte:

| Name                                                                                                                                                                                          | Type                                                                                                                       |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `registerMessageRef(id: string, element: ComponentPublicInstance | null)`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | `void`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} |

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    chatMessages: {
      slots: {
        root: 'w-full flex flex-col gap-1 flex-1 px-2.5 [&>article]:last-of-type:min-h-(--last-message-height)',
        indicator: 'h-6 flex items-center gap-1 py-3 *:size-2 *:rounded-full *:bg-elevated [&>*:nth-child(1)]:animate-[bounce_1s_infinite] [&>*:nth-child(2)]:animate-[bounce_1s_0.15s_infinite] [&>*:nth-child(3)]:animate-[bounce_1s_0.3s_infinite]',
        viewport: 'absolute inset-x-0 top-[86%] data-[state=open]:animate-[fade-in_200ms_ease-out] data-[state=closed]:animate-[fade-out_200ms_ease-in]',
        autoScroll: 'rounded-full absolute right-1/2 translate-x-1/2 bottom-0'
      },
      variants: {
        compact: {
          true: '',
          false: ''
        }
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/ChatMessages.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/chat-messages.ts).


# ChatPalette

## Uso

O componente ChatPalette é um wrapper de layout estruturado que organiza o [ChatMessages](https://ui.nitro.news/docs/components/chat-messages) em uma área de conteúdo rolável e o [ChatPrompt](https://ui.nitro.news/docs/components/chat-prompt) em uma seção inferior fixa, criando interfaces de chatbot coesas para modais, slideovers ou gavetas.

```vue {2,8}
<template>
  <NChatPalette>
    <NChatMessages />

    <template #prompt>
      <NChatPrompt />
    </template>
  </NChatPalette>
</template>
```

## Exemplos

> \[!TIP]
> See: /docs/components/chat
>
> Confira a página de visão geral do **Chat** para instruções de instalação, configuração do servidor e exemplos de uso.

### Dentro de um Modal

Você pode usar o componente ChatPalette dentro do conteúdo de um [Modal](https://ui.nitro.news/docs/components/modal).

::component-example
---
collapse: true
iframe:
  height: 500px;
iframeMobile: true
overflowHidden: true
name: chat-palette-modal-example
---
::

### Dentro do ContentSearch

Você pode usar o componente ChatPalette condicionalmente dentro do conteúdo do [ContentSearch](https://ui.nitro.news/docs/components/content-search) para exibir uma interface de chatbot quando um usuário seleciona um item.

::component-example
---
collapse: true
iframe:
  height: 500px;
iframeMobile: true
overflowHidden: true
name: chat-palette-content-search-example
---
::

## API

### Props

```ts
/**
 * Props for the ChatPalette component
 */
interface ChatPaletteProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  ui?: { root?: SlotClass; prompt?: SlotClass; close?: SlotClass; content?: SlotClass; } | undefined;
}
```

### Slots

```ts
/**
 * Slots for the ChatPalette component
 */
interface ChatPaletteSlots {
  default(): any;
  prompt(): any;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    chatPalette: {
      slots: {
        root: 'relative flex-1 flex flex-col min-h-0 min-w-0',
        prompt: 'px-0 rounded-t-none border-t border-default',
        close: '',
        content: 'overflow-y-auto flex-1 flex flex-col py-3'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/ChatPalette.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/chat-palette.ts).


# ChatPrompt

## Uso

O componente ChatPrompt renderiza um elemento `<form>` e estende o componente [Textarea](https://ui.nitro.news/docs/components/textarea), então você pode passar qualquer propriedade como `icon`, `placeholder`, `autofocus`, etc.

::component-example{collapse name="chat-prompt-example"}
::

> \[!NOTE]
>
> O ChatPrompt trata os seguintes eventos:
>
> - The form is submitted when the user presses :kbd{value="enter"} or when the user clicks on the submit button. Set the `submit-on-enter` prop to `false` to submit with :kbd{value="ctrl"} + :kbd{value="enter"} (or :kbd{value="cmd"} + :kbd{value="enter"} on macOS) instead, allowing :kbd{value="enter"} to insert a newline.
> - The textarea is blurred when :kbd{value="escape"} is pressed and emits a `close` event.

### Variante

Use a prop `variant` para alterar o estilo do prompt. O padrão é `outline`.

```vue
<template>
  <UChatPrompt variant="soft" />
</template>
```

## Exemplos

> \[!TIP]
> See: /docs/components/chat
>
> Confira a página de visão geral do **Chat** para instruções de instalação, configuração do servidor e exemplos de uso.

### Com um Editor `Soon`

Componha os slots `#header`, `#body` e `#footer` para construir um prompt rico: anexos de arquivo, um [Editor](https://ui.nitro.news/docs/components/editor) com menções `@` e comandos `/` por meio do [EditorMentionMenu](https://ui.nitro.news/docs/components/editor-mention-menu), e um seletor de modo.

::component-example{.justify-center collapse name="chat-prompt-editor-example"}
::

> \[!NOTE]
>
> O slot `#body` substitui o textarea interno e expõe os handlers `submit` e `close`, então você pode conectar os atalhos de teclado do editor ao formulário. Quando um menu de menções está aberto, pressionar :kbd{value="enter"} seleciona o item destacado em vez de enviar.

### Como página inicial

Você também pode usá-lo na página inicial da sua interface de chat.

```vue [pages/index.vue] {2,4,8-15,24,26}
<script setup lang="ts">
import { useChat } from '@ai-sdk/vue'

const input = ref('')

const { messages, status, sendMessage } = useChat()

async function onSubmit() {
  sendMessage({ text: input.value })

  // Navigate to chat page after first message
  if (messages.value.length === 1) {
    await navigateTo('/chat')
  }
}
</script>

<template>
  <NDashboardPanel>
    <template #body>
      <NContainer>
        <h1>How can I help you today?</h1>

        <NChatPrompt v-model="input" @submit="onSubmit">
          <NChatPromptSubmit :status="status" />
        </NChatPrompt>
      </NContainer>
    </template>
  </NDashboardPanel>
</template>
```

## API

### Props

```ts
/**
 * Props for the ChatPrompt component
 */
interface ChatPromptProps {
  /**
   * The element or component this component should render as.
   * @default "\"form\""
   */
  as?: any;
  /**
   * The placeholder text for the textarea.
   */
  placeholder?: string | undefined;
  color?: "error" | "primary" | "secondary" | "accent" | "success" | "info" | "warning" | "neutral" | undefined;
  variant?: "outline" | "soft" | "subtle" | "naked" | undefined;
  /**
   * When `true`, pressing `Enter` submits and `Shift+Enter` inserts a newline.
   * When `false`, pressing `Enter` inserts a newline and `Ctrl+Enter` / `Cmd+Enter` submits.
   * @default "true"
   */
  submitOnEnter?: boolean | undefined;
  error?: Error | undefined;
  ui?: ({ root?: SlotClass; header?: SlotClass; body?: SlotClass; footer?: SlotClass; base?: SlotClass; } & { root?: SlotClass; base?: SlotClass; leading?: SlotClass; leadingIcon?: SlotClass; leadingAvatar?: SlotClass; leadingAvatarSize?: SlotClass; trailing?: SlotClass; trailingIcon?: SlotClass; }) | undefined;
  /**
   * @default "1"
   */
  rows?: number | undefined;
  /**
   * @default "true"
   */
  autofocus?: boolean | undefined;
  autofocusDelay?: number | undefined;
  /**
   * @default "true"
   */
  autoresize?: boolean | undefined;
  autoresizeDelay?: number | undefined;
  maxrows?: number | undefined;
  /**
   * Display an icon based on the `leading` and `trailing` props.
   */
  icon?: any;
  /**
   * Display an avatar on the left side.
   */
  avatar?: AvatarProps | undefined;
  /**
   * When `true`, the loading icon will be displayed.
   */
  loading?: boolean | undefined;
  /**
   * The icon when the `loading` prop is `true`.
   */
  loadingIcon?: any;
  disabled?: boolean | undefined;
  /**
   * @default "\"\""
   */
  modelValue?: string | undefined;
}
```

> \[!NOTE]
> See: https\://developer.mozilla.org/en-US/docs/Web/HTML/Element/textarea#attributes
>
> Este componente também suporta todos os atributos HTML nativos de `<textarea>`.

### Slots

```ts
/**
 * Slots for the ChatPrompt component
 */
interface ChatPromptSlots {
  header(): any;
  footer(): any;
  /**
   * Replace the internal textarea, e.g. to render an [Editor](/docs/components/editor) with mentions.
   */
  body(): any;
  leading(): any;
  default(): any;
  trailing(): any;
}
```

### Emits

```ts
/**
 * Emitted events for the ChatPrompt component
 */
interface ChatPromptEmits {
  close: (payload: [event: Event]) => void;
  submit: (payload: [event: Event]) => void;
  update:modelValue: (payload: [value: string]) => void;
}
```

### Expose

Ao acessar o componente por meio de um template ref, você pode usar o seguinte:

| Name                                                                                                                              | Type                                                                                                                                                  |
| --------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `textareaRef`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | `Ref<HTMLTextAreaElement | null>`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} |

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    chatPrompt: {
      slots: {
        root: 'relative flex flex-col items-stretch gap-2 px-2.5 py-2 w-full rounded-lg backdrop-blur',
        header: 'flex items-center gap-1.5',
        body: 'items-start gap-1.5',
        footer: 'flex items-center justify-between gap-1.5',
        base: 'px-0'
      },
      variants: {
        color: {
          primary: '',
          secondary: '',
          accent: '',
          success: '',
          info: '',
          warning: '',
          error: '',
          neutral: ''
        },
        variant: {
          outline: {
            root: 'bg-default/75 ring ring-default'
          },
          soft: {
            root: 'bg-elevated/50'
          },
          subtle: {
            root: 'bg-elevated/50 ring ring-default'
          },
          naked: {
            root: ''
          }
        }
      },
      compoundVariants: [
        {
          color: 'primary',
          variant: [
            'outline',
            'subtle'
          ],
          class: {
            root: 'outline-primary/25 has-[textarea:focus-visible]:outline-3 has-[textarea:focus-visible]:ring-primary has-[[contenteditable]:focus-visible]:outline-3 has-[[contenteditable]:focus-visible]:ring-primary'
          }
        },
        {
          color: 'secondary',
          variant: [
            'outline',
            'subtle'
          ],
          class: {
            root: 'outline-secondary/25 has-[textarea:focus-visible]:outline-3 has-[textarea:focus-visible]:ring-secondary has-[[contenteditable]:focus-visible]:outline-3 has-[[contenteditable]:focus-visible]:ring-secondary'
          }
        },
        {
          color: 'accent',
          variant: [
            'outline',
            'subtle'
          ],
          class: {
            root: 'outline-accent/25 has-[textarea:focus-visible]:outline-3 has-[textarea:focus-visible]:ring-accent has-[[contenteditable]:focus-visible]:outline-3 has-[[contenteditable]:focus-visible]:ring-accent'
          }
        },
        {
          color: 'success',
          variant: [
            'outline',
            'subtle'
          ],
          class: {
            root: 'outline-success/25 has-[textarea:focus-visible]:outline-3 has-[textarea:focus-visible]:ring-success has-[[contenteditable]:focus-visible]:outline-3 has-[[contenteditable]:focus-visible]:ring-success'
          }
        },
        {
          color: 'info',
          variant: [
            'outline',
            'subtle'
          ],
          class: {
            root: 'outline-info/25 has-[textarea:focus-visible]:outline-3 has-[textarea:focus-visible]:ring-info has-[[contenteditable]:focus-visible]:outline-3 has-[[contenteditable]:focus-visible]:ring-info'
          }
        },
        {
          color: 'warning',
          variant: [
            'outline',
            'subtle'
          ],
          class: {
            root: 'outline-warning/25 has-[textarea:focus-visible]:outline-3 has-[textarea:focus-visible]:ring-warning has-[[contenteditable]:focus-visible]:outline-3 has-[[contenteditable]:focus-visible]:ring-warning'
          }
        },
        {
          color: 'error',
          variant: [
            'outline',
            'subtle'
          ],
          class: {
            root: 'outline-error/25 has-[textarea:focus-visible]:outline-3 has-[textarea:focus-visible]:ring-error has-[[contenteditable]:focus-visible]:outline-3 has-[[contenteditable]:focus-visible]:ring-error'
          }
        },
        {
          color: 'primary',
          variant: 'soft',
          class: {
            root: 'outline-primary/25 has-[textarea:focus-visible]:outline-3 has-[[contenteditable]:focus-visible]:outline-3'
          }
        },
        {
          color: 'secondary',
          variant: 'soft',
          class: {
            root: 'outline-secondary/25 has-[textarea:focus-visible]:outline-3 has-[[contenteditable]:focus-visible]:outline-3'
          }
        },
        {
          color: 'accent',
          variant: 'soft',
          class: {
            root: 'outline-accent/25 has-[textarea:focus-visible]:outline-3 has-[[contenteditable]:focus-visible]:outline-3'
          }
        },
        {
          color: 'success',
          variant: 'soft',
          class: {
            root: 'outline-success/25 has-[textarea:focus-visible]:outline-3 has-[[contenteditable]:focus-visible]:outline-3'
          }
        },
        {
          color: 'info',
          variant: 'soft',
          class: {
            root: 'outline-info/25 has-[textarea:focus-visible]:outline-3 has-[[contenteditable]:focus-visible]:outline-3'
          }
        },
        {
          color: 'warning',
          variant: 'soft',
          class: {
            root: 'outline-warning/25 has-[textarea:focus-visible]:outline-3 has-[[contenteditable]:focus-visible]:outline-3'
          }
        },
        {
          color: 'error',
          variant: 'soft',
          class: {
            root: 'outline-error/25 has-[textarea:focus-visible]:outline-3 has-[[contenteditable]:focus-visible]:outline-3'
          }
        },
        {
          color: 'neutral',
          variant: [
            'outline',
            'subtle'
          ],
          class: {
            root: 'outline-inverted/25 has-[textarea:focus-visible]:outline-3 has-[textarea:focus-visible]:ring-inverted has-[[contenteditable]:focus-visible]:outline-3 has-[[contenteditable]:focus-visible]:ring-inverted'
          }
        },
        {
          color: 'neutral',
          variant: 'soft',
          class: {
            root: 'outline-inverted/25 has-[textarea:focus-visible]:outline-3 has-[[contenteditable]:focus-visible]:outline-3'
          }
        }
      ],
      defaultVariants: {
        color: 'primary',
        variant: 'outline'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/ChatPrompt.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/chat-prompt.ts).


# ChatPromptSubmit

## Uso

O componente ChatPromptSubmit é usado dentro do componente [ChatPrompt](https://ui.nitro.news/docs/components/chat-prompt) para enviar o prompt. Ele trata automaticamente os diferentes valores de `status` para controlar o chat.

Ele estende o componente [Button](https://ui.nitro.news/docs/components/button), então você pode passar qualquer propriedade como `color`, `variant`, `size`, etc.

```vue
<template>
  <n-chat-prompt-submit />
  <template v-slot:code=>
  <pre className=language-vue shiki shiki-themes material-theme-lighter material-theme material-theme-palenight code=<template>
    <NChatPrompt>
      <NChatPromptSubmit />
    </NChatPrompt>
  </template>
   language=vue meta= style=>
  <code __ignoreMap=>
  <span class=line>
  <span class=sMK4o>
  <</span>
  <span class=swJcz>
  template</span>
  <span class=sMK4o>
  >
  </span></span>
  <span class=line>
  <span class=sMK4o>
    <</span>
  <span class=swJcz>
  NChatPrompt</span>
  <span class=sMK4o>
  >
  </span></span>
  <span class=line>
  <span class=sMK4o>
      <</span>
  <span class=swJcz>
  NChatPromptSubmit</span>
  <span class=sMK4o>
   />
  </span></span>
  <span class=line>
  <span class=sMK4o>
    </</span>
  <span class=swJcz>
  NChatPrompt</span>
  <span class=sMK4o>
  >
  </span></span>
  <span class=line>
  <span class=sMK4o>
  </</span>
  <span class=swJcz>
  template</span>
  <span class=sMK4o>
  >
  </span></span></code></pre></template>
</template>
```

> \[!NOTE]
>
> Você também pode usá-lo dentro do slot `footer` do componente [`ChatPrompt`](https://ui.nitro.news/docs/components/chat-prompt).

### Pronto

Quando o status dele é `ready`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, use as props `color`, `variant` e `icon` para personalizar o Button. O padrão é:

- `color="primary"`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `variant="solid"`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `icon="i-lucide-arrow-up"`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

```vue
<template>
  <UChatPromptSubmit color="primary" variant="solid" icon="i-lucide-arrow-up" />
</template>
```

**Nuxt:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/nuxt#theme
>
> Você pode personalizar esse ícone globalmente no seu `app.config.ts` na chave `ui.icons.arrowUp`.

**Vue:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/vue#theme
>
> Você pode personalizar esse ícone globalmente no seu `vite.config.ts` na chave `ui.icons.arrowUp`.

### Enviado

Quando o status dele é `submitted`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, use as props `submitted-color`, `submitted-variant` e `submitted-icon` para personalizar o Button. O padrão é:

- `submittedColor="neutral"`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `submittedVariant="subtle"`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `submittedIcon="i-lucide-square"`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

> \[!NOTE]
>
> O evento `stop` é emitido quando o usuário clica no Button.

```vue
<template>
  <UChatPromptSubmit submitted-color="neutral" submitted-variant="subtle" submitted-icon="i-lucide-square" status="submitted" />
</template>
```

**Nuxt:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/nuxt#theme
>
> Você pode personalizar esse ícone globalmente no seu `app.config.ts` na chave `ui.icons.stop`.

**Vue:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/vue#theme
>
> Você pode personalizar esse ícone globalmente no seu `vite.config.ts` na chave `ui.icons.stop`.

### Streaming

Quando o status dele é `streaming`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, use as props `streaming-color`, `streaming-variant` e `streaming-icon` para personalizar o Button. O padrão é:

- `streamingColor="neutral"`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `streamingVariant="subtle"`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `streamingIcon="i-lucide-square"`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

> \[!NOTE]
>
> O evento `stop` é emitido quando o usuário clica no Button.

```vue
<template>
  <UChatPromptSubmit streaming-color="neutral" streaming-variant="subtle" streaming-icon="i-lucide-square" status="streaming" />
</template>
```

**Nuxt:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/nuxt#theme
>
> Você pode personalizar esse ícone globalmente no seu `app.config.ts` na chave `ui.icons.stop`.

**Vue:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/vue#theme
>
> Você pode personalizar esse ícone globalmente no seu `vite.config.ts` na chave `ui.icons.stop`.

### Erro

Quando o status dele é `error`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, use as props `error-color`, `error-variant` e `error-icon` para personalizar o Button. O padrão é:

- `errorColor="error"`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `errorVariant="soft"`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `errorIcon="i-lucide-rotate-ccw"`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

> \[!NOTE]
>
> O evento `reload` é emitido quando o usuário clica no Button.

```vue
<template>
  <UChatPromptSubmit error-color="error" error-variant="soft" error-icon="i-lucide-rotate-ccw" status="error" />
</template>
```

**Nuxt:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/nuxt#theme
>
> Você pode personalizar esse ícone globalmente no seu `app.config.ts` na chave `ui.icons.reload`.

**Vue:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/vue#theme
>
> Você pode personalizar esse ícone globalmente no seu `vite.config.ts` na chave `ui.icons.reload`.

## Exemplos

> \[!TIP]
> See: /docs/components/chat
>
> Confira a página de visão geral do **Chat** para instruções de instalação, configuração do servidor e exemplos de uso.

## API

### Props

```ts
/**
 * Props for the ChatPromptSubmit component
 */
interface ChatPromptSubmitProps {
  /**
   * @default "\"ready\""
   */
  status?: ChatStatus | undefined;
  /**
   * The icon displayed in the button when the status is `ready`. Set to `false` to hide the icon.
   */
  icon?: any;
  /**
   * The color of the button when the status is `ready`.
   */
  color?: "error" | "primary" | "secondary" | "accent" | "success" | "info" | "warning" | "neutral" | undefined;
  /**
   * The variant of the button when the status is `ready`.
   */
  variant?: "link" | "outline" | "soft" | "subtle" | "ghost" | "solid" | undefined;
  /**
   * The icon displayed in the button when the status is `streaming`.
   */
  streamingIcon?: any;
  /**
   * The color of the button when the status is `streaming`.
   * @default "\"neutral\""
   */
  streamingColor?: "error" | "primary" | "secondary" | "accent" | "success" | "info" | "warning" | "neutral" | undefined;
  /**
   * The variant of the button when the status is `streaming`.
   * @default "\"subtle\""
   */
  streamingVariant?: "link" | "outline" | "soft" | "subtle" | "ghost" | "solid" | undefined;
  /**
   * The icon displayed in the button when the status is `submitted`.
   */
  submittedIcon?: any;
  /**
   * The color of the button when the status is `submitted`.
   * @default "\"neutral\""
   */
  submittedColor?: "error" | "primary" | "secondary" | "accent" | "success" | "info" | "warning" | "neutral" | undefined;
  /**
   * The variant of the button when the status is `submitted`.
   * @default "\"subtle\""
   */
  submittedVariant?: "link" | "outline" | "soft" | "subtle" | "ghost" | "solid" | undefined;
  /**
   * The icon displayed in the button when the status is `error`.
   */
  errorIcon?: any;
  /**
   * The color of the button when the status is `error`.
   * @default "\"error\""
   */
  errorColor?: "error" | "primary" | "secondary" | "accent" | "success" | "info" | "warning" | "neutral" | undefined;
  /**
   * The variant of the button when the status is `error`.
   * @default "\"soft\""
   */
  errorVariant?: "link" | "outline" | "soft" | "subtle" | "ghost" | "solid" | undefined;
  ui?: ({ base?: SlotClass; } & { base?: SlotClass; label?: SlotClass; leadingIcon?: SlotClass; leadingAvatar?: SlotClass; leadingAvatarSize?: SlotClass; trailingIcon?: SlotClass; }) | undefined;
  autofocus?: Booleanish | undefined;
  /**
   * Display an avatar on the left side.
   */
  avatar?: AvatarProps | undefined;
  /**
   * When `true`, the loading icon will be displayed.
   */
  loading?: boolean | undefined;
  /**
   * The icon when the `loading` prop is `true`.
   */
  loadingIcon?: any;
  disabled?: boolean | undefined;
  form?: string | undefined;
  name?: string | undefined;
  onClick?: ((event: MouseEvent) => void) | ((event: MouseEvent) => void)[] | undefined;
  /**
   * The element or component this component should render as when not a link.
   */
  as?: any;
  label?: string | undefined;
  size?: "xs" | "sm" | "md" | "lg" | "xl" | undefined;
  /**
   * When `true`, the icon will be displayed on the left side.
   */
  leading?: boolean | undefined;
  /**
   * Display an icon on the left side.
   */
  leadingIcon?: any;
  /**
   * When `true`, the icon will be displayed on the right side.
   */
  trailing?: boolean | undefined;
  /**
   * Display an icon on the right side.
   */
  trailingIcon?: any;
  /**
   * The type of the button when not a link.
   */
  type?: "reset" | "submit" | "button" | undefined;
  /**
   * Class to apply when the link is exact active
   */
  exactActiveClass?: string | undefined;
  /**
   * Pass the returned promise of `router.push()` to `document.startViewTransition()` if supported.
   */
  viewTransition?: boolean | undefined;
  formaction?: string | undefined;
  formenctype?: string | undefined;
  formmethod?: string | undefined;
  formnovalidate?: Booleanish | undefined;
  formtarget?: string | undefined;
  activeColor?: "error" | "primary" | "secondary" | "accent" | "success" | "info" | "warning" | "neutral" | undefined;
  activeVariant?: "link" | "outline" | "soft" | "subtle" | "ghost" | "solid" | undefined;
  /**
   * Render the button with equal padding on all sides.
   */
  square?: boolean | undefined;
  /**
   * Render the button full width.
   */
  block?: boolean | undefined;
  /**
   * Set loading state automatically based on the `@click` promise state
   */
  loadingAuto?: boolean | undefined;
}
```

> \[!NOTE]
> See: https\://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attributes
>
> Este componente também suporta todos os atributos HTML nativos de `<button>`.

### Slots

```ts
/**
 * Slots for the ChatPromptSubmit component
 */
interface ChatPromptSubmitSlots {
  leading(): any;
  default(): any;
  trailing(): any;
}
```

### Emits

```ts
/**
 * Emitted events for the ChatPromptSubmit component
 */
interface ChatPromptSubmitEmits {
  stop: (payload: [event: MouseEvent]) => void;
  reload: (payload: [event: MouseEvent]) => void;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    chatPromptSubmit: {
      slots: {
        base: ''
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/ChatPromptSubmit.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/chat-prompt-submit.ts).


# ChatReasoning

## Uso

O componente ChatReasoning renderiza um bloco recolhível que exibe o conteúdo de raciocínio ou pensamento da IA. Ele abre automaticamente durante o streaming e fecha automaticamente depois.

::component-example
---
collapse: true
prettier: true
class: h-[252px]
name: chat-reasoning-example
---
::

> \[!NOTE]
> See: /docs/composables/use-scroll-shadow
>
> O conteúdo do corpo usa o composable `useScrollShadow` para aplicar sombras de esmaecimento quando há transbordamento.

### Texto

Use a prop `text` para definir o conteúdo do raciocínio. O texto é exibido dentro do corpo recolhível.

```vue
<template>
  <UChatReasoning text="The user is asking about Vue components..." />
</template>
```

### Streaming

Use a prop `streaming` para indicar um raciocínio ativo. O componente abre automaticamente quando o streaming começa e fecha automaticamente quando ele termina.

```vue
<template>
  <UChatReasoning streaming text="The user is asking about Vue components..." />
</template>
```

> \[!TIP]
>
> Use o utilitário `isPartStreaming` de `@nitro/ui/utils/ai` para determinar se um part está sendo transmitido no momento.

### Shimmer

Durante o streaming, o rótulo do gatilho usa o componente [`ChatShimmer`](https://ui.nitro.news/docs/components/chat-shimmer). Use a prop `shimmer` para personalizar sua `duration` e seu `spread`.

```vue
<template>
  <UChatReasoning streaming text="The user is asking about Vue components..." :shimmer="{
  duration: 2,
  spread: 2
}" />
</template>
```

### Ícone

Use a prop `icon` para exibir um componente [Icon](https://ui.nitro.news/docs/components/icon) ao lado do gatilho.

```vue
<template>
  <UChatReasoning icon="i-lucide-brain" text="The user is asking about Vue components..." />
</template>
```

### Chevron

Use a prop `chevron` para alterar a posição do ícone de chevron.

> \[!NOTE]
>
> Quando `chevron` é definido como `leading` com um `icon`, o ícone troca de lugar com o chevron no hover e quando aberto.

```vue
<template>
  <UChatReasoning chevron="leading" icon="i-lucide-brain" text="The user is asking about Vue components..." />
</template>
```

### Ícone de chevron

Use a prop `chevron-icon` para personalizar o [Icon](https://ui.nitro.news/docs/components/icon) de chevron. O padrão é `i-lucide-chevron-down`.

```vue
<template>
  <UChatReasoning chevron-icon="i-lucide-arrow-down" text="The user is asking about Vue components..." />
</template>
```

**Nuxt:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/nuxt#theme
>
> Você pode personalizar esse ícone globalmente no seu `app.config.ts` na chave `ui.icons.chevronDown`.

**Vue:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/vue#theme
>
> Você pode personalizar esse ícone globalmente no seu `vite.config.ts` na chave `ui.icons.chevronDown`.

## Exemplos

> \[!TIP]
> See: /docs/components/chat
>
> Confira a página de visão geral do **Chat** para instruções de instalação, configuração do servidor e exemplos de uso.

## API

### Props

```ts
/**
 * Props for the ChatReasoning component
 */
interface ChatReasoningProps {
  /**
   * The reasoning text content to display.
   */
  text?: string | undefined;
  /**
   * Whether the reasoning content is currently streaming.
   * @default "false"
   */
  streaming?: boolean | undefined;
  /**
   * The duration in seconds that the AI spent reasoning.
   * If not provided, it will be calculated automatically based on streaming time.
   */
  duration?: number | undefined;
  /**
   * The icon displayed next to the trigger.
   */
  icon?: any;
  /**
   * The position of the chevron icon.
   * @default "\"trailing\""
   */
  chevron?: "leading" | "trailing" | undefined;
  /**
   * The icon displayed as the chevron.
   */
  chevronIcon?: any;
  /**
   * The delay in milliseconds before auto-closing when streaming ends.
   * Set to `0` to disable auto-close.
   * @default "500"
   */
  autoCloseDelay?: number | undefined;
  /**
   * Customize the [`ChatShimmer`](https://ui.nitro.news/docs/components/chat-shimmer) component when streaming.
   */
  shimmer?: Partial<Omit<ChatShimmerProps, "text">> | undefined;
  ui?: { root?: SlotClass; trigger?: SlotClass; leading?: SlotClass; leadingIcon?: SlotClass; chevronIcon?: SlotClass; label?: SlotClass; trailingIcon?: SlotClass; content?: SlotClass; body?: SlotClass; } | undefined;
  /**
   * When `true`, prevents the user from interacting with the collapsible.
   */
  disabled?: boolean | undefined;
  /**
   * The controlled open state of the collapsible. Can be binded with `v-model`.
   * @default "undefined"
   */
  open?: boolean | undefined;
  /**
   * The open state of the collapsible when it is initially rendered. <br> Use when you do not need to control its open state.
   */
  defaultOpen?: boolean | undefined;
  /**
   * When `true`, the element will be unmounted on closed state.
   * @default "false"
   */
  unmountOnHide?: boolean | undefined;
}
```

### Slots

```ts
/**
 * Slots for the ChatReasoning component
 */
interface ChatReasoningSlots {
  default(): any;
}
```

### Emits

```ts
/**
 * Emitted events for the ChatReasoning component
 */
interface ChatReasoningEmits {
  update:open: (payload: [value: boolean]) => void;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    chatReasoning: {
      slots: {
        root: '',
        trigger: [
          'group flex w-full items-center gap-1.5 text-muted text-sm disabled:cursor-default disabled:hover:text-muted hover:text-default rounded-sm outline-primary/25 focus-visible:outline-3 min-w-0',
          'transition-colors'
        ],
        leading: 'relative size-4 shrink-0',
        leadingIcon: 'size-4 shrink-0',
        chevronIcon: 'size-4 shrink-0 group-data-[state=open]:rotate-180 transition-transform duration-200',
        label: 'truncate',
        trailingIcon: 'size-4 shrink-0 group-data-[state=open]:rotate-180 transition-transform duration-200',
        content: 'data-[state=open]:animate-[collapsible-down_200ms_ease-out] data-[state=closed]:animate-[collapsible-up_200ms_ease-out] data-[state=closed]:overflow-hidden rounded-sm outline-primary/25 has-focus-visible:outline-3',
        body: 'max-h-[200px] pt-2 overflow-y-auto text-sm text-dimmed whitespace-pre-wrap focus:outline-none'
      },
      variants: {
        chevron: {
          leading: {
            leadingIcon: 'group-hover:opacity-0'
          },
          trailing: ''
        },
        alone: {
          false: {
            leadingIcon: [
              'absolute inset-0 group-data-[state=open]:opacity-0',
              'transition-opacity duration-200'
            ],
            chevronIcon: [
              'absolute inset-0 opacity-0 group-hover:opacity-100 group-data-[state=open]:opacity-100',
              'transition-[rotate,opacity] duration-200'
            ]
          }
        }
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/ChatReasoning.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/chat-reasoning.ts).


# ChatShimmer

## Uso

O componente ChatShimmer renderiza um elemento com um gradiente shimmer animado sobre o texto, comumente usado para indicar estados de streaming ou carregamento em interfaces de chat.

> \[!NOTE]
>
> Este componente é usado automaticamente pelos componentes [`ChatTool`](https://ui.nitro.news/docs/components/chat-tool) e [`ChatReasoning`](https://ui.nitro.news/docs/components/chat-reasoning) durante o streaming.

### Texto

Use a prop `text` para definir o texto do shimmer.

```vue
<template>
  <UChatShimmer text="Thinking..." />
</template>
```

### Duração

Use a prop `duration` para controlar a velocidade da animação em segundos.

```vue
<template>
  <UChatShimmer text="Thinking..." :duration="4" />
</template>
```

### Espalhamento

Use a prop `spread` para controlar a largura do destaque do shimmer. O spread real é calculado como `text.length * spread` em pixels.

```vue
<template>
  <UChatShimmer text="Thinking..." :spread="5" />
</template>
```

## Exemplos

> \[!TIP]
> See: /docs/components/chat
>
> Confira a página de visão geral do **Chat** para instruções de instalação, configuração do servidor e exemplos de uso.

## API

### Props

```ts
/**
 * Props for the ChatShimmer component
 */
interface ChatShimmerProps {
  /**
   * The text to display with the shimmer effect.
   */
  text: string;
  /**
   * The element or component this component should render as.
   * @default "\"span\""
   */
  as?: any;
  /**
   * The duration of the shimmer animation in seconds.
   * @default "2"
   */
  duration?: number | undefined;
  /**
   * The spread multiplier for the shimmer highlight. The actual spread is computed as `text.length * spread` in pixels.
   * @default "2"
   */
  spread?: number | undefined;
  ui?: {} | undefined;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    chatShimmer: {
      base: 'text-transparent bg-clip-text bg-no-repeat bg-size-[calc(200%+var(--spread)*2+2px)_100%,auto] bg-[image:linear-gradient(90deg,#0000_calc(50%-var(--spread)),var(--ui-text-highlighted),#0000_calc(50%+var(--spread))),linear-gradient(var(--ui-text-muted),var(--ui-text-muted))] animate-[shimmer_var(--duration)_linear_infinite] rtl:animate-[shimmer-rtl_var(--duration)_linear_infinite] will-change-[background-position]'
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/ChatShimmer.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/chat-shimmer.ts).


# ChatTool

## Uso

O componente ChatTool renderiza um bloco recolhível que exibe o status de invocação de ferramentas de IA, como "Buscando componentes" ou "Lendo documentação". Quando um slot padrão é fornecido, ele se torna recolhível para revelar a saída da ferramenta.

::component-example{collapse prettier name="chat-tool-example"}
::

### Texto

Use a prop `text` para definir o texto de status da ferramenta.

```vue
<template>
  <UChatTool text="Searched components" />
</template>
```

### Sufixo

Use a prop `suffix` para exibir um texto secundário após o rótulo principal.

```vue
<template>
  <UChatTool text="Reading component" suffix="Button" />
</template>
```

### Streaming

Use a prop `streaming` para indicar que a ferramenta está em execução. O texto exibe uma animação shimmer.

```vue
<template>
  <UChatTool streaming text="Searching components..." />
</template>
```

> \[!TIP]
>
> Use o utilitário `isToolStreaming` de `@nitro/ui/utils/ai` para determinar se um tool part ainda está em execução. Ele retorna `false` quando a ferramenta está aguardando uma aprovação do usuário.

### Shimmer

Durante o streaming, o rótulo do gatilho usa o componente [`ChatShimmer`](https://ui.nitro.news/docs/components/chat-shimmer). Use a prop `shimmer` para personalizar sua `duration` e seu `spread`.

```vue
<template>
  <UChatTool streaming text="Searching components..." :shimmer="{
  duration: 2,
  spread: 2
}" />
</template>
```

### Ícone

Use a prop `icon` para exibir um componente [Icon](https://ui.nitro.news/docs/components/icon) ao lado do gatilho.

```vue
<template>
  <UChatTool icon="i-lucide-search" text="Searched components" />
</template>
```

### Carregando

Use a prop `loading` para exibir um indicador de carregamento. Use a prop `loading-icon` para personalizar o ícone de carregamento.

```vue
<template>
  <UChatTool loading text="Searching components..." />
</template>
```

### Ícone de carregamento

Use a prop `loading-icon` para personalizar o ícone de carregamento. O padrão é `i-lucide-loader-circle`.

```vue
<template>
  <UChatTool loading loading-icon="i-lucide-loader" text="Searching components..." />
</template>
```

**Nuxt:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/nuxt#theme
>
> Você pode personalizar esse ícone globalmente no seu `app.config.ts` na chave `ui.icons.loading`.

**Vue:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/vue#theme
>
> Você pode personalizar esse ícone globalmente no seu `vite.config.ts` na chave `ui.icons.loading`.

### Chevron

Use a prop `chevron` para alterar a posição do ícone de chevron.

> \[!NOTE]
>
> Quando `chevron` é definido como `leading` com um `icon`, o ícone troca de lugar com o chevron no hover e quando aberto.

```vue
<template>
  <UChatTool chevron="leading" icon="i-lucide-search" text="Searched components">
    Tool output content
  </UChatTool>
</template>
```

### Ícone de chevron

Use a prop `chevron-icon` para personalizar o [Icon](https://ui.nitro.news/docs/components/icon) de chevron. O padrão é `i-lucide-chevron-down`.

```vue
<template>
  <UChatTool chevron-icon="i-lucide-arrow-down" text="Searched components">
    Tool output content
  </UChatTool>
</template>
```

**Nuxt:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/nuxt#theme
>
> Você pode personalizar esse ícone globalmente no seu `app.config.ts` na chave `ui.icons.chevronDown`.

**Vue:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/vue#theme
>
> Você pode personalizar esse ícone globalmente no seu `vite.config.ts` na chave `ui.icons.chevronDown`.

### Variante

Use a prop `variant` para alterar o estilo visual. O padrão é `inline`.

```vue
<template>
  <UChatTool variant="card" text="Searched components" icon="i-lucide-search" chevron="trailing">
    Tool output content
  </UChatTool>
</template>
```

### Ações `Soon`

Use a prop `actions` para exibir uma lista de [Button](https://ui.nitro.news/docs/components/button) abaixo do gatilho, útil para ferramentas que exigem uma confirmação do usuário antes de executar.

```vue
<template>
  <UChatTool :actions="[
  {
    label: 'Approve'
  },
  {
    label: 'Deny',
    color: 'neutral',
    variant: 'soft'
  }
]" text="Run terminal command" variant="card" icon="i-lucide-terminal">
    $ pnpm run lint
  </UChatTool>
</template>
```

## Exemplos

> \[!TIP]
> See: /docs/components/chat
>
> Confira a página de visão geral do **Chat** para instruções de instalação, configuração do servidor e exemplos de uso.

### Com fluxo de aprovação `Soon`

Use a prop `actions` para construir um fluxo de aprovação de ferramenta com o [AI SDK](https://ai-sdk.dev/docs/agents/tool-approvals){rel="&#x22;nofollow&#x22;"}. Quando um tool part está no estado `approval-requested`, exiba as ações de aprovar e negar e responda com `addToolApprovalResponse`.

::component-example{collapse prettier name="chat-tool-approval-example"}
::

> \[!TIP]
>
> Use o utilitário `isToolApprovalPending` de `@nitro/ui/utils/ai` para detectar uma aprovação pendente; `isToolStreaming` retorna `false` nesse estado.
>
> ```vue
> <script setup lang="ts">
> import { useChat } from '@ai-sdk/vue'
> import { lastAssistantMessageIsCompleteWithApprovalResponses } from 'ai'
>
> const { messages, addToolApprovalResponse } = useChat({
>   sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithApprovalResponses
> })
> </script>
>
> <template>
>   <NChatTool
>     v-if="isToolUIPart(part)"
>     :text="getToolName(part)"
>     :streaming="isToolStreaming(part)"
>     :actions="part.state === 'approval-requested' ? [
>       { label: 'Approve', onClick: () => addToolApprovalResponse({ id: part.approval.id, approved: true }) },
>       { label: 'Deny', color: 'neutral', variant: 'ghost', onClick: () => addToolApprovalResponse({ id: part.approval.id, approved: false }) }
>     ] : undefined"
>   />
> </template>
> ```

## API

### Props

```ts
/**
 * Props for the ChatTool component
 */
interface ChatToolProps {
  /**
   * The text content to display.
   */
  text?: string | undefined;
  /**
   * The suffix text displayed after the main text.
   */
  suffix?: string | undefined;
  /**
   * The icon displayed next to the trigger.
   */
  icon?: any;
  /**
   * Whether the tool is in a loading state.
   * @default "false"
   */
  loading?: boolean | undefined;
  /**
   * The icon displayed when loading.
   */
  loadingIcon?: any;
  /**
   * Whether the tool content is currently streaming.
   * @default "false"
   */
  streaming?: boolean | undefined;
  /**
   * The visual variant of the tool display.
   * @default "\"inline\""
   */
  variant?: "inline" | "card" | undefined;
  /**
   * The position of the chevron icon.
   * @default "\"trailing\""
   */
  chevron?: "leading" | "trailing" | undefined;
  /**
   * The icon displayed as the chevron.
   */
  chevronIcon?: any;
  /**
   * Customize the [`ChatShimmer`](https://ui.nitro.news/docs/components/chat-shimmer) component when streaming.
   */
  shimmer?: Partial<Omit<ChatShimmerProps, "text">> | undefined;
  /**
   * Display a list of actions below the trigger, useful for tool approval flows.
   * `{ size: 'xs' }`{lang="ts-type"}
   */
  actions?: ButtonProps[] | undefined;
  ui?: { root?: SlotClass; trigger?: SlotClass; leading?: SlotClass; leadingIcon?: SlotClass; chevronIcon?: SlotClass; label?: SlotClass; suffix?: SlotClass; trailingIcon?: SlotClass; content?: SlotClass; body?: SlotClass; actions?: SlotClass; } | undefined;
  /**
   * When `true`, prevents the user from interacting with the collapsible.
   */
  disabled?: boolean | undefined;
  /**
   * The controlled open state of the collapsible. Can be binded with `v-model`.
   * @default "undefined"
   */
  open?: boolean | undefined;
  /**
   * The open state of the collapsible when it is initially rendered. <br> Use when you do not need to control its open state.
   */
  defaultOpen?: boolean | undefined;
  /**
   * When `true`, the element will be unmounted on closed state.
   * @default "false"
   */
  unmountOnHide?: boolean | undefined;
}
```

### Slots

```ts
/**
 * Slots for the ChatTool component
 */
interface ChatToolSlots {
  default(): any;
  actions(): any;
}
```

### Emits

```ts
/**
 * Emitted events for the ChatTool component
 */
interface ChatToolEmits {
  update:open: (payload: [value: boolean]) => void;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    chatTool: {
      slots: {
        root: '',
        trigger: [
          'group flex w-full items-center gap-1.5 text-muted text-sm disabled:cursor-default disabled:hover:text-muted hover:text-default min-w-0',
          'transition-colors'
        ],
        leading: 'relative size-4 shrink-0',
        leadingIcon: 'size-4 shrink-0',
        chevronIcon: 'size-4 shrink-0 group-data-[state=open]:rotate-180 transition-transform duration-200',
        label: 'truncate',
        suffix: 'text-dimmed ms-1',
        trailingIcon: 'size-4 shrink-0 group-data-[state=open]:rotate-180 transition-transform duration-200',
        content: 'data-[state=open]:animate-[collapsible-down_200ms_ease-out] data-[state=closed]:animate-[collapsible-up_200ms_ease-out] data-[state=closed]:overflow-hidden',
        body: 'text-sm text-dimmed whitespace-pre-wrap',
        actions: 'flex items-center justify-end gap-1.5'
      },
      variants: {
        variant: {
          inline: {
            trigger: 'rounded-sm outline-primary/25 focus-visible:outline-3',
            body: 'pt-2',
            actions: 'pt-2'
          },
          card: {
            root: 'rounded-md ring ring-default overflow-hidden outline-primary/25 has-focus-visible:outline-3 has-focus-visible:ring-primary',
            trigger: 'px-2 py-1 focus:outline-none',
            trailingIcon: 'ms-auto',
            body: 'border-t border-default p-2 max-h-[200px] overflow-y-auto focus:outline-none',
            actions: 'border-t border-default p-2'
          }
        },
        chevron: {
          leading: '',
          trailing: ''
        },
        loading: {
          true: {
            leadingIcon: 'animate-spin'
          }
        },
        alone: {
          false: {
            leadingIcon: [
              'absolute inset-0 group-hover:opacity-0 group-data-[state=open]:opacity-0',
              'transition-opacity duration-200'
            ],
            chevronIcon: [
              'absolute inset-0 opacity-0 group-hover:opacity-100 group-data-[state=open]:opacity-100',
              'transition-[rotate,opacity] duration-200'
            ]
          }
        }
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/ChatTool.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/chat-tool.ts).


# Checkbox

## Uso

Use a diretiva `v-model` para controlar o estado marcado do Checkbox.

```vue
<script setup lang="ts">
const value = ref(true)
</script>

<template>
  <UCheckbox v-model="value" />
</template>
```

Use a prop `default-value` para definir o valor inicial quando você não precisa controlar o estado.

```vue
<template>
  <UCheckbox default-value />
</template>
```

### Indeterminado

Use o valor `indeterminate` na diretiva `v-model` ou na prop `default-value` para colocar o Checkbox em um [estado indeterminado](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox#indeterminate_state_checkboxes){rel="&#x22;nofollow&#x22;"}.

```vue
<template>
  <UCheckbox default-value="indeterminate" />
</template>
```

### Ícone de indeterminado

Use a prop `indeterminate-icon` para personalizar o ícone de indeterminado. O padrão é `i-lucide-minus`.

```vue
<template>
  <UCheckbox default-value="indeterminate" indeterminate-icon="i-lucide-plus" />
</template>
```

**Nuxt:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/nuxt#theme
>
> Você pode personalizar esse ícone globalmente no seu `app.config.ts` na chave `ui.icons.minus`.

**Vue:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/vue#theme
>
> Você pode personalizar esse ícone globalmente no seu `vite.config.ts` na chave `ui.icons.minus`.

### Label

Use a prop `label` para definir o rótulo do Checkbox.

```vue
<template>
  <UCheckbox label="Check me" />
</template>
```

Ao usar a prop `required`, um asterisco é adicionado ao lado do rótulo.

```vue
<template>
  <UCheckbox required label="Check me" />
</template>
```

### Descrição

Use a prop `description` para definir a descrição do Checkbox.

```vue
<template>
  <UCheckbox label="Check me" description="This is a checkbox." />
</template>
```

### Ícone

Use a prop `icon` para definir o ícone do Checkbox quando ele está marcado. O padrão é `i-lucide-check`.

```vue
<template>
  <UCheckbox icon="i-lucide-heart" default-value label="Check me" />
</template>
```

**Nuxt:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/nuxt#theme
>
> Você pode personalizar esse ícone globalmente no seu `app.config.ts` na chave `ui.icons.check`.

**Vue:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/vue#theme
>
> Você pode personalizar esse ícone globalmente no seu `vite.config.ts` na chave `ui.icons.check`.

### Cor

Use a prop `color` para alterar a cor do Checkbox.

```vue
<template>
  <UCheckbox color="neutral" default-value label="Check me" />
</template>
```

### Variante

Use a prop `variant` para alterar a variante do Checkbox.

```vue
<template>
  <UCheckbox color="primary" variant="card" default-value label="Check me" />
</template>
```

### Tamanho

Use a prop `size` para alterar o tamanho do Checkbox.

```vue
<template>
  <UCheckbox size="xl" variant="list" default-value label="Check me" />
</template>
```

### Indicador

Use a prop `indicator` para alterar a posição ou ocultar o indicador. O padrão é `start`.

```vue
<template>
  <UCheckbox indicator="end" variant="card" default-value label="Check me" />
</template>
```

### Desabilitado

Use a prop `disabled` para desabilitar o Checkbox.

```vue
<template>
  <UCheckbox disabled label="Check me" />
</template>
```

## API

### Props

```ts
/**
 * Props for the Checkbox component
 */
interface CheckboxProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  label?: string | undefined;
  description?: string | undefined;
  color?: "primary" | "secondary" | "accent" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
  variant?: "card" | "list" | undefined;
  size?: "xs" | "sm" | "md" | "lg" | "xl" | undefined;
  /**
   * Position of the indicator.
   */
  indicator?: "start" | "end" | "hidden" | undefined;
  /**
   * Highlight the ring color like a focus state.
   */
  highlight?: boolean | undefined;
  /**
   * The icon displayed when checked.
   */
  icon?: any;
  /**
   * The icon displayed when the checkbox is indeterminate.
   */
  indeterminateIcon?: any;
  ui?: { root?: SlotClass; container?: SlotClass; base?: SlotClass; indicator?: SlotClass; icon?: SlotClass; wrapper?: SlotClass; label?: SlotClass; description?: SlotClass; } | undefined;
  /**
   * When `true`, prevents the user from interacting with the checkbox
   */
  disabled?: boolean | undefined;
  /**
   * When `true`, indicates that the user must set the value before the owning form can be submitted.
   */
  required?: boolean | undefined;
  /**
   * The name of the field. Submitted with its owning form as part of a name/value pair.
   */
  name?: string | undefined;
  /**
   * The value given as data when submitted with a `name`.
   */
  value?: AcceptableValue | undefined;
  /**
   * Id of the element
   */
  id?: string | undefined;
  /**
   * The value of the checkbox when it is initially rendered. Use when you do not need to control its value.
   */
  defaultValue?: T | "indeterminate" | undefined;
  /**
   * The controlled value of the checkbox. Can be binded with v-model.
   */
  modelValue?: T | "indeterminate" | null | undefined;
  /**
   * The value used when the checkbox is checked. Defaults to `true`.
   */
  trueValue?: T | undefined;
  /**
   * The value used when the checkbox is unchecked. Defaults to `false`.
   */
  falseValue?: T | undefined;
  autofocus?: Booleanish | undefined;
  form?: string | undefined;
  formaction?: string | undefined;
  formenctype?: string | undefined;
  formmethod?: string | undefined;
  formnovalidate?: Booleanish | undefined;
  formtarget?: string | undefined;
}
```

> \[!NOTE]
> See: https\://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attributes
>
> Este componente também suporta todos os atributos HTML nativos de `<button>`.

### Slots

```ts
/**
 * Slots for the Checkbox component
 */
interface CheckboxSlots {
  label(): any;
  description(): any;
}
```

### Emits

```ts
/**
 * Emitted events for the Checkbox component
 */
interface CheckboxEmits {
  change: (payload: [event: Event]) => void;
  update:modelValue: (payload: [value: T | "indeterminate"]) => void;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    checkbox: {
      slots: {
        root: 'relative flex items-start',
        container: 'flex items-center',
        base: 'rounded-sm ring ring-inset ring-accented overflow-hidden focus-visible:outline-3',
        indicator: 'flex items-center justify-center size-full text-inverted',
        icon: 'shrink-0 size-full',
        wrapper: 'w-full',
        label: 'block font-medium text-default',
        description: 'text-muted'
      },
      variants: {
        color: {
          primary: {
            base: 'outline-primary/25 focus-visible:ring-primary',
            indicator: 'bg-primary'
          },
          secondary: {
            base: 'outline-secondary/25 focus-visible:ring-secondary',
            indicator: 'bg-secondary'
          },
          accent: {
            base: 'outline-accent/25 focus-visible:ring-accent',
            indicator: 'bg-accent'
          },
          success: {
            base: 'outline-success/25 focus-visible:ring-success',
            indicator: 'bg-success'
          },
          info: {
            base: 'outline-info/25 focus-visible:ring-info',
            indicator: 'bg-info'
          },
          warning: {
            base: 'outline-warning/25 focus-visible:ring-warning',
            indicator: 'bg-warning'
          },
          error: {
            base: 'outline-error/25 focus-visible:ring-error',
            indicator: 'bg-error'
          },
          neutral: {
            base: 'outline-inverted/25 focus-visible:ring-inverted',
            indicator: 'bg-inverted'
          }
        },
        variant: {
          list: {
            root: ''
          },
          card: {
            root: 'border border-muted rounded-lg'
          }
        },
        indicator: {
          start: {
            root: 'flex-row',
            wrapper: 'ms-2'
          },
          end: {
            root: 'flex-row-reverse',
            wrapper: 'me-2'
          },
          hidden: {
            base: 'sr-only',
            wrapper: 'text-center'
          }
        },
        size: {
          xs: {
            base: 'size-3',
            container: 'h-4',
            wrapper: 'text-xs'
          },
          sm: {
            base: 'size-3.5',
            container: 'h-4',
            wrapper: 'text-xs'
          },
          md: {
            base: 'size-4',
            container: 'h-5',
            wrapper: 'text-sm'
          },
          lg: {
            base: 'size-4.5',
            container: 'h-5',
            wrapper: 'text-sm'
          },
          xl: {
            base: 'size-5',
            container: 'h-6',
            wrapper: 'text-base'
          }
        },
        required: {
          true: {
            label: "after:content-['*'] after:ms-0.5 after:text-error"
          }
        },
        disabled: {
          true: {
            root: 'opacity-75',
            base: 'cursor-not-allowed',
            label: 'cursor-not-allowed',
            description: 'cursor-not-allowed'
          }
        },
        highlight: {
          true: ''
        },
        checked: {
          true: ''
        }
      },
      compoundVariants: [
        {
          size: 'xs',
          variant: 'card',
          class: {
            root: 'p-2.5'
          }
        },
        {
          size: 'sm',
          variant: 'card',
          class: {
            root: 'p-3'
          }
        },
        {
          size: 'md',
          variant: 'card',
          class: {
            root: 'p-3.5'
          }
        },
        {
          size: 'lg',
          variant: 'card',
          class: {
            root: 'p-4'
          }
        },
        {
          size: 'xl',
          variant: 'card',
          class: {
            root: 'p-4.5'
          }
        },
        {
          color: 'primary',
          variant: 'card',
          class: {
            root: 'has-data-[state=checked]:border-primary'
          }
        },
        {
          color: 'secondary',
          variant: 'card',
          class: {
            root: 'has-data-[state=checked]:border-secondary'
          }
        },
        {
          color: 'accent',
          variant: 'card',
          class: {
            root: 'has-data-[state=checked]:border-accent'
          }
        },
        {
          color: 'success',
          variant: 'card',
          class: {
            root: 'has-data-[state=checked]:border-success'
          }
        },
        {
          color: 'info',
          variant: 'card',
          class: {
            root: 'has-data-[state=checked]:border-info'
          }
        },
        {
          color: 'warning',
          variant: 'card',
          class: {
            root: 'has-data-[state=checked]:border-warning'
          }
        },
        {
          color: 'error',
          variant: 'card',
          class: {
            root: 'has-data-[state=checked]:border-error'
          }
        },
        {
          color: 'neutral',
          variant: 'card',
          class: {
            root: 'has-data-[state=checked]:border-inverted'
          }
        },
        {
          variant: 'card',
          disabled: true,
          class: {
            root: 'cursor-not-allowed'
          }
        },
        {
          color: 'primary',
          highlight: true,
          class: {
            base: 'ring-primary'
          }
        },
        {
          color: 'secondary',
          highlight: true,
          class: {
            base: 'ring-secondary'
          }
        },
        {
          color: 'accent',
          highlight: true,
          class: {
            base: 'ring-accent'
          }
        },
        {
          color: 'success',
          highlight: true,
          class: {
            base: 'ring-success'
          }
        },
        {
          color: 'info',
          highlight: true,
          class: {
            base: 'ring-info'
          }
        },
        {
          color: 'warning',
          highlight: true,
          class: {
            base: 'ring-warning'
          }
        },
        {
          color: 'error',
          highlight: true,
          class: {
            base: 'ring-error'
          }
        },
        {
          color: 'neutral',
          highlight: true,
          class: {
            base: 'ring-inverted'
          }
        }
      ],
      defaultVariants: {
        size: 'md',
        color: 'primary',
        variant: 'list',
        indicator: 'start'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/Checkbox.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/checkbox.ts).


# CheckboxGroup

## Uso

Use a diretiva `v-model` para controlar o valor do CheckboxGroup ou a prop `default-value` para definir o valor inicial quando você não precisa controlar o estado.

```vue
<script setup lang="ts">
const items = ref([
  "System",
  "Light",
  "Dark"
])
const value = ref([
  "System"
])
</script>

<template>
  <UCheckboxGroup v-model="value" :items="items" />
</template>
```

### Itens

Use a prop `items` como um array de strings ou números:

```vue
<script setup lang="ts">
const items = ref([
  "System",
  "Light",
  "Dark"
])
const value = ref([
  "System"
])
</script>

<template>
  <UCheckboxGroup v-model="value" :items="items" />
</template>
```

Você também pode passar um array de objetos com as seguintes propriedades:

- `label?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `description?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- [`value?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}](https://ui.nitro.news/#value-key)
- `disabled?: boolean`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `class?: any`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `ui?: { item?: ClassNameValue, container?: ClassNameValue, base?: ClassNameValue, 'indicator'?: ClassNameValue, icon?: ClassNameValue, wrapper?: ClassNameValue, label?: ClassNameValue, description?: ClassNameValue }`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

```vue
<script setup lang="ts">
import type { CheckboxGroupItem } from '@nitro/ui'

const items = ref<CheckboxGroupItem[]>([
  {
    label: "System",
    description: "This is the first option.",
    value: "system"
  },
  {
    label: "Light",
    description: "This is the second option.",
    value: "light"
  },
  {
    label: "Dark",
    description: "This is the third option.",
    value: "dark"
  }
])
const value = ref([
  "system"
])
</script>

<template>
  <UCheckboxGroup v-model="value" :items="items" />
</template>
```

> \[!CAUTION]
>
> Ao usar objetos, você precisa referenciar a propriedade `value` do objeto na diretiva `v-model` ou na prop `default-value`.

### Chave de valor

Você pode alterar a propriedade usada para definir o valor usando a prop `value-key`. O padrão é `value`.

```vue
<script setup lang="ts">
import type { CheckboxGroupItem } from '@nitro/ui'

const items = ref<CheckboxGroupItem[]>([
  {
    label: "System",
    description: "This is the first option.",
    id: "system"
  },
  {
    label: "Light",
    description: "This is the second option.",
    id: "light"
  },
  {
    label: "Dark",
    description: "This is the third option.",
    id: "dark"
  }
])
const value = ref([
  "light"
])
</script>

<template>
  <UCheckboxGroup v-model="value" value-key="id" :items="items" />
</template>
```

### Legenda

Use a prop `legend` para definir a legenda do CheckboxGroup.

```vue
<script setup lang="ts">
const items = ref([
  "System",
  "Light",
  "Dark"
])
</script>

<template>
  <UCheckboxGroup legend="Theme" :default-value="[
  'System'
]" :items="items" />
</template>
```

### Cor

Use a prop `color` para alterar a cor do CheckboxGroup.

```vue
<script setup lang="ts">
const items = ref([
  "System",
  "Light",
  "Dark"
])
</script>

<template>
  <UCheckboxGroup color="neutral" :default-value="[
  'System'
]" :items="items" />
</template>
```

### Variante

Use a prop `variant` para alterar a variante do CheckboxGroup.

```vue
<script setup lang="ts">
const items = ref([
  "System",
  "Light",
  "Dark"
])
</script>

<template>
  <UCheckboxGroup color="primary" variant="card" :default-value="[
  'System'
]" :items="items" />
</template>
```

### Tamanho

Use a prop `size` para alterar o tamanho do CheckboxGroup.

```vue
<script setup lang="ts">
const items = ref([
  "System",
  "Light",
  "Dark"
])
</script>

<template>
  <UCheckboxGroup size="xl" variant="list" :default-value="[
  'System'
]" :items="items" />
</template>
```

### Orientação

Use a prop `orientation` para alterar a orientação do CheckboxGroup. O padrão é `vertical`.

```vue
<script setup lang="ts">
const items = ref([
  "System",
  "Light",
  "Dark"
])
</script>

<template>
  <UCheckboxGroup orientation="horizontal" variant="list" :default-value="[
  'System'
]" :items="items" />
</template>
```

### Indicador

Use a prop `indicator` para alterar a posição ou ocultar o indicador. O padrão é `start`.

```vue
<script setup lang="ts">
const items = ref([
  "System",
  "Light",
  "Dark"
])
</script>

<template>
  <UCheckboxGroup indicator="end" variant="card" :default-value="[
  'System'
]" :items="items" />
</template>
```

### Desabilitado

Use a prop `disabled` para desabilitar o CheckboxGroup.

```vue
<script setup lang="ts">
const items = ref([
  "System",
  "Light",
  "Dark"
])
</script>

<template>
  <UCheckboxGroup disabled :default-value="[
  'System'
]" :items="items" />
</template>
```

## API

### Props

```ts
/**
 * Props for the CheckboxGroup component
 */
interface CheckboxGroupProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  legend?: string | undefined;
  /**
   * When `items` is an array of objects, select the field to use as the value.
   * @default "\"value\" as never"
   */
  valueKey?: VK | undefined;
  /**
   * When `items` is an array of objects, select the field to use as the label.
   * @default "\"label\""
   */
  labelKey?: GetItemKeys<T> | undefined;
  /**
   * When `items` is an array of objects, select the field to use as the description.
   * @default "\"description\""
   */
  descriptionKey?: GetItemKeys<T> | undefined;
  items?: T | undefined;
  /**
   * The controlled value of the CheckboxGroup. Can be bind as `v-model`.
   */
  modelValue?: GetItemValue<T, VK, undefined, NestedItem<T>>[] | undefined;
  /**
   * The value of the CheckboxGroup when initially rendered. Use when you do not need to control the state of the CheckboxGroup.
   */
  defaultValue?: GetItemValue<T, VK, undefined, NestedItem<T>>[] | undefined;
  size?: "xs" | "sm" | "md" | "lg" | "xl" | undefined;
  variant?: "table" | "list" | "card" | undefined;
  /**
   * The orientation the checkbox buttons are laid out.
   * @default "\"vertical\""
   */
  orientation?: "horizontal" | "vertical" | undefined;
  ui?: ({ root?: SlotClass; fieldset?: SlotClass; legend?: SlotClass; item?: SlotClass; } & { root?: SlotClass; container?: SlotClass; base?: SlotClass; indicator?: SlotClass; icon?: SlotClass; wrapper?: SlotClass; label?: SlotClass; description?: SlotClass; }) | undefined;
  /**
   * When `true`, prevents the user from interacting with the checkboxes
   */
  disabled?: boolean | undefined;
  /**
   * Whether keyboard navigation should loop around
   */
  loop?: boolean | undefined;
  /**
   * The name of the field. Submitted with its owning form as part of a name/value pair.
   */
  name?: string | undefined;
  /**
   * When `true`, indicates that the user must set the value before the owning form can be submitted.
   */
  required?: boolean | undefined;
  color?: "primary" | "secondary" | "accent" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
  /**
   * Highlight the ring color like a focus state.
   */
  highlight?: boolean | undefined;
  /**
   * Position of the indicator.
   */
  indicator?: "start" | "end" | "hidden" | undefined;
  /**
   * The icon displayed when checked.
   */
  icon?: any;
}
```

### Slots

```ts
/**
 * Slots for the CheckboxGroup component
 */
interface CheckboxGroupSlots {
  legend(): any;
  label(): any;
  description(): any;
}
```

### Emits

```ts
/**
 * Emitted events for the CheckboxGroup component
 */
interface CheckboxGroupEmits {
  update:modelValue: (payload: [value: GetItemValue<T, VK, undefined, NestedItem<T>>[]]) => void;
  change: (payload: [event: Event]) => void;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    checkboxGroup: {
      slots: {
        root: 'relative',
        fieldset: 'flex gap-x-2',
        legend: 'mb-1 block font-medium text-default',
        item: ''
      },
      variants: {
        orientation: {
          horizontal: {
            fieldset: 'flex-row'
          },
          vertical: {
            fieldset: 'flex-col'
          }
        },
        color: {
          primary: {},
          secondary: {},
          accent: {},
          success: {},
          info: {},
          warning: {},
          error: {},
          neutral: {}
        },
        variant: {
          list: {},
          card: {},
          table: {
            item: 'border border-muted'
          }
        },
        size: {
          xs: {
            fieldset: 'gap-y-0.5',
            legend: 'text-xs'
          },
          sm: {
            fieldset: 'gap-y-0.5',
            legend: 'text-xs'
          },
          md: {
            fieldset: 'gap-y-1',
            legend: 'text-sm'
          },
          lg: {
            fieldset: 'gap-y-1',
            legend: 'text-sm'
          },
          xl: {
            fieldset: 'gap-y-1.5',
            legend: 'text-base'
          }
        },
        required: {
          true: {
            legend: "after:content-['*'] after:ms-0.5 after:text-error"
          }
        },
        disabled: {
          true: {}
        }
      },
      compoundVariants: [
        {
          size: 'xs',
          variant: 'table',
          class: {
            item: 'p-2.5'
          }
        },
        {
          size: 'sm',
          variant: 'table',
          class: {
            item: 'p-3'
          }
        },
        {
          size: 'md',
          variant: 'table',
          class: {
            item: 'p-3.5'
          }
        },
        {
          size: 'lg',
          variant: 'table',
          class: {
            item: 'p-4'
          }
        },
        {
          size: 'xl',
          variant: 'table',
          class: {
            item: 'p-4.5'
          }
        },
        {
          orientation: 'horizontal',
          variant: 'table',
          class: {
            item: 'first-of-type:rounded-s-lg last-of-type:rounded-e-lg',
            fieldset: 'gap-0 -space-x-px'
          }
        },
        {
          orientation: 'vertical',
          variant: 'table',
          class: {
            item: 'first-of-type:rounded-t-lg last-of-type:rounded-b-lg',
            fieldset: 'gap-0 -space-y-px'
          }
        },
        {
          color: 'primary',
          variant: 'table',
          class: {
            item: 'has-data-[state=checked]:bg-primary/10 has-data-[state=checked]:border-primary/50 has-data-[state=checked]:z-[1]'
          }
        },
        {
          color: 'secondary',
          variant: 'table',
          class: {
            item: 'has-data-[state=checked]:bg-secondary/10 has-data-[state=checked]:border-secondary/50 has-data-[state=checked]:z-[1]'
          }
        },
        {
          color: 'accent',
          variant: 'table',
          class: {
            item: 'has-data-[state=checked]:bg-accent/10 has-data-[state=checked]:border-accent/50 has-data-[state=checked]:z-[1]'
          }
        },
        {
          color: 'success',
          variant: 'table',
          class: {
            item: 'has-data-[state=checked]:bg-success/10 has-data-[state=checked]:border-success/50 has-data-[state=checked]:z-[1]'
          }
        },
        {
          color: 'info',
          variant: 'table',
          class: {
            item: 'has-data-[state=checked]:bg-info/10 has-data-[state=checked]:border-info/50 has-data-[state=checked]:z-[1]'
          }
        },
        {
          color: 'warning',
          variant: 'table',
          class: {
            item: 'has-data-[state=checked]:bg-warning/10 has-data-[state=checked]:border-warning/50 has-data-[state=checked]:z-[1]'
          }
        },
        {
          color: 'error',
          variant: 'table',
          class: {
            item: 'has-data-[state=checked]:bg-error/10 has-data-[state=checked]:border-error/50 has-data-[state=checked]:z-[1]'
          }
        },
        {
          color: 'neutral',
          variant: 'table',
          class: {
            item: 'has-data-[state=checked]:bg-elevated has-data-[state=checked]:border-inverted/50 has-data-[state=checked]:z-[1]'
          }
        },
        {
          variant: 'table',
          disabled: true,
          class: {
            item: 'cursor-not-allowed'
          }
        }
      ],
      defaultVariants: {
        size: 'md',
        variant: 'list',
        color: 'primary'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/CheckboxGroup.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/checkbox-group.ts).


# Chip

## Uso

Envolva qualquer componente com um Chip para exibir um indicador.

```vue
<template>
  <UChip>
    <NButton icon="i-lucide-mail" color="neutral" variant="subtle" />
  </UChip>
</template>
```

### Cor

Use a prop `color` para alterar a cor do Chip.

```vue
<template>
  <UChip color="neutral">
    <NButton icon="i-lucide-mail" color="neutral" variant="subtle" />
  </UChip>
</template>
```

### Tamanho

Use a prop `size` para alterar o tamanho do Chip.

```vue
<template>
  <UChip size="3xl">
    <NButton icon="i-lucide-mail" color="neutral" variant="subtle" />
  </UChip>
</template>
```

### Texto

Use a prop `text` para definir o texto do Chip.

```vue
<template>
  <UChip :text="5" size="3xl">
    <NButton icon="i-lucide-mail" color="neutral" variant="subtle" />
  </UChip>
</template>
```

### Posição

Use a prop `position` para alterar a posição do Chip.

```vue
<template>
  <UChip position="bottom-left">
    <NButton icon="i-lucide-mail" color="neutral" variant="subtle" />
  </UChip>
</template>
```

### Inset

Use a prop `inset` para exibir o Chip dentro do componente. Isso é útil ao lidar com componentes arredondados.

```vue
<template>
  <UChip inset>
    <NAvatar src="https://github.com/benjamincanac.png" loading="lazy" />
  </UChip>
</template>
```

### Independente

Use a prop `standalone` junto com a prop `inset` para exibir o Chip inline.

```vue
<template>
  <UChip standalone inset />
</template>
```

> \[!NOTE]
>
> É usado dessa forma nos componentes [`CommandPalette`](https://ui.nitro.news/docs/components/command-palette), [`InputMenu`](https://ui.nitro.news/docs/components/input-menu), [`Select`](https://ui.nitro.news/docs/components/select) ou [`SelectMenu`](https://ui.nitro.news/docs/components/select-menu), por exemplo.

## Exemplos

### Controlar a visibilidade

Você pode controlar a visibilidade do Chip usando a prop `show`.

:component-example{name="chip-show-example"}

> \[!NOTE]
>
> Neste exemplo, o Chip tem uma cor por status e é exibido quando o status não é `offline`.

## API

### Props

```ts
/**
 * Props for the Chip component
 */
interface ChipProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  /**
   * Display some text inside the chip.
   */
  text?: string | number | undefined;
  color?: "primary" | "secondary" | "accent" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
  size?: "xs" | "sm" | "md" | "lg" | "xl" | "3xs" | "2xs" | "2xl" | "3xl" | undefined;
  /**
   * The position of the chip.
   */
  position?: "top-right" | "bottom-right" | "top-left" | "bottom-left" | undefined;
  /**
   * When `true`, keep the chip inside the component for rounded elements.
   * @default "false"
   */
  inset?: boolean | undefined;
  /**
   * When `true`, render the chip relatively to the parent.
   * @default "false"
   */
  standalone?: boolean | undefined;
  ui?: { root?: SlotClass; base?: SlotClass; } | undefined;
  /**
   * @default "true"
   */
  show?: boolean | undefined;
}
```

### Slots

```ts
/**
 * Slots for the Chip component
 */
interface ChipSlots {
  default(): any;
  content(): any;
}
```

### Emits

```ts
/**
 * Emitted events for the Chip component
 */
interface ChipEmits {
  update:show: (payload: [value: boolean]) => void;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    chip: {
      slots: {
        root: 'relative inline-flex items-center justify-center shrink-0',
        base: 'rounded-full ring ring-bg flex items-center justify-center text-inverted font-medium whitespace-nowrap'
      },
      variants: {
        color: {
          primary: 'bg-primary',
          secondary: 'bg-secondary',
          accent: 'bg-accent',
          success: 'bg-success',
          info: 'bg-info',
          warning: 'bg-warning',
          error: 'bg-error',
          neutral: 'bg-inverted'
        },
        size: {
          '3xs': 'h-[4px] min-w-[4px] text-[4px]',
          '2xs': 'h-[5px] min-w-[5px] text-[5px]',
          xs: 'h-[6px] min-w-[6px] text-[6px]',
          sm: 'h-[7px] min-w-[7px] text-[7px]',
          md: 'h-[8px] min-w-[8px] text-[8px]',
          lg: 'h-[9px] min-w-[9px] text-[9px]',
          xl: 'h-[10px] min-w-[10px] text-[10px]',
          '2xl': 'h-[11px] min-w-[11px] text-[11px]',
          '3xl': 'h-[12px] min-w-[12px] text-[12px]'
        },
        position: {
          'top-right': 'top-0 right-0',
          'bottom-right': 'bottom-0 right-0',
          'top-left': 'top-0 left-0',
          'bottom-left': 'bottom-0 left-0'
        },
        inset: {
          false: ''
        },
        standalone: {
          false: 'absolute'
        }
      },
      compoundVariants: [
        {
          position: 'top-right',
          inset: false,
          class: '-translate-y-1/2 translate-x-1/2 transform'
        },
        {
          position: 'bottom-right',
          inset: false,
          class: 'translate-y-1/2 translate-x-1/2 transform'
        },
        {
          position: 'top-left',
          inset: false,
          class: '-translate-y-1/2 -translate-x-1/2 transform'
        },
        {
          position: 'bottom-left',
          inset: false,
          class: 'translate-y-1/2 -translate-x-1/2 transform'
        }
      ],
      defaultVariants: {
        size: 'md',
        color: 'primary',
        position: 'top-right'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/Chip.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/chip.ts).


# Collapsible

## Uso

Use a [Button](https://ui.nitro.news/docs/components/button) or any other component in the default slot of the Collapsible.

Depois, use o slot `#content` para adicionar o conteúdo exibido quando o Collapsible está aberto.

```vue
<template>
  <UCollapsible class="flex flex-col gap-2 w-48">
    <NButton label="Open" color="neutral" variant="subtle" trailing-icon="i-lucide-chevron-down" block />
  
    <template #content>
      <Placeholder class="h-48" />
    </template></UCollapsible>
</template>
```

### Desmontar

Use a prop `unmount-on-hide` para evitar que o conteúdo seja desmontado quando o Collapsible é recolhido. O padrão é `true`.

```vue
<template>
  <UCollapsible :unmount-on-hide="false" class="flex flex-col gap-2 w-48">
    <NButton label="Open" color="neutral" variant="subtle" trailing-icon="i-lucide-chevron-down" block />
  
    <template #content>
      <Placeholder class="h-48" />
    </template></UCollapsible>
</template>
```

> \[!NOTE]
>
> Você pode inspecionar o DOM para ver o conteúdo sendo renderizado.

### Desabilitado

Use a prop `disabled` para desabilitar o Collapsible.

```vue
<template>
  <UCollapsible class="flex flex-col gap-2 w-48" disabled>
    <NButton label="Open" color="neutral" variant="subtle" trailing-icon="i-lucide-chevron-down" block />
  
    <template #content>
      <Placeholder class="h-48" />
    </template></UCollapsible>
</template>
```

## Exemplos

### Controlar o estado de abertura

Você pode controlar o estado de abertura usando a prop `default-open` ou a diretiva `v-model:open`.

:component-example{name="collapsible-open-example"}

> \[!NOTE]
>
> Neste exemplo, aproveitando o [`defineShortcuts`](https://ui.nitro.news/docs/composables/define-shortcuts), você pode abrir e fechar o Collapsible pressionando :kbd{value="O"}.

> \[!TIP]
>
> Isso permite mover o gatilho para fora do Collapsible ou removê-lo por completo.

### Com ícone rotativo

Aqui está um exemplo com um ícone rotativo no Button que indica o estado de abertura do Collapsible.

:component-example{name="collapsible-icon-example"}

## API

### Props

```ts
/**
 * Props for the Collapsible component
 */
interface CollapsibleProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  ui?: { root?: SlotClass; content?: SlotClass; } | undefined;
  /**
   * When `true`, prevents the user from interacting with the collapsible.
   */
  disabled?: boolean | undefined;
  /**
   * The open state of the collapsible when it is initially rendered. <br> Use when you do not need to control its open state.
   */
  defaultOpen?: boolean | undefined;
  /**
   * The controlled open state of the collapsible. Can be binded with `v-model`.
   */
  open?: boolean | undefined;
  /**
   * When `true`, the element will be unmounted on closed state.
   * @default "true"
   */
  unmountOnHide?: boolean | undefined;
}
```

### Slots

```ts
/**
 * Slots for the Collapsible component
 */
interface CollapsibleSlots {
  default(): any;
  content(): any;
}
```

### Emits

```ts
/**
 * Emitted events for the Collapsible component
 */
interface CollapsibleEmits {
  update:open: (payload: [value: boolean]) => void;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    collapsible: {
      slots: {
        root: '',
        content: 'data-[state=open]:animate-[collapsible-down_200ms_ease-out] data-[state=closed]:animate-[collapsible-up_200ms_ease-out] overflow-hidden'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/Collapsible.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/collapsible.ts).


# ColorModeAvatar

## Uso

O componente ColorModeAvatar estende o componente [Avatar](https://ui.nitro.news/docs/components/avatar), então você pode passar qualquer propriedade como `size`, `icon`, etc.

Use as props `light` e `dark` para definir a origem para os modos claro e escuro.

```vue
<template>
  <UColorModeAvatar light="https://github.com/vuejs.png" dark="https://github.com/nuxt.png" />
</template>
```

> \[!NOTE]
>
> Alterne entre os modos claro e escuro para ver as diferentes imagens: :n-color-mode-select{size="sm"}

## API

### Props

```ts
/**
 * Props for the ColorModeAvatar component
 */
interface ColorModeAvatarProps {
  light: string;
  dark: string;
  /**
   * The element or component this component should render as.
   */
  as?: any;
  color?: "primary" | "secondary" | "accent" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
  ui?: { root?: SlotClass; image?: SlotClass; fallback?: SlotClass; icon?: SlotClass; } | undefined;
  alt?: string | undefined;
  crossorigin?: "" | "anonymous" | "use-credentials" | undefined;
  decoding?: "async" | "auto" | "sync" | undefined;
  height?: Numberish | undefined;
  loading?: "lazy" | "eager" | undefined;
  referrerpolicy?: HTMLAttributeReferrerPolicy | undefined;
  sizes?: string | undefined;
  srcset?: string | undefined;
  usemap?: string | undefined;
  width?: Numberish | undefined;
  icon?: any;
  text?: string | undefined;
  size?: "md" | "3xs" | "2xs" | "xs" | "sm" | "lg" | "xl" | "2xl" | "3xl" | undefined;
  chip?: boolean | ChipProps | undefined;
}
```

> \[!NOTE]
> See: https\://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#attributes
>
> Este componente também suporta todos os atributos HTML nativos de `<img>`.

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/color-mode/ColorModeAvatar.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/color-mode/color-mode-avatar.ts).


# ColorModeButton

## Uso

O componente ColorModeButton estende o componente [Button](https://ui.nitro.news/docs/components/button), então você pode passar qualquer propriedade como `color`, `variant`, `size`, etc.

```vue
<template>
  <UColorModeButton />
</template>
```

> \[!NOTE]
>
> O botão usa por padrão `color="neutral"` e `variant="ghost"`.

## Exemplos

### Com ícones personalizados

**Nuxt:**

Use o `app.config.ts` para personalizar o ícone com a propriedade `ui.icons`:

```ts [app/app.config.ts]
export default defineAppConfig({
  ui: {
    icons: {
      light: 'i-ph-sun',
      dark: 'i-ph-moon'
    }
  }
})
```

**Vue:**

Use o `vite.config.ts` para personalizar o ícone com a propriedade `ui.icons`:

```ts [vite.config.ts]
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nitro/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      ui: {
        icons: {
          light: 'i-ph-sun',
          dark: 'i-ph-moon'
        }
      }
    })
  ]
})
```

### Com slot de fallback

Como o botão é envolvido em um componente [ClientOnly](https://nuxt.com/docs/api/components/client-only){rel="&#x22;nofollow&#x22;"}, você pode passar um slot `fallback` para exibir um placeholder enquanto o componente está carregando.

```vue
<template>
  <UColorModeButton>
    <template #fallback>
      <NButton loading variant="ghost" color="neutral" />
    </template></UColorModeButton>
</template>
```

## API

### Props

```ts
/**
 * Props for the ColorModeButton component
 */
interface ColorModeButtonProps {
  /**
   * @default "\"neutral\""
   */
  color?: "primary" | "secondary" | "accent" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
  /**
   * @default "\"ghost\""
   */
  variant?: "link" | "ghost" | "solid" | "outline" | "soft" | "subtle" | undefined;
  /**
   * The element or component this component should render as when not a link.
   */
  as?: any;
  /**
   * Display an icon on the right side.
   */
  trailingIcon?: any;
  ui?: { base?: SlotClass; label?: SlotClass; leadingIcon?: SlotClass; leadingAvatar?: SlotClass; leadingAvatarSize?: SlotClass; trailingIcon?: SlotClass; } | undefined;
  name?: string | undefined;
  /**
   * When `true`, the icon will be displayed on the right side.
   */
  trailing?: boolean | undefined;
  /**
   * When `true`, the loading icon will be displayed.
   */
  loading?: boolean | undefined;
  onClick?: ((event: MouseEvent) => void) | ((event: MouseEvent) => void)[] | undefined;
  /**
   * Display an icon based on the `leading` and `trailing` props.
   */
  icon?: any;
  size?: "md" | "xs" | "sm" | "lg" | "xl" | undefined;
  /**
   * Display an avatar on the left side.
   */
  avatar?: AvatarProps | undefined;
  /**
   * Class to apply when the link is exact active
   */
  exactActiveClass?: string | undefined;
  /**
   * Pass the returned promise of `router.push()` to `document.startViewTransition()` if supported.
   */
  viewTransition?: boolean | undefined;
  autofocus?: Booleanish | undefined;
  disabled?: boolean | undefined;
  form?: string | undefined;
  formaction?: string | undefined;
  formenctype?: string | undefined;
  formmethod?: string | undefined;
  formnovalidate?: Booleanish | undefined;
  formtarget?: string | undefined;
  /**
   * The type of the button when not a link.
   */
  type?: "reset" | "submit" | "button" | undefined;
  label?: string | undefined;
  activeColor?: "primary" | "secondary" | "accent" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
  activeVariant?: "link" | "ghost" | "solid" | "outline" | "soft" | "subtle" | undefined;
  /**
   * Render the button with equal padding on all sides.
   */
  square?: boolean | undefined;
  /**
   * Render the button full width.
   */
  block?: boolean | undefined;
  /**
   * Set loading state automatically based on the `@click` promise state
   */
  loadingAuto?: boolean | undefined;
  /**
   * When `true`, the icon will be displayed on the left side.
   */
  leading?: boolean | undefined;
  /**
   * Display an icon on the left side.
   */
  leadingIcon?: any;
  /**
   * The icon when the `loading` prop is `true`.
   */
  loadingIcon?: any;
}
```

> \[!NOTE]
> See: https\://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attributes
>
> Este componente também suporta todos os atributos HTML nativos de `<button>`.

### Slots

```ts
/**
 * Slots for the ColorModeButton component
 */
interface ColorModeButtonSlots {
}
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/color-mode/ColorModeButton.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/color-mode/color-mode-button.ts).


# ColorModeImage

## Uso

O componente ColorModeImage usa o componente `<NuxtImg>` quando o [`@nuxt/image`](https://github.com/nuxt/image){rel="&#x22;nofollow&#x22;"} está instalado, recorrendo a `img` caso contrário.

```vue
<template>
  <UColorModeImage light="https://picsum.photos/id/29/400" dark="https://picsum.photos/id/46/400" :width="200" :height="200" />
</template>
```

> \[!NOTE]
>
> Alterne entre os modos claro e escuro para ver as diferentes imagens: :n-color-mode-select{size="sm"}

## API

### Props

```ts
/**
 * Props for the ColorModeImage component
 */
interface ColorModeImageProps {
  dark: string;
  light: string;
  alt?: string | undefined;
  crossorigin?: "" | "anonymous" | "use-credentials" | undefined;
  decoding?: "async" | "auto" | "sync" | undefined;
  height?: Numberish | undefined;
  loading?: "lazy" | "eager" | undefined;
  referrerpolicy?: HTMLAttributeReferrerPolicy | undefined;
  sizes?: string | undefined;
  srcset?: string | undefined;
  usemap?: string | undefined;
  width?: Numberish | undefined;
}
```

> \[!NOTE]
> See: https\://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#attributes
>
> Este componente também suporta todos os atributos HTML nativos de `<img>`.

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/color-mode/ColorModeImage.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/color-mode/color-mode-image.ts).


# ColorModeSelect

## Uso

O componente ColorModeSelect estende o componente [SelectMenu](https://ui.nitro.news/docs/components/select-menu), então você pode passar qualquer propriedade como `color`, `variant`, `size`, etc.

```vue
<template>
  <UColorModeSelect />
</template>
```

## Exemplos

### Com ícones personalizados

**Nuxt:**

Use o `app.config.ts` para personalizar o ícone com a propriedade `ui.icons`:

```ts [app/app.config.ts]
export default defineAppConfig({
  ui: {
    icons: {
      system: 'i-ph-desktop',
      light: 'i-ph-sun',
      dark: 'i-ph-moon'
    }
  }
})
```

**Vue:**

Use o `vite.config.ts` para personalizar o ícone com a propriedade `ui.icons`:

```ts [vite.config.ts]
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nitro/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      ui: {
        icons: {
          light: 'i-ph-sun',
          dark: 'i-ph-moon'
        }
      }
    })
  ]
})
```

## API

### Props

```ts
/**
 * Props for the ColorModeSelect component
 */
interface ColorModeSelectProps {
  /**
   * The open state of the combobox when it is initially rendered. <br> Use when you do not need to control its open state.
   */
  defaultOpen?: boolean | undefined;
  /**
   * The controlled open state of the Combobox. Can be binded with `v-model:open`.
   */
  open?: boolean | undefined;
  /**
   * The icon displayed to open the menu.
   */
  trailingIcon?: any;
  color?: "primary" | "secondary" | "accent" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
  /**
   * Highlight the ring color like a focus state.
   */
  highlight?: boolean | undefined;
  ui?: { base?: SlotClass; leading?: SlotClass; leadingIcon?: SlotClass; leadingAvatar?: SlotClass; leadingAvatarSize?: SlotClass; trailing?: SlotClass; trailingIcon?: SlotClass; value?: SlotClass; placeholder?: SlotClass; arrow?: SlotClass; content?: SlotClass; viewport?: SlotClass; group?: SlotClass; empty?: SlotClass; label?: SlotClass; separator?: SlotClass; item?: SlotClass; itemLeadingIcon?: SlotClass; itemLeadingAvatar?: SlotClass; itemLeadingAvatarSize?: SlotClass; itemLeadingChip?: SlotClass; itemLeadingChipSize?: SlotClass; itemTrailing?: SlotClass; itemTrailingIcon?: SlotClass; itemWrapper?: SlotClass; itemLabel?: SlotClass; itemDescription?: SlotClass; input?: SlotClass; focusScope?: SlotClass; trailingClear?: SlotClass; } | undefined;
  /**
   * The name of the field. Submitted with its owning form as part of a name/value pair.
   */
  name?: string | undefined;
  /**
   * When `true`, the icon will be displayed on the right side.
   */
  trailing?: boolean | undefined;
  /**
   * The content of the menu.
   */
  content?: (Omit<ComboboxContentProps, "as" | "asChild" | "forceMount"> & Partial<EmitsToProps<DismissableLayerEmits>>) | undefined;
  /**
   * When `true`, the loading icon will be displayed.
   */
  loading?: boolean | undefined;
  size?: "md" | "xs" | "sm" | "lg" | "xl" | undefined;
  /**
   * Display an avatar on the left side.
   */
  avatar?: AvatarProps | undefined;
  variant?: "ghost" | "outline" | "soft" | "subtle" | "none" | undefined;
  autofocus?: boolean | undefined;
  /**
   * When `true`, prevents the user from interacting with listbox
   */
  disabled?: boolean | undefined;
  form?: string | undefined;
  formaction?: string | undefined;
  formenctype?: string | undefined;
  formmethod?: string | undefined;
  formnovalidate?: Booleanish | undefined;
  formtarget?: string | undefined;
  /**
   * When `true`, the icon will be displayed on the left side.
   */
  leading?: boolean | undefined;
  /**
   * Display an icon on the left side.
   */
  leadingIcon?: any;
  /**
   * The icon when the `loading` prop is `true`.
   */
  loadingIcon?: any;
  /**
   * Whether to reset the searchTerm when the Combobox input blurred
   */
  resetSearchTermOnBlur?: boolean | undefined;
  /**
   * Whether to reset the searchTerm when the Combobox value is selected
   */
  resetSearchTermOnSelect?: boolean | undefined;
  /**
   * When `true` the `modelValue` will be reset to `null` (or `[]` if `multiple`)
   */
  resetModelValueOnClear?: boolean | undefined;
  /**
   * When `true`, hover over item will trigger highlight
   */
  highlightOnHover?: boolean | undefined;
  /**
   * Use this to compare objects by a particular field, or pass your own comparison function for complete control over how objects are compared.
   */
  by?: string | ((a: SelectMenuItem[], b: SelectMenuItem[]) => boolean) | undefined;
  /**
   * The value of the SelectMenu when initially rendered. Use when you do not need to control the state of the SelectMenu.
   */
  defaultValue?: SelectMenuItem | undefined;
  /**
   * Whether multiple options can be selected or not.
   */
  multiple?: false | undefined;
  required?: boolean | undefined;
  id?: string | undefined;
  /**
   * The placeholder text when the select is empty.
   */
  placeholder?: string | undefined;
  /**
   * Whether to display the search input or not.
   * Can be an object to pass additional props to the input.
   * `{ placeholder: 'Search...', variant: 'none' }`{lang="ts-type"}
   * @default "false"
   */
  searchInput?: boolean | Omit<InputProps<AcceptableValue, ModelModifiers>, "modelValue" | "defaultValue"> | undefined;
  /**
   * The icon displayed when an item is selected.
   */
  selectedIcon?: any;
  /**
   * Display a clear button to reset the model value.
   * Can be an object to pass additional props to the Button.
   */
  clear?: false | (false & Partial<Omit<ButtonProps, LinkPropsKeys>>) | undefined;
  /**
   * The icon displayed in the clear button.
   */
  clearIcon?: any;
  /**
   * Display an arrow alongside the menu.
   * `{ rounded: true }`{lang="ts-type"}
   */
  arrow?: boolean | Omit<ComboboxArrowProps, "as" | "asChild"> | undefined;
  /**
   * Render the menu in a portal.
   */
  portal?: string | boolean | HTMLElement | undefined;
  /**
   * Enable virtualization for large lists.
   * Note: when enabled, all groups are flattened into a single list due to a limitation of Reka UI (https://github.com/unovue/reka-ui/issues/1885).
   */
  virtualize?: boolean | { overscan?: number | undefined; estimateSize?: number | ((index: number) => number) | undefined; } | undefined;
  /**
   * When `items` is an array of objects, select the field to use as the value instead of the object itself.
   */
  valueKey?: undefined;
  /**
   * When `items` is an array of objects, select the field to use as the label.
   */
  labelKey?: string | undefined;
  /**
   * When `items` is an array of objects, select the field to use as the description.
   */
  descriptionKey?: string | undefined;
  modelModifiers?: Omit<ModelModifiers, "lazy"> | undefined;
  /**
   * Determines if custom user input that does not exist in options can be added.
   */
  createItem?: boolean | "always" | { position?: "top" | "bottom" | undefined; when?: "empty" | "always" | undefined; } | undefined;
  /**
   * Fields to filter items by.
   */
  filterFields?: string[] | undefined;
  /**
   * When `true`, disable the default filters, useful for custom filtering (useAsyncData, useFetch, etc.).
   */
  ignoreFilter?: boolean | undefined;
  autofocusDelay?: number | undefined;
}
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/color-mode/ColorModeSelect.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/color-mode/color-mode-select.ts).


# ColorModeSwitch

## Uso

O componente ColorModeSwitch estende o componente [Switch](https://ui.nitro.news/docs/components/switch), então você pode passar qualquer propriedade como `color`, `size`, etc.

```vue
<template>
  <UColorModeSwitch />
</template>
```

## Exemplos

### Com ícones personalizados

**Nuxt:**

Use o `app.config.ts` para personalizar o ícone com a propriedade `ui.icons`:

```ts [app/app.config.ts]
export default defineAppConfig({
  ui: {
    icons: {
      light: 'i-ph-sun',
      dark: 'i-ph-moon'
    }
  }
})
```

**Vue:**

Use o `vite.config.ts` para personalizar o ícone com a propriedade `ui.icons`:

```ts [vite.config.ts]
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nitro/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      ui: {
        icons: {
          light: 'i-ph-sun',
          dark: 'i-ph-moon'
        }
      }
    })
  ]
})
```

## API

### Props

```ts
/**
 * Props for the ColorModeSwitch component
 */
interface ColorModeSwitchProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  color?: "primary" | "secondary" | "accent" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
  /**
   * Highlight the ring color like a focus state.
   */
  highlight?: boolean | undefined;
  ui?: { root?: SlotClass; base?: SlotClass; container?: SlotClass; thumb?: SlotClass; icon?: SlotClass; wrapper?: SlotClass; label?: SlotClass; description?: SlotClass; } | undefined;
  /**
   * The name of the field. Submitted with its owning form as part of a name/value pair.
   */
  name?: string | undefined;
  /**
   * When `true`, the loading icon will be displayed.
   */
  loading?: boolean | undefined;
  size?: "md" | "xs" | "sm" | "lg" | "xl" | undefined;
  autofocus?: Booleanish | undefined;
  /**
   * When `true`, prevents the user from interacting with the switch.
   */
  disabled?: boolean | undefined;
  form?: string | undefined;
  formaction?: string | undefined;
  formenctype?: string | undefined;
  formmethod?: string | undefined;
  formnovalidate?: Booleanish | undefined;
  formtarget?: string | undefined;
  label?: string | undefined;
  /**
   * The icon when the `loading` prop is `true`.
   */
  loadingIcon?: any;
  /**
   * The state of the switch when it is initially rendered. Use when you do not need to control its state.
   */
  defaultValue?: boolean | undefined;
  /**
   * When `true`, indicates that the user must set the value before the owning form can be submitted.
   */
  required?: boolean | undefined;
  id?: string | undefined;
  /**
   * The value given as data when submitted with a `name`.
   */
  value?: string | undefined;
  description?: string | undefined;
  /**
   * The value used when the switch is on. Defaults to `true`.
   */
  trueValue?: boolean | undefined;
  /**
   * The value used when the switch is off. Defaults to `false`.
   */
  falseValue?: boolean | undefined;
}
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/color-mode/ColorModeSwitch.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/color-mode/color-mode-switch.ts).


# ColorPicker

## Uso

Use a diretiva `v-model` para controlar o valor do ColorPicker.

```vue
<script setup lang="ts">
const value = ref("#00C16A")
</script>

<template>
  <UColorPicker v-model="value" />
</template>
```

Use a prop `default-value` para definir o valor inicial quando você não precisa controlar o estado.

```vue
<template>
  <UColorPicker default-value="#00BCD4" />
</template>
```

### Formato RGB

Use a prop `format` para definir o valor `rgb` do ColorPicker.

```vue
<script setup lang="ts">
const value = ref("rgb(0, 193, 106)")
</script>

<template>
  <UColorPicker format="rgb" v-model="value" />
</template>
```

### Formato HSL

Use a prop `format` para definir o valor `hsl` do ColorPicker.

```vue
<script setup lang="ts">
const value = ref("hsl(153, 100%, 37.8%)")
</script>

<template>
  <UColorPicker format="hsl" v-model="value" />
</template>
```

### Formato CMYK

Use a prop `format` para definir o valor `cmyk` do ColorPicker.

```vue
<script setup lang="ts">
const value = ref("cmyk(100%, 0%, 45.08%, 24.31%)")
</script>

<template>
  <UColorPicker format="cmyk" v-model="value" />
</template>
```

### Formato CIELab

Use a prop `format` para definir o valor `lab` do ColorPicker.

```vue
<script setup lang="ts">
const value = ref("lab(68.88% -60.41% 32.55%)")
</script>

<template>
  <UColorPicker format="lab" v-model="value" />
</template>
```

### Throttle

Use a prop `throttle` para definir o valor de throttle do ColorPicker.

```vue
<script setup lang="ts">
const value = ref("#00C16A")
</script>

<template>
  <UColorPicker :throttle="100" v-model="value" />
</template>
```

### Tamanho

Use a prop `size` para definir o tamanho do ColorPicker.

```vue
<template>
  <UColorPicker size="xl" />
</template>
```

### Desabilitado

Use a prop `disabled` para desabilitar o ColorPicker.

```vue
<template>
  <UColorPicker disabled />
</template>
```

## Exemplos

### Como seletor de cores

Use a [Button](https://ui.nitro.news/docs/components/button) and a [Popover](https://ui.nitro.news/docs/components/popover) component to create a color chooser.

:component-example{name="color-picker-chooser-example"}

## API

### Props

```ts
/**
 * Props for the ColorPicker component
 */
interface ColorPickerProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  /**
   * Throttle time in ms for the color picker
   * @default "50"
   */
  throttle?: number | undefined;
  /**
   * Disable the color picker
   */
  disabled?: boolean | undefined;
  /**
   * The default value of the color picker
   * @default "\"#FFFFFF\""
   */
  defaultValue?: string | undefined;
  /**
   * Format of the color
   * @default "\"hex\""
   */
  format?: "hex" | "rgb" | "hsl" | "cmyk" | "lab" | undefined;
  size?: "xs" | "sm" | "md" | "lg" | "xl" | undefined;
  ui?: { root?: SlotClass; picker?: SlotClass; selector?: SlotClass; selectorBackground?: SlotClass; selectorThumb?: SlotClass; track?: SlotClass; trackThumb?: SlotClass; } | undefined;
  modelValue?: string | undefined;
}
```

### Emits

```ts
/**
 * Emitted events for the ColorPicker component
 */
interface ColorPickerEmits {
  update:modelValue: (payload: [value: string | undefined]) => void;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    colorPicker: {
      slots: {
        root: 'data-[disabled]:opacity-75',
        picker: 'flex gap-4',
        selector: 'rounded-md touch-none',
        selectorBackground: 'w-full h-full relative rounded-md',
        selectorThumb: '-translate-y-1/2 -translate-x-1/2 absolute size-4 ring-2 ring-white rounded-full cursor-pointer data-[disabled]:cursor-not-allowed',
        track: 'w-[8px] relative rounded-md touch-none',
        trackThumb: 'absolute transform -translate-y-1/2 -translate-x-[4px] rtl:translate-x-[4px] size-4 rounded-full ring-2 ring-white cursor-pointer data-[disabled]:cursor-not-allowed'
      },
      variants: {
        size: {
          xs: {
            selector: 'w-38 h-38',
            track: 'h-38'
          },
          sm: {
            selector: 'w-40 h-40',
            track: 'h-40'
          },
          md: {
            selector: 'w-42 h-42',
            track: 'h-42'
          },
          lg: {
            selector: 'w-44 h-44',
            track: 'h-44'
          },
          xl: {
            selector: 'w-46 h-46',
            track: 'h-46'
          }
        }
      },
      compoundVariants: [],
      defaultVariants: {
        size: 'md'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/ColorPicker.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/color-picker.ts).


# CommandPalette

## Uso

Use a diretiva `v-model` para controlar o valor do CommandPalette ou a prop `default-value` para definir o valor inicial quando você não precisa controlar o estado.

```vue
<script setup lang="ts">
import type { CommandPaletteGroup } from '@nitro/ui'

const groups = ref<CommandPaletteGroup[]>([
  {
    id: "users",
    label: "Users",
    items: [
      {
        label: "Benjamin Canac",
        suffix: "benjamincanac",
        avatar: {
          src: "https://github.com/benjamincanac.png",
          loading: "lazy"
        }
      },
      {
        label: "Romain Hamel",
        suffix: "romhml",
        avatar: {
          src: "https://github.com/romhml.png",
          loading: "lazy"
        }
      },
      {
        label: "Sébastien Chopin",
        suffix: "atinux",
        avatar: {
          src: "https://github.com/atinux.png",
          loading: "lazy"
        }
      },
      {
        label: "Hugo Richard",
        suffix: "HugoRCD",
        avatar: {
          src: "https://github.com/HugoRCD.png",
          loading: "lazy"
        }
      },
      {
        label: "Sandro Circi",
        suffix: "sandros94",
        avatar: {
          src: "https://github.com/sandros94.png",
          loading: "lazy"
        }
      },
      {
        label: "Daniel Roe",
        suffix: "danielroe",
        avatar: {
          src: "https://github.com/danielroe.png",
          loading: "lazy"
        }
      },
      {
        label: "Jakub Michálek",
        suffix: "J-Michalek",
        avatar: {
          src: "https://github.com/J-Michalek.png",
          loading: "lazy"
        }
      },
      {
        label: "Eugen Istoc",
        suffix: "genu",
        avatar: {
          src: "https://github.com/genu.png",
          loading: "lazy"
        }
      }
    ]
  }
])
const value = ref({})
</script>

<template>
  <UCommandPalette v-model="value" :groups="groups" class="flex-1 h-80" />
</template>
```

> \[!TIP]
> See: #control-selected-items
>
> Você também pode usar o evento `@update:model-value` para escutar o(s) item(ns) selecionado(s).

### Grupos

O componente CommandPalette filtra os grupos e classifica os comandos correspondentes por relevância conforme o usuário digita. Ele oferece resultados de busca dinâmicos e instantâneos para uma descoberta de comandos eficiente. Use a prop `groups` como um array de objetos com as seguintes propriedades:

- `id: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `label?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `slot?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `items?: CommandPaletteItem[]`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- [`ignoreFilter?: boolean`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}](https://ui.nitro.news/#with-ignore-filter)
- [`postFilter?: (searchTerm: string, items: T[]) => T[]`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}](https://ui.nitro.news/#with-post-filtered-items)
- `highlightedIcon?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

> \[!CAUTION]
>
> Você precisa fornecer um `id` para cada grupo, caso contrário o grupo será ignorado.

Cada grupo contém um array `items` de objetos que definem os comandos. Cada item pode ter as seguintes propriedades:

- `prefix?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `label?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `suffix?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `icon?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `avatar?: AvatarProps`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `chip?: ChipProps`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `kbds?: string[] | KbdProps[]`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `active?: boolean`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `loading?: boolean`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `disabled?: boolean`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- [`slot?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}](https://ui.nitro.news/#with-custom-slot)
- `placeholder?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `children?: CommandPaletteItem[]`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `onSelect?: (e: Event) => void`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `class?: any`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `ui?: { item?: ClassNameValue, itemLeadingIcon?: ClassNameValue, itemLeadingAvatarSize?: ClassNameValue, itemLeadingAvatar?: ClassNameValue, itemLeadingChipSize?: ClassNameValue, itemLeadingChip?: ClassNameValue, itemLabel?: ClassNameValue, itemLabelPrefix?: ClassNameValue, itemLabelBase?: ClassNameValue, itemLabelSuffix?: ClassNameValue, itemTrailing?: ClassNameValue, itemTrailingKbds?: ClassNameValue, itemTrailingKbdsSize?: ClassNameValue, itemTrailingHighlightedIcon?: ClassNameValue, itemTrailingIcon?: ClassNameValue }`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Você pode passar qualquer propriedade do componente [Link](https://ui.nitro.news/docs/components/link#props), como `to`, `target`, etc.

```vue
<script setup lang="ts">
import type { CommandPaletteGroup } from '@nitro/ui'

const groups = ref<CommandPaletteGroup[]>([
  {
    id: "users",
    label: "Users",
    items: [
      {
        label: "Benjamin Canac",
        suffix: "benjamincanac",
        avatar: {
          src: "https://github.com/benjamincanac.png",
          loading: "lazy"
        }
      },
      {
        label: "Romain Hamel",
        suffix: "romhml",
        avatar: {
          src: "https://github.com/romhml.png",
          loading: "lazy"
        }
      },
      {
        label: "Sébastien Chopin",
        suffix: "atinux",
        avatar: {
          src: "https://github.com/atinux.png",
          loading: "lazy"
        }
      },
      {
        label: "Hugo Richard",
        suffix: "HugoRCD",
        avatar: {
          src: "https://github.com/HugoRCD.png",
          loading: "lazy"
        }
      },
      {
        label: "Sandro Circi",
        suffix: "sandros94",
        avatar: {
          src: "https://github.com/sandros94.png",
          loading: "lazy"
        }
      },
      {
        label: "Daniel Roe",
        suffix: "danielroe",
        avatar: {
          src: "https://github.com/danielroe.png",
          loading: "lazy"
        }
      },
      {
        label: "Jakub Michálek",
        suffix: "J-Michalek",
        avatar: {
          src: "https://github.com/J-Michalek.png",
          loading: "lazy"
        }
      },
      {
        label: "Eugen Istoc",
        suffix: "genu",
        avatar: {
          src: "https://github.com/genu.png",
          loading: "lazy"
        }
      }
    ]
  }
])
const value = ref({})
</script>

<template>
  <UCommandPalette v-model="value" :groups="groups" class="flex-1" />
</template>
```

> \[!TIP]
> See: #with-children-in-items
>
> Cada item pode receber um array `children` de objetos com as seguintes propriedades para criar submenus:

### Múltiplo

Use a prop `multiple` para permitir múltiplas seleções.

```vue
<script setup lang="ts">
import type { CommandPaletteGroup } from '@nitro/ui'

const groups = ref<CommandPaletteGroup[]>([
  {
    id: "users",
    label: "Users",
    items: [
      {
        label: "Benjamin Canac",
        suffix: "benjamincanac",
        avatar: {
          src: "https://github.com/benjamincanac.png",
          loading: "lazy"
        }
      },
      {
        label: "Romain Hamel",
        suffix: "romhml",
        avatar: {
          src: "https://github.com/romhml.png",
          loading: "lazy"
        }
      },
      {
        label: "Sébastien Chopin",
        suffix: "atinux",
        avatar: {
          src: "https://github.com/atinux.png",
          loading: "lazy"
        }
      },
      {
        label: "Hugo Richard",
        suffix: "HugoRCD",
        avatar: {
          src: "https://github.com/HugoRCD.png",
          loading: "lazy"
        }
      },
      {
        label: "Sandro Circi",
        suffix: "sandros94",
        avatar: {
          src: "https://github.com/sandros94.png",
          loading: "lazy"
        }
      },
      {
        label: "Daniel Roe",
        suffix: "danielroe",
        avatar: {
          src: "https://github.com/danielroe.png",
          loading: "lazy"
        }
      },
      {
        label: "Jakub Michálek",
        suffix: "J-Michalek",
        avatar: {
          src: "https://github.com/J-Michalek.png",
          loading: "lazy"
        }
      },
      {
        label: "Eugen Istoc",
        suffix: "genu",
        avatar: {
          src: "https://github.com/genu.png",
          loading: "lazy"
        }
      }
    ]
  }
])
const value = ref([])
</script>

<template>
  <UCommandPalette multiple v-model="value" :groups="groups" class="flex-1" />
</template>
```

> \[!CAUTION]
>
> Certifique-se de passar um array para a prop `default-value` ou para a diretiva `v-model`.

### Placeholder

Use a prop `placeholder` para alterar o texto de placeholder.

```vue
<script setup lang="ts">
import type { CommandPaletteGroup } from '@nitro/ui'

const groups = ref<CommandPaletteGroup[]>([
  {
    id: "apps",
    items: [
      {
        label: "Calendar",
        icon: "i-lucide-calendar"
      },
      {
        label: "Music",
        icon: "i-lucide-music"
      },
      {
        label: "Maps",
        icon: "i-lucide-map"
      }
    ]
  }
])
</script>

<template>
  <UCommandPalette placeholder="Search an app..." :groups="groups" class="flex-1" />
</template>
```

### Tamanho `4.4+`

Use a prop `size` para alterar o tamanho do CommandPalette.

```vue
<script setup lang="ts">
import type { CommandPaletteGroup } from '@nitro/ui'

const groups = ref<CommandPaletteGroup[]>([
  {
    id: "apps",
    items: [
      {
        label: "Calendar",
        icon: "i-lucide-calendar"
      },
      {
        label: "Music",
        icon: "i-lucide-music"
      },
      {
        label: "Maps",
        icon: "i-lucide-map"
      }
    ]
  }
])
</script>

<template>
  <UCommandPalette size="xl" :groups="groups" class="flex-1" />
</template>
```

### Ícone

Use a prop `icon` para personalizar o [Icon](https://ui.nitro.news/docs/components/icon) do input. O padrão é `i-lucide-search`.

```vue
<script setup lang="ts">
import type { CommandPaletteGroup } from '@nitro/ui'

const groups = ref<CommandPaletteGroup[]>([
  {
    id: "apps",
    items: [
      {
        label: "Calendar",
        icon: "i-lucide-calendar"
      },
      {
        label: "Music",
        icon: "i-lucide-music"
      },
      {
        label: "Maps",
        icon: "i-lucide-map"
      }
    ]
  }
])
</script>

<template>
  <UCommandPalette icon="i-lucide-box" :groups="groups" class="flex-1" />
</template>
```

**Nuxt:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/nuxt#theme
>
> Você pode personalizar esse ícone globalmente no seu `app.config.ts` na chave `ui.icons.search`.

**Vue:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/vue#theme
>
> Você pode personalizar esse ícone globalmente no seu `vite.config.ts` na chave `ui.icons.search`.

### Ícone de selecionado

Use a prop `selected-icon` para personalizar o [Icon](https://ui.nitro.news/docs/components/icon) do item selecionado. O padrão é `i-lucide-check`.

```vue
<script setup lang="ts">
import type { CommandPaletteGroup } from '@nitro/ui'

const groups = ref<CommandPaletteGroup[]>([
  {
    id: "users",
    label: "Users",
    items: [
      {
        label: "Benjamin Canac",
        suffix: "benjamincanac",
        avatar: {
          src: "https://github.com/benjamincanac.png",
          loading: "lazy"
        }
      },
      {
        label: "Romain Hamel",
        suffix: "romhml",
        avatar: {
          src: "https://github.com/romhml.png",
          loading: "lazy"
        }
      },
      {
        label: "Sébastien Chopin",
        suffix: "atinux",
        avatar: {
          src: "https://github.com/atinux.png",
          loading: "lazy"
        }
      },
      {
        label: "Hugo Richard",
        suffix: "HugoRCD",
        avatar: {
          src: "https://github.com/HugoRCD.png",
          loading: "lazy"
        }
      },
      {
        label: "Sandro Circi",
        suffix: "sandros94",
        avatar: {
          src: "https://github.com/sandros94.png",
          loading: "lazy"
        }
      },
      {
        label: "Daniel Roe",
        suffix: "danielroe",
        avatar: {
          src: "https://github.com/danielroe.png",
          loading: "lazy"
        }
      },
      {
        label: "Jakub Michálek",
        suffix: "J-Michalek",
        avatar: {
          src: "https://github.com/J-Michalek.png",
          loading: "lazy"
        }
      },
      {
        label: "Eugen Istoc",
        suffix: "genu",
        avatar: {
          src: "https://github.com/genu.png",
          loading: "lazy"
        }
      }
    ]
  }
])
const value = ref([
  {
    label: "Benjamin Canac",
    suffix: "benjamincanac",
    avatar: {
      src: "https://github.com/benjamincanac.png",
      loading: "lazy"
    }
  }
])
</script>

<template>
  <UCommandPalette multiple v-model="value" selected-icon="i-lucide-circle-check" :groups="groups" class="flex-1" />
</template>
```

**Nuxt:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/nuxt#theme
>
> Você pode personalizar esse ícone globalmente no seu `app.config.ts` na chave `ui.icons.check`.

**Vue:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/vue#theme
>
> Você pode personalizar esse ícone globalmente no seu `vite.config.ts` na chave `ui.icons.check`.

### Ícone à direita

Use a prop `trailing-icon` para personalizar o [Icon](https://ui.nitro.news/docs/components/icon) à direita quando um item tem filhos. O padrão é `i-lucide-chevron-right`.

```vue
<script setup lang="ts">
import type { CommandPaletteGroup } from '@nitro/ui'

const groups = ref<CommandPaletteGroup[]>([
  {
    id: "actions",
    items: [
      {
        label: "Share",
        icon: "i-lucide-share",
        children: [
          {
            label: "Email",
            icon: "i-lucide-mail"
          },
          {
            label: "Copy",
            icon: "i-lucide-copy"
          },
          {
            label: "Link",
            icon: "i-lucide-link"
          }
        ]
      }
    ]
  }
])
</script>

<template>
  <UCommandPalette trailing-icon="i-lucide-arrow-right" :groups="groups" class="flex-1" />
</template>
```

**Nuxt:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/nuxt#theme
>
> Você pode personalizar esse ícone globalmente no seu `app.config.ts` na chave `ui.icons.chevronRight`.

**Vue:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/vue#theme
>
> Você pode personalizar esse ícone globalmente no seu `vite.config.ts` na chave `ui.icons.chevronRight`.

### Carregando

Use a prop `loading` para exibir um ícone de carregamento no CommandPalette.

```vue
<script setup lang="ts">
import type { CommandPaletteGroup } from '@nitro/ui'

const groups = ref<CommandPaletteGroup[]>([
  {
    id: "apps",
    items: [
      {
        label: "Calendar",
        icon: "i-lucide-calendar"
      },
      {
        label: "Music",
        icon: "i-lucide-music"
      },
      {
        label: "Maps",
        icon: "i-lucide-map"
      }
    ]
  }
])
</script>

<template>
  <UCommandPalette loading :groups="groups" class="flex-1" />
</template>
```

### Ícone de carregamento

Use a prop `loading-icon` para personalizar o ícone de carregamento. O padrão é `i-lucide-loader-circle`.

```vue
<script setup lang="ts">
import type { CommandPaletteGroup } from '@nitro/ui'

const groups = ref<CommandPaletteGroup[]>([
  {
    id: "apps",
    items: [
      {
        label: "Calendar",
        icon: "i-lucide-calendar"
      },
      {
        label: "Music",
        icon: "i-lucide-music"
      },
      {
        label: "Maps",
        icon: "i-lucide-map"
      }
    ]
  }
])
</script>

<template>
  <UCommandPalette loading loading-icon="i-lucide-loader" :groups="groups" class="flex-1" />
</template>
```

**Nuxt:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/nuxt#theme
>
> Você pode personalizar esse ícone globalmente no seu `app.config.ts` na chave `ui.icons.loading`.

**Vue:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/vue#theme
>
> Você pode personalizar esse ícone globalmente no seu `vite.config.ts` na chave `ui.icons.loading`.

### Fechar

Use a prop `close` para exibir um [Button](https://ui.nitro.news/docs/components/button) para dispensar o CommandPalette.

> \[!TIP]
>
> Um evento `update:open` será emitido quando o botão de fechar for clicado.

```vue
<script setup lang="ts">
import type { CommandPaletteGroup } from '@nitro/ui'

const groups = ref<CommandPaletteGroup[]>([
  {
    id: "apps",
    items: [
      {
        label: "Calendar",
        icon: "i-lucide-calendar"
      },
      {
        label: "Music",
        icon: "i-lucide-music"
      },
      {
        label: "Maps",
        icon: "i-lucide-map"
      }
    ]
  }
])
</script>

<template>
  <UCommandPalette close :groups="groups" class="flex-1" />
</template>
```

Você pode passar qualquer propriedade do componente [Button](https://ui.nitro.news/docs/components/button) para personalizá-lo.

```vue
<script setup lang="ts">
import type { CommandPaletteGroup } from '@nitro/ui'

const groups = ref<CommandPaletteGroup[]>([
  {
    id: "apps",
    items: [
      {
        label: "Calendar",
        icon: "i-lucide-calendar"
      },
      {
        label: "Music",
        icon: "i-lucide-music"
      },
      {
        label: "Maps",
        icon: "i-lucide-map"
      }
    ]
  }
])
</script>

<template>
  <UCommandPalette :close="{
  color: 'primary',
  variant: 'outline',
  class: 'rounded-full'
}" :groups="groups" class="flex-1" />
</template>
```

### Ícone de fechar

Use a prop `close-icon` para personalizar o [Icon](https://ui.nitro.news/docs/components/icon) do botão de fechar. O padrão é `i-lucide-x`.

```vue
<script setup lang="ts">
import type { CommandPaletteGroup } from '@nitro/ui'

const groups = ref<CommandPaletteGroup[]>([
  {
    id: "apps",
    items: [
      {
        label: "Calendar",
        icon: "i-lucide-calendar"
      },
      {
        label: "Music",
        icon: "i-lucide-music"
      },
      {
        label: "Maps",
        icon: "i-lucide-map"
      }
    ]
  }
])
</script>

<template>
  <UCommandPalette close close-icon="i-lucide-arrow-right" :groups="groups" class="flex-1" />
</template>
```

**Nuxt:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/nuxt#theme
>
> Você pode personalizar esse ícone globalmente no seu `app.config.ts` na chave `ui.icons.close`.

**Vue:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/vue#theme
>
> Você pode personalizar esse ícone globalmente no seu `vite.config.ts` na chave `ui.icons.close`.

### Voltar

Use a prop `back` para personalizar ou ocultar o botão de voltar (com o valor `false`) exibido ao navegar para dentro de um submenu.

Você pode passar qualquer propriedade do componente [Button](https://ui.nitro.news/docs/components/button) para personalizá-lo.

```vue
<script setup lang="ts">
import type { CommandPaletteGroup } from '@nitro/ui'

const groups = ref<CommandPaletteGroup[]>([
  {
    id: "actions",
    items: [
      {
        label: "Share",
        icon: "i-lucide-share",
        children: [
          {
            label: "Email",
            icon: "i-lucide-mail"
          },
          {
            label: "Copy",
            icon: "i-lucide-copy"
          },
          {
            label: "Link",
            icon: "i-lucide-link"
          }
        ]
      }
    ]
  }
])
</script>

<template>
  <UCommandPalette :back="{
  color: 'primary'
}" :groups="groups" class="flex-1" />
</template>
```

### Ícone de voltar

Use a prop `back-icon` para personalizar o [Icon](https://ui.nitro.news/docs/components/icon) do botão de voltar. O padrão é `i-lucide-arrow-left`.

```vue
<script setup lang="ts">
import type { CommandPaletteGroup } from '@nitro/ui'

const groups = ref<CommandPaletteGroup[]>([
  {
    id: "actions",
    items: [
      {
        label: "Share",
        icon: "i-lucide-share",
        children: [
          {
            label: "Email",
            icon: "i-lucide-mail"
          },
          {
            label: "Copy",
            icon: "i-lucide-copy"
          },
          {
            label: "Link",
            icon: "i-lucide-link"
          }
        ]
      }
    ]
  }
])
</script>

<template>
  <UCommandPalette back back-icon="i-lucide-house" :groups="groups" class="flex-1" />
</template>
```

**Nuxt:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/nuxt#theme
>
> Você pode personalizar esse ícone globalmente no seu `app.config.ts` na chave `ui.icons.arrowLeft`.

**Vue:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/vue#theme
>
> Você pode personalizar esse ícone globalmente no seu `vite.config.ts` na chave `ui.icons.arrowLeft`.

### Desabilitado

Use a prop `disabled` para desabilitar o CommandPalette.

```vue
<script setup lang="ts">
import type { CommandPaletteGroup } from '@nitro/ui'

const groups = ref<CommandPaletteGroup[]>([
  {
    id: "apps",
    items: [
      {
        label: "Calendar",
        icon: "i-lucide-calendar"
      },
      {
        label: "Music",
        icon: "i-lucide-music"
      },
      {
        label: "Maps",
        icon: "i-lucide-map"
      }
    ]
  }
])
</script>

<template>
  <UCommandPalette disabled :groups="groups" class="flex-1" />
</template>
```

## Exemplos

### Controlar o(s) item(ns) selecionado(s)

Você pode controlar o(s) item(ns) selecionado(s) usando a prop `default-value` ou a diretiva `v-model`, usando o campo `onSelect` em cada item ou usando o evento `@update:model-value`.

::component-example
---
collapse: true
props:
  autofocus: false
class: "!p-0"
name: command-palette-select-example
---
::

> \[!TIP]
>
> Use a prop `value-key` para selecionar um campo de um item para usar como valor em vez do objeto em si. Use a prop `by` para comparar objetos por um campo em vez de por referência.

### Controlar o termo de busca

Use a diretiva `v-model:search-term` para controlar o termo de busca.

::component-example
---
collapse: true
props:
  autofocus: false
class: "!p-0"
name: command-palette-search-term-example
---
::

> \[!NOTE]
>
> Este exemplo usa o evento `@update:model-value` para redefinir o termo de busca quando um item é selecionado.

### Com filhos nos itens

Você pode criar menus hierárquicos usando a propriedade `children` nos itens. Quando um item tem filhos, ele exibe automaticamente um ícone de chevron e habilita a navegação para dentro de um submenu.

::component-example
---
collapse: true
prettier: true
props:
  autofocus: false
class: "!p-0"
name: command-palette-items-children-example
---
::

> \[!NOTE]
>
> Ao navegar para dentro de um submenu:
>
> - The search term is reset
> - A back button appears in the input
> - You can go back to the previous group by pressing the :kbd{value="backspace"} key

### Com itens buscados

Você pode buscar itens de uma API e usá-los no CommandPalette.

::component-example
---
collapse: true
props:
  autofocus: false
class: "!p-0"
name: command-palette-fetch-example
---
::

> \[!NOTE]
>
> Este exemplo usa `useLazyFetch` com `server: false` para buscar os dados no cliente sem bloquear a renderização inicial. O estado de carregamento verifica os status `pending` e `idle` para exibir um indicador de carregamento antes e durante a busca.

### Com filtro ignorado

Você pode definir o campo `ignoreFilter` como `true` em um grupo para desabilitar a busca interna e usar sua própria lógica de busca.

::component-example
---
collapse: true
props:
  autofocus: false
class: "!p-0"
name: command-palette-ignore-filter-example
---
::

> \[!NOTE]
>
> Este exemplo usa [`refDebounced`](https://vueuse.org/shared/refDebounced/#refdebounced){rel="&#x22;nofollow&#x22;"} para aplicar debounce nas chamadas de API. O estado de carregamento verifica os status `pending` e `idle` para exibir um indicador de carregamento antes e durante a busca.

### Com itens pós-filtrados

Você pode usar o campo `postFilter` em um grupo para filtrar os itens depois que a busca aconteceu.

::component-example
---
collapse: true
props:
  autofocus: false
class: "!p-0"
name: command-palette-post-filter-example
---
::

> \[!NOTE]
>
> Comece a digitar para ver os itens de nível mais alto aparecerem.

### Com busca fuse personalizada

Você pode usar a prop `fuse` para sobrescrever as opções do [useFuse](https://vueuse.org/integrations/useFuse){rel="&#x22;nofollow&#x22;"}, cujo padrão é:

```ts
{
  fuseOptions: {
    ignoreLocation: true,
    threshold: 0.1,
    keys: ['label', 'description', 'suffix']
  },
  resultLimit: 12,
  matchAllWhenSearchEmpty: true
}
```

> \[!TIP]
>
> As `fuseOptions` são as opções do [Fuse.js](https://www.fusejs.io/api/options.html){rel="&#x22;nofollow&#x22;"}, o `resultLimit` é o número máximo de resultados a retornar e o `matchAllWhenSearchEmpty` é um booleano para corresponder a todos os itens quando o termo de busca está vazio.

Você pode, por exemplo, definir `{ fuseOptions: { includeMatches: true } }`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} para destacar o termo de busca nos itens.

::component-example
---
collapse: true
props:
  autofocus: false
class: "!p-0"
name: command-palette-fuse-example
---
::

### Com virtualização `4.1+`

Use a prop `virtualize` para habilitar a virtualização em listas grandes, como um booleano ou um objeto com opções como `{ estimateSize: 32, overscan: 12 }`.

> \[!WARNING]
> See: https\://github.com/unovue/reka-ui/issues/1885
>
> Quando habilitado, todos os grupos são achatados em uma única lista devido a uma limitação do Reka UI.

::component-example
---
collapse: true
props:
  autofocus: false
class: "!p-0"
name: command-palette-virtualize-example
---
::

### Dentro de um Popover

Você pode usar o componente CommandPalette dentro do conteúdo de um [Popover](https://ui.nitro.news/docs/components/popover).

::component-example
---
collapse: true
props:
  autofocus: false
name: popover-command-palette-example
---
::

### Dentro de um Modal

Você pode usar o componente CommandPalette dentro do conteúdo de um [Modal](https://ui.nitro.news/docs/components/modal).

::component-example
---
collapse: true
props:
  autofocus: false
name: modal-command-palette-example
---
::

> \[!NOTE]
>
> Este exemplo usa `useLazyFetch` com `immediate: false` para buscar os dados apenas quando o Modal abre.

### Dentro de um Drawer

Você pode usar o componente CommandPalette dentro do conteúdo de um [Drawer](https://ui.nitro.news/docs/components/drawer).

::component-example
---
collapse: true
props:
  autofocus: false
name: drawer-command-palette-example
---
::

> \[!NOTE]
>
> Este exemplo usa `useLazyFetch` com `immediate: false` para buscar os dados apenas quando o Drawer abre.

### Escutar o estado de abertura

Ao usar a prop `close`, você pode escutar o evento `update:open` quando o botão é clicado.

::component-example
---
collapse: true
props:
  autofocus: false
name: command-palette-open-example
---
::

> \[!NOTE]
>
> Isso pode ser útil ao usar o CommandPalette dentro de um [`Modal`](https://ui.nitro.news/docs/components/modal), por exemplo.

### Com slot de rodapé

Use o slot `#footer` para adicionar conteúdo personalizado na parte inferior do CommandPalette, como ajuda de atalhos de teclado ou ações adicionais.

::component-example
---
collapse: true
props:
  autofocus: false
class: "!p-0"
name: command-palette-footer-slot-example
---
::

### Com slot personalizado

Use a propriedade `slot` para personalizar um item ou grupo específico.

Você terá acesso aos seguintes slots:

- `#{{ item.slot }}`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `#{{ item.slot }}-leading`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `#{{ item.slot }}-label`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `#{{ item.slot }}-trailing`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `#{{ group.slot }}`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `#{{ group.slot }}-leading`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `#{{ group.slot }}-label`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `#{{ group.slot }}-trailing`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

::component-example
---
collapse: true
props:
  autofocus: false
class: "!p-0"
name: command-palette-custom-slot-example
---
::

> \[!TIP]
> See: #slots
>
> Você também pode usar os slots `#item`, `#item-leading`, `#item-label` e `#item-trailing` para personalizar todos os itens.

## API

### Props

```ts
/**
 * Props for the CommandPalette component
 */
interface CommandPaletteProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  size?: "sm" | "md" | "xs" | "lg" | "xl" | undefined;
  /**
   * The icon displayed in the input. Set to `false` to hide the icon.
   */
  icon?: any;
  /**
   * The icon displayed on the right side of the input.
   */
  trailingIcon?: any;
  /**
   * The icon displayed when an item is selected.
   */
  selectedIcon?: any;
  /**
   * The icon displayed when an item has children.
   */
  childrenIcon?: any;
  /**
   * The placeholder text for the input.
   */
  placeholder?: string | undefined;
  /**
   * Automatically focus the input when component is mounted.
   * @default "true"
   */
  autofocus?: boolean | undefined;
  /**
   * Display a close button in the input (useful when inside a Modal for example).
   * `{ size: 'md', color: 'neutral', variant: 'ghost' }`{lang="ts-type"}
   */
  close?: boolean | Omit<ButtonProps, LinkPropsKeys> | undefined;
  /**
   * The icon displayed in the close button.
   */
  closeIcon?: any;
  /**
   * Display a button to navigate back in history.
   * `{ size: 'md', color: 'neutral', variant: 'link' }`{lang="ts-type"}
   * @default "true"
   */
  back?: boolean | Omit<ButtonProps, LinkPropsKeys> | undefined;
  /**
   * The icon displayed in the back button.
   */
  backIcon?: any;
  /**
   * Configure the input or hide it with `false`.
   * @default "true"
   */
  input?: boolean | Omit<InputProps<AcceptableValue, ModelModifiers>, "modelValue" | "defaultValue"> | undefined;
  groups?: G[] | undefined;
  /**
   * Options for [useFuse](https://vueuse.org/integrations/useFuse).
   */
  fuse?: UseFuseOptions<T> | undefined;
  /**
   * Enable virtualization for large lists.
   * Note: when enabled, all groups are flattened into a single list due to a limitation of Reka UI (https://github.com/unovue/reka-ui/issues/1885).
   * @default "false"
   */
  virtualize?: boolean | { overscan?: number | undefined; estimateSize?: number | ((index: number) => number) | undefined; } | undefined;
  /**
   * When `items` is an array of objects, select the field to use as the value instead of the object itself.
   */
  valueKey?: GetItemKeys<T> | undefined;
  /**
   * The key used to get the label from the item.
   * @default "\"label\""
   */
  labelKey?: GetItemKeys<T> | undefined;
  /**
   * The key used to get the description from the item.
   * @default "\"description\""
   */
  descriptionKey?: GetItemKeys<T> | undefined;
  /**
   * Whether to preserve the order of groups as defined in the `groups` prop when filtering.
   * When `false`, groups will appear based on item matches.
   * @default "false"
   */
  preserveGroupOrder?: boolean | undefined;
  /**
   * Delay (in milliseconds) before the search term is passed to Fuse (debounced).
   * Useful when indexing large datasets where fuzzy search becomes the bottleneck — the input stays responsive while Fuse and the result pipeline only re-run after typing settles.
   * Set to `0` (the default) to disable.
   * @default "0"
   */
  searchDelay?: number | undefined;
  ui?: { root?: SlotClass; input?: SlotClass; close?: SlotClass; back?: SlotClass; content?: SlotClass; footer?: SlotClass; viewport?: SlotClass; group?: SlotClass; empty?: SlotClass; label?: SlotClass; item?: SlotClass; itemLeadingIcon?: SlotClass; itemLeadingAvatar?: SlotClass; itemLeadingAvatarSize?: SlotClass; itemLeadingChip?: SlotClass; itemLeadingChipSize?: SlotClass; itemTrailing?: SlotClass; itemTrailingIcon?: SlotClass; itemTrailingHighlightedIcon?: SlotClass; itemTrailingKbds?: SlotClass; itemTrailingKbdsSize?: SlotClass; itemWrapper?: SlotClass; itemLabel?: SlotClass; itemLabelBase?: SlotClass; itemLabelPrefix?: SlotClass; itemLabelSuffix?: SlotClass; itemDescription?: SlotClass; } | undefined;
  /**
   * Whether multiple options can be selected or not.
   */
  multiple?: boolean | undefined;
  /**
   * When `true`, prevents the user from interacting with listbox
   */
  disabled?: boolean | undefined;
  /**
   * The controlled value of the listbox. Can be binded with `v-model`.
   */
  modelValue?: AcceptableValue | AcceptableValue[] | undefined;
  /**
   * The value of the listbox when initially rendered. Use when you do not need to control the state of the Listbox
   */
  defaultValue?: AcceptableValue | AcceptableValue[] | undefined;
  /**
   * When `true`, hover over item will trigger highlight
   * @default "true"
   */
  highlightOnHover?: boolean | undefined;
  /**
   * How multiple selection should behave in the collection.
   */
  selectionBehavior?: "replace" | "toggle" | undefined;
  /**
   * Use this to compare objects by a particular field, or pass your own comparison function for complete control over how objects are compared.
   */
  by?: string | ((a: AcceptableValue, b: AcceptableValue) => boolean) | undefined;
  /**
   * When `true`, the loading icon will be displayed.
   */
  loading?: boolean | undefined;
  /**
   * The icon when the `loading` prop is `true`.
   */
  loadingIcon?: any;
  /**
   * @default "\"\""
   */
  searchTerm?: string | undefined;
}
```

### Slots

```ts
/**
 * Slots for the CommandPalette component
 */
interface CommandPaletteSlots {
  empty(): any;
  footer(): any;
  back(): any;
  close(): any;
  item(): any;
  item-leading(): any;
  item-label(): any;
  item-description(): any;
  item-trailing(): any;
  group-label(): any;
}
```

### Emits

```ts
/**
 * Emitted events for the CommandPalette component
 */
interface CommandPaletteEmits {
  update:modelValue: (payload: [value: T]) => void;
  highlight: (payload: [payload: { ref: HTMLElement; value: T; } | undefined]) => void;
  entryFocus: (payload: [event: CustomEvent<any>]) => void;
  leave: (payload: [event: Event]) => void;
  update:open: (payload: [value: boolean]) => void;
  update:searchTerm: (payload: [value: string]) => void;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    commandPalette: {
      slots: {
        root: 'flex flex-col min-h-0 min-w-0 divide-y divide-default',
        input: '',
        close: '',
        back: 'p-0',
        content: 'relative overflow-hidden flex flex-col',
        footer: 'p-1',
        viewport: 'relative scroll-py-1 overflow-y-auto flex-1 focus:outline-none',
        group: 'p-1 isolate',
        empty: 'text-center text-muted',
        label: 'font-semibold text-highlighted',
        item: 'group relative w-full flex items-start select-none outline-none before:absolute before:z-[-1] before:inset-px before:rounded-md data-disabled:cursor-not-allowed data-disabled:opacity-75',
        itemLeadingIcon: 'shrink-0',
        itemLeadingAvatar: 'shrink-0',
        itemLeadingAvatarSize: '',
        itemLeadingChip: 'shrink-0',
        itemLeadingChipSize: '',
        itemTrailing: 'ms-auto inline-flex items-center',
        itemTrailingIcon: 'shrink-0',
        itemTrailingHighlightedIcon: 'shrink-0 text-dimmed hidden group-data-highlighted:inline-flex',
        itemTrailingKbds: 'hidden lg:inline-flex items-center shrink-0',
        itemTrailingKbdsSize: '',
        itemWrapper: 'flex-1 flex flex-col text-start min-w-0',
        itemLabel: 'truncate space-x-1 text-dimmed',
        itemLabelBase: 'text-highlighted [&>mark]:text-primary [&>mark]:bg-primary/15',
        itemLabelPrefix: 'text-default',
        itemLabelSuffix: 'text-dimmed [&>mark]:text-primary [&>mark]:bg-primary/15',
        itemDescription: 'truncate text-muted [&>mark]:text-primary [&>mark]:bg-primary/15'
      },
      variants: {
        virtualize: {
          true: {
            viewport: 'p-1 isolate'
          },
          false: {
            viewport: 'divide-y divide-default'
          }
        },
        size: {
          xs: {
            input: '[&>input]:h-10',
            empty: 'py-3 text-xs',
            label: 'p-1 text-[10px]/3 gap-1',
            item: 'p-1 text-xs gap-1',
            itemLeadingIcon: 'size-4',
            itemLeadingAvatarSize: '3xs',
            itemLeadingChip: 'size-4',
            itemLeadingChipSize: 'sm',
            itemTrailing: 'gap-1',
            itemTrailingIcon: 'size-4',
            itemTrailingHighlightedIcon: 'size-4',
            itemTrailingKbds: 'gap-0.5',
            itemTrailingKbdsSize: 'sm'
          },
          sm: {
            input: '[&>input]:h-11',
            empty: 'py-4 text-xs',
            label: 'p-1.5 text-[10px]/3 gap-1.5',
            item: 'p-1.5 text-xs gap-1.5',
            itemLeadingIcon: 'size-4',
            itemLeadingAvatarSize: '3xs',
            itemLeadingChip: 'size-4',
            itemLeadingChipSize: 'sm',
            itemTrailing: 'gap-1.5',
            itemTrailingIcon: 'size-4',
            itemTrailingHighlightedIcon: 'size-4',
            itemTrailingKbds: 'gap-0.5',
            itemTrailingKbdsSize: 'sm'
          },
          md: {
            input: '[&>input]:h-12',
            empty: 'py-6 text-sm',
            label: 'p-1.5 text-xs gap-1.5',
            item: 'p-1.5 text-sm gap-1.5',
            itemLeadingIcon: 'size-5',
            itemLeadingAvatarSize: '2xs',
            itemLeadingChip: 'size-5',
            itemLeadingChipSize: 'md',
            itemTrailing: 'gap-1.5',
            itemTrailingIcon: 'size-5',
            itemTrailingHighlightedIcon: 'size-5',
            itemTrailingKbds: 'gap-0.5',
            itemTrailingKbdsSize: 'md'
          },
          lg: {
            input: '[&>input]:h-13',
            empty: 'py-7 text-sm',
            label: 'p-2 text-xs gap-2',
            item: 'p-2 text-sm gap-2',
            itemLeadingIcon: 'size-5',
            itemLeadingAvatarSize: '2xs',
            itemLeadingChip: 'size-5',
            itemLeadingChipSize: 'md',
            itemTrailing: 'gap-2',
            itemTrailingIcon: 'size-5',
            itemTrailingHighlightedIcon: 'size-5',
            itemTrailingKbds: 'gap-0.5',
            itemTrailingKbdsSize: 'md'
          },
          xl: {
            input: '[&>input]:h-14',
            empty: 'py-8 text-base',
            label: 'p-2 text-sm gap-2',
            item: 'p-2 text-base gap-2',
            itemLeadingIcon: 'size-6',
            itemLeadingAvatarSize: 'xs',
            itemLeadingChip: 'size-6',
            itemLeadingChipSize: 'lg',
            itemTrailing: 'gap-2',
            itemTrailingIcon: 'size-6',
            itemTrailingHighlightedIcon: 'size-6',
            itemTrailingKbds: 'gap-0.5',
            itemTrailingKbdsSize: 'lg'
          }
        },
        active: {
          true: {
            item: 'text-highlighted before:bg-elevated',
            itemLeadingIcon: 'text-default'
          },
          false: {
            item: [
              'text-default data-highlighted:not-data-disabled:text-highlighted data-highlighted:not-data-disabled:before:bg-elevated/50',
              'transition-colors before:transition-colors'
            ],
            itemLeadingIcon: [
              'text-dimmed group-data-highlighted:not-group-data-disabled:text-default',
              'transition-colors'
            ]
          }
        },
        loading: {
          true: {
            itemLeadingIcon: 'animate-spin'
          }
        }
      },
      defaultVariants: {
        size: 'md'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/CommandPalette.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/command-palette.ts).


# Container

## Uso

Use o slot padrão para centralizar e limitar a largura do seu conteúdo.

> \[!TIP]
> See: /docs/getting-started/theme/css-variables#container
>
> Sua largura máxima é controlada pela variável CSS `--ui-container`.

::component-example
---
props:
  class: w-full
name: container-example
---
::

## API

### Props

```ts
/**
 * Props for the Container component
 */
interface ContainerProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
}
```

### Slots

```ts
/**
 * Slots for the Container component
 */
interface ContainerSlots {
  default(): any;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    container: {
      base: 'w-full max-w-(--ui-container) mx-auto px-4 sm:px-6 lg:px-8'
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/Container.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/container.ts).


# ContentNavigation

> \[!WARNING]
> See: /docs/getting-started/integrations/content
>
> Este componente só está disponível quando o módulo `@nuxt/content` está instalado.

## Uso

Use a prop `navigation` com o valor `navigation`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} que você obtém ao buscar a navegação do seu app.

::component-example
---
overflowHidden: true
props:
  class: w-full
class: h-96 overflow-y-auto
name: content-navigation-example
---
::

### Tipo

Defina a prop `type` como `single` para permitir que apenas um item fique aberto por vez. O padrão é `multiple`.

```vue
<script setup lang="ts">
import type { ContentNavigationLink } from '@nitro/ui'

const navigation = ref<ContentNavigationLink[]>([
  {
    title: "Guide",
    icon: "i-lucide-book-open",
    path: "#getting-started",
    children: [
      {
        title: "Introduction",
        path: "#introduction",
        active: true
      },
      {
        title: "Installation",
        path: "#installation"
      }
    ]
  },
  {
    title: "Composables",
    icon: "i-lucide-database",
    path: "#composables",
    children: [
      {
        title: "defineShortcuts",
        path: "#defineshortcuts"
      },
      {
        title: "useModal",
        path: "#usemodal"
      }
    ]
  }
])
</script>

<template>
  <UContentNavigation type="single" />
</template>
```

### Cor

Use a prop `color` para alterar a cor dos links de navegação.

```vue
<script setup lang="ts">
import type { ContentNavigationLink } from '@nitro/ui'

const navigation = ref<ContentNavigationLink[]>([
  {
    title: "Guide",
    icon: "i-lucide-book-open",
    path: "#getting-started",
    children: [
      {
        title: "Introduction",
        path: "#introduction",
        active: true
      },
      {
        title: "Installation",
        path: "#installation"
      }
    ]
  },
  {
    title: "Composables",
    icon: "i-lucide-database",
    path: "#composables",
    children: [
      {
        title: "defineShortcuts",
        path: "#defineshortcuts"
      },
      {
        title: "useModal",
        path: "#usemodal"
      }
    ]
  }
])
</script>

<template>
  <UContentNavigation color="neutral" />
</template>
```

### Variante

Use a prop `variant` para alterar a variante dos links de navegação.

```vue
<script setup lang="ts">
import type { ContentNavigationLink } from '@nitro/ui'

const navigation = ref<ContentNavigationLink[]>([
  {
    title: "Guide",
    icon: "i-lucide-book-open",
    path: "#getting-started",
    children: [
      {
        title: "Introduction",
        path: "#introduction",
        active: true
      },
      {
        title: "Installation",
        path: "#installation"
      }
    ]
  },
  {
    title: "Composables",
    icon: "i-lucide-database",
    path: "#composables",
    children: [
      {
        title: "defineShortcuts",
        path: "#defineshortcuts"
      },
      {
        title: "useModal",
        path: "#usemodal"
      }
    ]
  }
])
</script>

<template>
  <UContentNavigation variant="link" />
</template>
```

### Destaque

Use a prop `highlight` para exibir uma borda destacada para o link ativo.

Use a prop `highlight-color` para alterar a cor da borda. O padrão é o valor da prop `color`.

```vue
<script setup lang="ts">
import type { ContentNavigationLink } from '@nitro/ui'

const navigation = ref<ContentNavigationLink[]>([
  {
    title: "Guide",
    icon: "i-lucide-book-open",
    path: "#getting-started",
    children: [
      {
        title: "Introduction",
        path: "#introduction",
        active: true
      },
      {
        title: "Installation",
        path: "#installation"
      }
    ]
  },
  {
    title: "Composables",
    icon: "i-lucide-database",
    path: "#composables",
    children: [
      {
        title: "defineShortcuts",
        path: "#defineshortcuts"
      },
      {
        title: "useModal",
        path: "#usemodal"
      }
    ]
  }
])
</script>

<template>
  <UContentNavigation highlight highlight-color="primary" color="primary" variant="pill" />
</template>
```

### Ícone à direita

```vue
<script setup lang="ts">
import type { ContentNavigationLink } from '@nitro/ui'

const navigation = ref<ContentNavigationLink[]>([
  {
    title: "Guide",
    icon: "i-lucide-book-open",
    path: "#getting-started",
    children: [
      {
        title: "Introduction",
        path: "#introduction",
        active: true
      },
      {
        title: "Installation",
        path: "#installation"
      }
    ]
  },
  {
    title: "Composables",
    icon: "i-lucide-database",
    path: "#composables",
    children: [
      {
        title: "defineShortcuts",
        path: "#defineshortcuts"
      },
      {
        title: "useModal",
        path: "#usemodal"
      }
    ]
  }
])
</script>

<template>
  <UContentNavigation trailing-icon="i-lucide-arrow-up" />
</template>
```

## Exemplos

### Dentro de um layout

Use o componente ContentNavigation dentro de um componente [PageAside](https://ui.nitro.news/docs/components/page-aside), em um layout, para exibir a navegação da página:

```vue [layouts/docs.vue] {11}
<script setup lang="ts">
import type { ContentNavigationItem } from '@nuxt/content'

const navigation = inject<Ref<ContentNavigationItem[]>>('navigation')
</script>

<template>
  <NPage>
    <template #left>
      <NPageAside>
        <NContentNavigation :navigation="navigation" highlight />
      </NPageAside>
    </template>

    <slot />
  </NPage>
</template>
```

### Dentro de um cabeçalho

Use o componente ContentNavigation dentro do slot `content` de um componente [Header](https://ui.nitro.news/docs/components/header) para exibir a navegação da página no mobile:

```vue [components/Header.vue] {9-11}
<script setup lang="ts">
import type { ContentNavigationItem } from '@nuxt/content'

const navigation = inject<Ref<ContentNavigationItem[]>>('navigation')
</script>

<template>
  <NHeader>
    <template #body>
      <NContentNavigation :navigation="navigation" highlight />
    </template>
  </NHeader>
</template>
```

## API

### Props

```ts
/**
 * Props for the ContentNavigation component
 */
interface ContentNavigationProps {
  /**
   * The element or component this component should render as.
   * @default "\"nav\""
   */
  as?: any;
  /**
   * When `true`, the tree will be opened based on the current route.
   * When `false`, the tree will be closed.
   * When `undefined` (default), the first item will be opened with `type="single"` and the first level will be opened with `type="multiple"`.
   * @default "undefined"
   */
  defaultOpen?: boolean | undefined;
  /**
   * The icon displayed to toggle the accordion.
   */
  trailingIcon?: any;
  color?: "primary" | "secondary" | "accent" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
  variant?: "pill" | "link" | undefined;
  /**
   * Display a line next to the active link.
   * @default "false"
   */
  highlight?: boolean | undefined;
  highlightColor?: "primary" | "secondary" | "accent" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
  /**
   * When type is "single", prevents closing the open item when clicking its trigger.
   * When type is "multiple", disables the collapsible behavior.
   * @default "true"
   */
  collapsible?: boolean | undefined;
  /**
   * @default "0"
   */
  level?: number | undefined;
  navigation?: T[] | undefined;
  ui?: { root?: SlotClass; content?: SlotClass; list?: SlotClass; item?: SlotClass; listWithChildren?: SlotClass; itemWithChildren?: SlotClass; trigger?: SlotClass; link?: SlotClass; linkLeadingIcon?: SlotClass; linkTrailing?: SlotClass; linkTrailingBadge?: SlotClass; linkTrailingBadgeSize?: SlotClass; linkTrailingIcon?: SlotClass; linkTitle?: SlotClass; linkTitleExternalIcon?: SlotClass; } | undefined;
  /**
   * When `true`, prevents the user from interacting with the accordion and all its items
   */
  disabled?: boolean | undefined;
  /**
   * Determines whether a "single" or "multiple" items can be selected at a time.
   * 
   * This prop will overwrite the inferred type from `modelValue` and `defaultValue`.
   * @default "\"multiple\""
   */
  type?: SingleOrMultipleType | undefined;
  /**
   * When `true`, the element will be unmounted on closed state.
   * @default "true"
   */
  unmountOnHide?: boolean | undefined;
}
```

### Slots

```ts
/**
 * Slots for the ContentNavigation component
 */
interface ContentNavigationSlots {
  link(): any;
  link-leading(): any;
  link-title(): any;
  link-trailing(): any;
}
```

### Emits

```ts
/**
 * Emitted events for the ContentNavigation component
 */
interface ContentNavigationEmits {
  update:modelValue: (payload: [value: string | string[] | undefined]) => void;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    contentNavigation: {
      slots: {
        root: '',
        content: 'data-[state=open]:animate-[accordion-down_200ms_ease-out] data-[state=closed]:animate-[accordion-up_200ms_ease-out] overflow-hidden focus:outline-none',
        list: 'isolate -mx-2.5 -mt-1.5',
        item: '',
        listWithChildren: 'ms-5 border-s border-default',
        itemWithChildren: 'flex flex-col data-[state=open]:mb-1.5',
        trigger: 'font-semibold',
        link: 'group relative w-full px-2.5 py-1.5 before:inset-y-px before:inset-x-0 flex items-center gap-1.5 text-sm before:absolute before:z-[-1] before:rounded-md focus:outline-none focus-visible:outline-none focus-visible:before:ring-inset focus-visible:before:ring-2',
        linkLeadingIcon: 'shrink-0 size-5',
        linkTrailing: 'ms-auto inline-flex gap-1.5 items-center',
        linkTrailingBadge: 'shrink-0',
        linkTrailingBadgeSize: 'sm',
        linkTrailingIcon: 'size-5 transform transition-transform duration-200 shrink-0 group-data-[state=open]:rotate-180',
        linkTitle: 'truncate',
        linkTitleExternalIcon: 'size-3 align-top text-dimmed'
      },
      variants: {
        color: {
          primary: {
            trigger: 'focus-visible:ring-primary',
            link: 'focus-visible:before:ring-primary'
          },
          secondary: {
            trigger: 'focus-visible:ring-secondary',
            link: 'focus-visible:before:ring-secondary'
          },
          accent: {
            trigger: 'focus-visible:ring-accent',
            link: 'focus-visible:before:ring-accent'
          },
          success: {
            trigger: 'focus-visible:ring-success',
            link: 'focus-visible:before:ring-success'
          },
          info: {
            trigger: 'focus-visible:ring-info',
            link: 'focus-visible:before:ring-info'
          },
          warning: {
            trigger: 'focus-visible:ring-warning',
            link: 'focus-visible:before:ring-warning'
          },
          error: {
            trigger: 'focus-visible:ring-error',
            link: 'focus-visible:before:ring-error'
          },
          neutral: {
            trigger: 'focus-visible:ring-inverted',
            link: 'focus-visible:before:ring-inverted'
          }
        },
        highlightColor: {
          primary: '',
          secondary: '',
          accent: '',
          success: '',
          info: '',
          warning: '',
          error: '',
          neutral: ''
        },
        variant: {
          pill: '',
          link: ''
        },
        active: {
          true: {
            link: 'font-medium'
          },
          false: {
            link: 'text-muted',
            linkLeadingIcon: 'text-dimmed'
          }
        },
        disabled: {
          true: {
            trigger: 'data-[state=open]:text-highlighted'
          }
        },
        highlight: {
          true: {}
        },
        level: {
          true: {
            item: 'ps-1.5 -ms-px',
            itemWithChildren: 'ps-1.5 -ms-px'
          }
        }
      },
      compoundVariants: [
        {
          highlight: true,
          level: true,
          class: {
            link: 'after:absolute after:-left-1.5 after:inset-y-0.5 after:block after:w-px after:rounded-full after:transition-colors'
          }
        },
        {
          disabled: false,
          active: false,
          variant: 'pill',
          class: {
            link: 'hover:text-highlighted hover:before:bg-elevated/50 data-[state=open]:text-highlighted transition-colors before:transition-colors',
            linkLeadingIcon: 'group-hover:text-default group-data-[state=open]:text-default transition-colors'
          }
        },
        {
          color: 'primary',
          variant: 'pill',
          active: true,
          class: {
            link: 'text-primary',
            linkLeadingIcon: 'text-primary group-data-[state=open]:text-primary'
          }
        },
        {
          color: 'secondary',
          variant: 'pill',
          active: true,
          class: {
            link: 'text-secondary',
            linkLeadingIcon: 'text-secondary group-data-[state=open]:text-secondary'
          }
        },
        {
          color: 'accent',
          variant: 'pill',
          active: true,
          class: {
            link: 'text-accent',
            linkLeadingIcon: 'text-accent group-data-[state=open]:text-accent'
          }
        },
        {
          color: 'success',
          variant: 'pill',
          active: true,
          class: {
            link: 'text-success',
            linkLeadingIcon: 'text-success group-data-[state=open]:text-success'
          }
        },
        {
          color: 'info',
          variant: 'pill',
          active: true,
          class: {
            link: 'text-info',
            linkLeadingIcon: 'text-info group-data-[state=open]:text-info'
          }
        },
        {
          color: 'warning',
          variant: 'pill',
          active: true,
          class: {
            link: 'text-warning',
            linkLeadingIcon: 'text-warning group-data-[state=open]:text-warning'
          }
        },
        {
          color: 'error',
          variant: 'pill',
          active: true,
          class: {
            link: 'text-error',
            linkLeadingIcon: 'text-error group-data-[state=open]:text-error'
          }
        },
        {
          color: 'neutral',
          variant: 'pill',
          active: true,
          class: {
            link: 'text-highlighted',
            linkLeadingIcon: 'text-highlighted group-data-[state=open]:text-highlighted'
          }
        },
        {
          variant: 'pill',
          active: true,
          highlight: false,
          class: {
            link: 'before:bg-elevated'
          }
        },
        {
          variant: 'pill',
          active: true,
          highlight: true,
          disabled: false,
          class: {
            link: 'hover:before:bg-elevated/50 before:transition-colors'
          }
        },
        {
          disabled: false,
          active: false,
          variant: 'link',
          class: {
            link: 'hover:text-highlighted data-[state=open]:text-highlighted transition-colors',
            linkLeadingIcon: 'group-hover:text-default group-data-[state=open]:text-default transition-colors'
          }
        },
        {
          color: 'primary',
          variant: 'link',
          active: true,
          class: {
            link: 'text-primary',
            linkLeadingIcon: 'text-primary group-data-[state=open]:text-primary'
          }
        },
        {
          color: 'secondary',
          variant: 'link',
          active: true,
          class: {
            link: 'text-secondary',
            linkLeadingIcon: 'text-secondary group-data-[state=open]:text-secondary'
          }
        },
        {
          color: 'accent',
          variant: 'link',
          active: true,
          class: {
            link: 'text-accent',
            linkLeadingIcon: 'text-accent group-data-[state=open]:text-accent'
          }
        },
        {
          color: 'success',
          variant: 'link',
          active: true,
          class: {
            link: 'text-success',
            linkLeadingIcon: 'text-success group-data-[state=open]:text-success'
          }
        },
        {
          color: 'info',
          variant: 'link',
          active: true,
          class: {
            link: 'text-info',
            linkLeadingIcon: 'text-info group-data-[state=open]:text-info'
          }
        },
        {
          color: 'warning',
          variant: 'link',
          active: true,
          class: {
            link: 'text-warning',
            linkLeadingIcon: 'text-warning group-data-[state=open]:text-warning'
          }
        },
        {
          color: 'error',
          variant: 'link',
          active: true,
          class: {
            link: 'text-error',
            linkLeadingIcon: 'text-error group-data-[state=open]:text-error'
          }
        },
        {
          color: 'neutral',
          variant: 'link',
          active: true,
          class: {
            link: 'text-highlighted',
            linkLeadingIcon: 'text-highlighted group-data-[state=open]:text-highlighted'
          }
        },
        {
          highlightColor: 'primary',
          highlight: true,
          level: true,
          active: true,
          class: {
            link: 'after:bg-primary'
          }
        },
        {
          highlightColor: 'secondary',
          highlight: true,
          level: true,
          active: true,
          class: {
            link: 'after:bg-secondary'
          }
        },
        {
          highlightColor: 'accent',
          highlight: true,
          level: true,
          active: true,
          class: {
            link: 'after:bg-accent'
          }
        },
        {
          highlightColor: 'success',
          highlight: true,
          level: true,
          active: true,
          class: {
            link: 'after:bg-success'
          }
        },
        {
          highlightColor: 'info',
          highlight: true,
          level: true,
          active: true,
          class: {
            link: 'after:bg-info'
          }
        },
        {
          highlightColor: 'warning',
          highlight: true,
          level: true,
          active: true,
          class: {
            link: 'after:bg-warning'
          }
        },
        {
          highlightColor: 'error',
          highlight: true,
          level: true,
          active: true,
          class: {
            link: 'after:bg-error'
          }
        },
        {
          highlightColor: 'neutral',
          highlight: true,
          level: true,
          active: true,
          class: {
            link: 'after:bg-inverted'
          }
        }
      ],
      defaultVariants: {
        color: 'primary',
        highlightColor: 'primary',
        variant: 'pill'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/content/ContentNavigation.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/content/content-navigation.ts).


# ContentSearch

> \[!WARNING]
> See: /docs/getting-started/integrations/content
>
> Este componente só está disponível quando o módulo `@nuxt/content` está instalado.

## Uso

O componente ContentSearch estende o componente [CommandPalette](https://ui.nitro.news/docs/components/command-palette) com suporte de busca integrado ao [`@nuxt/content`](https://content.nuxt.com){rel="&#x22;nofollow&#x22;"}, agrupamento de navegação e comandos de modo de cor. Ele suporta tanto a filtragem no lado do cliente com [Fuse.js](https://www.fusejs.io/){rel="&#x22;nofollow&#x22;"} quanto a [busca em texto completo FTS5](https://www.sqlite.org/fts5.html){rel="&#x22;nofollow&#x22;"} no servidor. Você pode passar qualquer propriedade do CommandPalette, como `icon`, `placeholder`, etc.

::component-example
---
iframe:
  height: 500px;
iframeMobile: true
overflowHidden: true
source: false
name: content-search-example
---
::

> \[!NOTE]
>
> Você pode abrir o CommandPalette pressionando :kbd{value="meta"} :kbd{.ms-px value="K"}, usando o componente [ContentSearchButton](https://ui.nitro.news/docs/components/content-search-button) ou usando o composable `useContentSearch`: `const { open } = useContentSearch()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}.

> \[!TIP]
>
> É recomendado envolver o componente `ContentSearch` em um componente [ClientOnly](https://nuxt.com/docs/api/components/client-only){rel="&#x22;nofollow&#x22;"} para que ele não seja renderizado no servidor.

### Navegação

Use a prop `navigation` com [`queryCollectionNavigation`](https://content.nuxt.com/docs/utils/query-collection-navigation){rel="&#x22;nofollow&#x22;"} para agrupar os resultados de busca por seção:

```vue [app.vue] {2,9}
<script setup lang="ts">
const { data: navigation } = await useAsyncData('navigation', () => queryCollectionNavigation('content'))
</script>

<template>
  <NApp>
    <ClientOnly>
      <LazyUContentSearch
        :navigation="navigation"
      />
    </ClientOnly>
  </NApp>
</template>
```

### Arquivos

Use a prop `files` com [`queryCollectionSearchSections`](https://content.nuxt.com/docs/utils/query-collection-search-sections){rel="&#x22;nofollow&#x22;"} para carregar todas as seções de busca de antemão e usar a filtragem no lado do cliente com [Fuse.js](https://www.fusejs.io/){rel="&#x22;nofollow&#x22;"}:

```vue [app.vue] {4-8,16}
<script setup lang="ts">
const { data: navigation } = await useAsyncData('navigation', () => queryCollectionNavigation('content'))

const { data: files } = useLazyAsyncData('search', () => queryCollectionSearchSections('docs', {
  ignoredTags: ['style']
}), {
  server: false
})
</script>

<template>
  <NApp>
    <ClientOnly>
      <LazyUContentSearch
        :navigation="navigation"
        :files="files"
        :fuse="{ resultLimit: 20, fuseOptions: { threshold: 0.2 } }"
      />
    </ClientOnly>
  </NApp>
</template>
```

> \[!TIP]
>
> Use a prop `fuse` para configurar as opções do [useFuse](https://vueuse.org/integrations/useFuse){rel="&#x22;nofollow&#x22;"} passadas ao [CommandPalette](https://ui.nitro.news/docs/components/command-palette) subjacente, como `resultLimit` (padrão `12`) e `fuseOptions.threshold` (padrão `0.1`).

### Busca `4.8+`

Use a prop `search` com [`useSearchCollection`](https://content.nuxt.com/docs/utils/use-search-collection){rel="&#x22;nofollow&#x22;"} para a [busca em texto completo FTS5](https://www.sqlite.org/fts5.html){rel="&#x22;nofollow&#x22;"} no servidor, com trechos destacados, em vez da filtragem no lado do cliente:

> \[!WARNING]
>
> Requires `@nuxt/content` v3.14+.

```vue [app.vue] {4-7,24-25}
<script setup lang="ts">
const { data: navigation } = await useAsyncData('navigation', () => queryCollectionNavigation('content'))

const { search, status, init } = useSearchCollection('content', {
  immediate: false,
  ignoredTags: ['style']
})

const { open } = useContentSearch()

// Defer index initialization until the user opens the palette when using `immediate: false`
watch(open, (value) => {
  if (value && status.value === 'idle') {
    init()
  }
})
</script>

<template>
  <NApp>
    <ClientOnly>
      <LazyUContentSearch
        :navigation="navigation"
        :search="search"
        :search-status="status"
      />
    </ClientOnly>
  </NApp>
</template>
```

> \[!TIP]
>
> Passe `search-status` para que o componente possa reacionar a busca automaticamente assim que o índice ficar pronto. Use `search-delay` (padrão `100ms`) para controlar por quanto tempo a digitação precisa pausar antes de a busca disparar. A opção `fuse.resultLimit` limita o total de resultados retornados em todos os grupos (resultados de busca, links, tema, etc.).

> \[!NOTE]
>
> Ao usar a prop `search`, você não precisa passar `files`. O componente chama a função de busca assíncrona a cada tecla digitada, em vez do Fuse.js. Os resultados são mapeados e agrupados automaticamente por navegação, com trechos destacados. Diferentemente da abordagem `files`, que carrega todas as seções de busca de antemão e permite navegar pelos itens de navegação antes de digitar, a prop `search` só retorna resultados depois que uma consulta é digitada.

### Atalho

Use a prop `shortcut` para alterar o atalho usado em [defineShortcuts](https://ui.nitro.news/docs/composables/define-shortcuts) para abrir o componente ContentSearch. O padrão é `meta_k` ( :kbd{value="meta"} :kbd{value="K"} ).

```vue [app.vue] {5}
<template>
  <NApp>
    <ClientOnly>
      <LazyUContentSearch
        shortcut="meta_k"
      />
    </ClientOnly>
  </NApp>
</template>
```

### Links

Use a prop `links` para adicionar um grupo de links de acesso rápido no topo da paleta de comandos:

```vue [app.vue] {21}
<script setup lang="ts">
const links = [{
  label: 'Docs',
  icon: 'i-lucide-book',
  to: '/docs/getting-started'
}, {
  label: 'Components',
  icon: 'i-lucide-box',
  to: '/docs/components'
}, {
  label: 'Showcase',
  icon: 'i-lucide-presentation',
  to: '/showcase'
}]
</script>

<template>
  <NApp>
    <ClientOnly>
      <LazyUContentSearch
        :links="links"
      />
    </ClientOnly>
  </NApp>
</template>
```

### Modo de cor

Por padrão, um grupo de comandos será adicionado à paleta de comandos para você alternar entre os modos claro e escuro. Isso só terá efeito se o `colorMode` não estiver forçado em uma página específica, o que pode ser feito por meio de `definePageMeta`:

```vue [pages/index.vue]
<script setup lang="ts">
definePageMeta({
  colorMode: 'dark'
})
</script>
```

Você pode desabilitar esse comportamento definindo a prop `color-mode` como `false`:

```vue [app.vue] {5}
<template>
  <NApp>
    <ClientOnly>
      <LazyUContentSearch
        :color-mode="false"
      />
    </ClientOnly>
  </NApp>
</template>
```

## API

### Props

```ts
/**
 * Props for the ContentSearch component
 */
interface ContentSearchProps {
  size?: "sm" | "md" | "xs" | "lg" | "xl" | undefined;
  /**
   * Display a close button in the input (useful when inside a Modal for example).
   * `{ size: 'md', color: 'neutral', variant: 'ghost' }`{lang="ts-type"}
   * @default "true"
   */
  close?: boolean | Omit<ButtonProps, LinkPropsKeys> | undefined;
  /**
   * Configure the input or hide it with `false`.
   * `{ fixed: true }`{lang="ts-type"}
   */
  input?: boolean | Omit<InputProps<AcceptableValue, ModelModifiers>, "modelValue" | "defaultValue"> | undefined;
  /**
   * Keyboard shortcut to open the search (used by [`defineShortcuts`](https://ui.nitro.news/docs/composables/define-shortcuts))
   * @default "\"meta_k\""
   */
  shortcut?: string | undefined;
  /**
   * Links group displayed as the first group in the command palette.
   */
  links?: T[] | undefined;
  navigation?: ContentNavigationItem[] | undefined;
  files?: ContentSearchFile[] | undefined;
  /**
   * Options for [useFuse](https://vueuse.org/integrations/useFuse) passed to the [CommandPalette](https://ui.nitro.news/docs/components/command-palette).
   */
  fuse?: UseFuseOptions<T> | undefined;
  /**
   * Async search function (e.g. from [`useSearchCollection`](https://content.nuxt.com/docs/utils/use-search-collection)).
   * When provided, ContentSearch calls it on each keystroke and uses the results instead of Fuse.
   * Results are mapped, sanitized, and grouped by navigation internally.
   */
  search?: ContentSearchFn | undefined;
  /**
   * Status of the async search index (e.g. from `useSearchCollection`).
   * When the status transitions to `'ready'`, the search is automatically re-triggered if there's a pending term.
   */
  searchStatus?: ContentSearchStatus | undefined;
  /**
   * Delay (in milliseconds) before the search is triggered (debounced).
   * Keeps the input responsive by only running the search after typing settles.
   * Set to `0` to disable.
   * @default "100"
   */
  searchDelay?: number | undefined;
  /**
   * When `true`, the theme command will be added to the groups.
   * @default "true"
   */
  colorMode?: boolean | undefined;
  ui?: ({ modal?: SlotClass; input?: SlotClass; } & { root?: SlotClass; input?: SlotClass; close?: SlotClass; back?: SlotClass; content?: SlotClass; footer?: SlotClass; viewport?: SlotClass; group?: SlotClass; empty?: SlotClass; label?: SlotClass; item?: SlotClass; itemLeadingIcon?: SlotClass; itemLeadingAvatar?: SlotClass; itemLeadingAvatarSize?: SlotClass; itemLeadingChip?: SlotClass; itemLeadingChipSize?: SlotClass; itemTrailing?: SlotClass; itemTrailingIcon?: SlotClass; itemTrailingHighlightedIcon?: SlotClass; itemTrailingKbds?: SlotClass; itemTrailingKbdsSize?: SlotClass; itemWrapper?: SlotClass; itemLabel?: SlotClass; itemLabelBase?: SlotClass; itemLabelPrefix?: SlotClass; itemLabelSuffix?: SlotClass; itemDescription?: SlotClass; }) | undefined;
  title?: string | undefined;
  description?: string | undefined;
  /**
   * Render an overlay behind the modal.
   */
  overlay?: boolean | undefined;
  /**
   * Animate the modal when opening or closing.
   */
  transition?: boolean | undefined;
  /**
   * The content of the modal.
   */
  content?: (Omit<DialogContentProps, "as" | "asChild" | "forceMount"> & Partial<EmitsToProps<DialogContentImplEmits>>) | undefined;
  /**
   * When `false`, the modal will not close when clicking outside or pressing escape.
   */
  dismissible?: boolean | undefined;
  /**
   * When `true`, the modal will take up the full screen.
   * @default "false"
   */
  fullscreen?: boolean | undefined;
  /**
   * The modality of the dialog When set to `true`, <br>
   * interaction with outside elements will be disabled and only dialog content will be visible to screen readers.
   */
  modal?: boolean | undefined;
  /**
   * Render the modal in a portal.
   */
  portal?: string | boolean | HTMLElement | undefined;
  /**
   * When set to `false`, the dialog content will not be unmounted when closed, but instead hidden with CSS. <br>
   * Useful for SEO or when you want to improve performance by not remounting the component on every open.
   */
  unmountOnHide?: boolean | undefined;
  /**
   * The icon displayed in the input. Set to `false` to hide the icon.
   */
  icon?: any;
  /**
   * The icon displayed on the right side of the input.
   */
  trailingIcon?: any;
  /**
   * The icon displayed when an item is selected.
   */
  selectedIcon?: any;
  /**
   * The icon displayed when an item has children.
   */
  childrenIcon?: any;
  /**
   * The placeholder text for the input.
   */
  placeholder?: string | undefined;
  /**
   * Automatically focus the input when component is mounted.
   */
  autofocus?: boolean | undefined;
  /**
   * When `true`, the loading icon will be displayed.
   */
  loading?: boolean | undefined;
  /**
   * The icon when the `loading` prop is `true`.
   */
  loadingIcon?: any;
  /**
   * The icon displayed in the close button.
   */
  closeIcon?: any;
  /**
   * Display a button to navigate back in history.
   * `{ size: 'md', color: 'neutral', variant: 'link' }`{lang="ts-type"}
   */
  back?: boolean | Omit<ButtonProps, LinkPropsKeys> | undefined;
  /**
   * The icon displayed in the back button.
   */
  backIcon?: any;
  /**
   * When `true`, prevents the user from interacting with listbox
   */
  disabled?: boolean | undefined;
  /**
   * When `true`, hover over item will trigger highlight
   */
  highlightOnHover?: boolean | undefined;
  /**
   * The key used to get the label from the item.
   */
  labelKey?: string | undefined;
  /**
   * The key used to get the description from the item.
   */
  descriptionKey?: string | undefined;
  /**
   * Whether to preserve the order of groups as defined in the `groups` prop when filtering.
   * When `false`, groups will appear based on item matches.
   */
  preserveGroupOrder?: boolean | undefined;
  /**
   * Enable virtualization for large lists.
   * Note: when enabled, all groups are flattened into a single list due to a limitation of Reka UI (https://github.com/unovue/reka-ui/issues/1885).
   */
  virtualize?: boolean | { overscan?: number | undefined; estimateSize?: number | ((index: number) => number) | undefined; } | undefined;
  groups?: CommandPaletteGroup<ContentSearchItem>[] | undefined;
  /**
   * @default "\"\""
   */
  searchTerm?: string | undefined;
}
```

### Slots

```ts
/**
 * Slots for the ContentSearch component
 */
interface ContentSearchSlots {
  empty(): any;
  footer(): any;
  back(): any;
  close(): any;
  item(): any;
  item-leading(): any;
  item-label(): any;
  item-description(): any;
  item-trailing(): any;
  group-label(): any;
  content(): any;
}
```

### Emits

```ts
/**
 * Emitted events for the ContentSearch component
 */
interface ContentSearchEmits {
  update:searchTerm: (payload: [value: string]) => void;
}
```

### Expose

Ao acessar o componente por meio de um template ref, você pode usar o seguinte:

| Name                                                                                                                                    | Type                                                                                                                                                                   |
| --------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `commandPaletteRef`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | `Ref<InstanceType<typeof UCommandPalette> | null>`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} |

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    contentSearch: {
      slots: {
        modal: '',
        input: ''
      },
      variants: {
        fullscreen: {
          false: {
            modal: 'sm:max-w-3xl h-full sm:h-[28rem]'
          }
        },
        size: {
          xs: {},
          sm: {},
          md: {},
          lg: {},
          xl: {}
        }
      },
      defaultVariants: {
        size: 'md'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/content/ContentSearch.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/content/content-search.ts).


# ContentSearchButton

> \[!WARNING]
> See: /docs/getting-started/integrations/content
>
> Este componente só está disponível quando o módulo `@nuxt/content` está instalado.

## Uso

O componente ContentSearchButton é usado para abrir o modal do [ContentSearch](https://ui.nitro.news/docs/components/content-search).

```vue
<template>
  <UContentSearchButton />
</template>
```

Ele estende o componente [Button](https://ui.nitro.news/docs/components/button), então você pode passar qualquer propriedade como `color`, `variant`, `size`, etc.

```vue
<template>
  <UContentSearchButton variant="subtle" />
</template>
```

> \[!NOTE]
> See: #collapsed
>
> O botão usa por padrão `color="neutral"` e `variant="outline"` quando não está recolhido, e `variant="ghost"` quando recolhido.

### Recolhido

Use a prop `collapsed` para exibir o rótulo do botão e os [kbds](https://ui.nitro.news/#kbds). O padrão é `true`.

```vue
<template>
  <UContentSearchButton :collapsed="false" />
</template>
```

### Kbds

Use a prop `kbds` para exibir teclas do teclado no botão. O padrão é `['meta', 'K']`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} para corresponder ao atalho padrão do componente [ContentSearch](https://ui.nitro.news/docs/components/content-search#shortcut).

```vue
<template>
  <UContentSearchButton :collapsed="false" :kbds="[
  'alt',
  'O'
]" />
</template>
```

## API

### Props

```ts
/**
 * Props for the ContentSearchButton component
 */
interface ContentSearchButtonProps {
  /**
   * The icon displayed in the button. Set to `false` to hide the icon.
   */
  icon?: any;
  /**
   * The label displayed in the button.
   */
  label?: string | undefined;
  /**
   * The color of the button.
   * @default "\"neutral\""
   */
  color?: "error" | "neutral" | "primary" | "secondary" | "accent" | "success" | "info" | "warning" | undefined;
  /**
   * The variant of the button.
   * Defaults to 'outline' when not collapsed, 'ghost' when collapsed.
   */
  variant?: "solid" | "outline" | "soft" | "subtle" | "ghost" | "link" | undefined;
  /**
   * Whether the button is collapsed.
   * @default "true"
   */
  collapsed?: boolean | undefined;
  /**
   * Display a tooltip on the button when is collapsed with the button label.
   * This has priority over the global `tooltip` prop.
   * @default "false"
   */
  tooltip?: boolean | TooltipProps | undefined;
  /**
   * The keyboard keys to display in the button.
   * `{ variant: 'subtle' }`{lang="ts-type"}
   * @default "[\"meta\", \"k\"]"
   */
  kbds?: (string | undefined)[] | KbdProps[] | undefined;
  ui?: ({ base?: SlotClass; label?: SlotClass; trailing?: SlotClass; } & { base?: SlotClass; label?: SlotClass; leadingIcon?: SlotClass; leadingAvatar?: SlotClass; leadingAvatarSize?: SlotClass; trailingIcon?: SlotClass; }) | undefined;
  /**
   * Class to apply when the link is exact active
   */
  exactActiveClass?: string | undefined;
  /**
   * Pass the returned promise of `router.push()` to `document.startViewTransition()` if supported.
   */
  viewTransition?: boolean | undefined;
  autofocus?: Booleanish | undefined;
  disabled?: boolean | undefined;
  form?: string | undefined;
  formaction?: string | undefined;
  formenctype?: string | undefined;
  formmethod?: string | undefined;
  formnovalidate?: Booleanish | undefined;
  formtarget?: string | undefined;
  name?: string | undefined;
  /**
   * The type of the button when not a link.
   */
  type?: "reset" | "submit" | "button" | undefined;
  onClick?: ((event: MouseEvent) => void) | ((event: MouseEvent) => void)[] | undefined;
  /**
   * The element or component this component should render as when not a link.
   */
  as?: any;
  activeColor?: "error" | "neutral" | "primary" | "secondary" | "accent" | "success" | "info" | "warning" | undefined;
  activeVariant?: "solid" | "outline" | "soft" | "subtle" | "ghost" | "link" | undefined;
  size?: "xs" | "sm" | "md" | "lg" | "xl" | undefined;
  /**
   * Render the button with equal padding on all sides.
   */
  square?: boolean | undefined;
  /**
   * Render the button full width.
   */
  block?: boolean | undefined;
  /**
   * Set loading state automatically based on the `@click` promise state
   */
  loadingAuto?: boolean | undefined;
  /**
   * Display an avatar on the left side.
   */
  avatar?: AvatarProps | undefined;
  /**
   * When `true`, the icon will be displayed on the left side.
   */
  leading?: boolean | undefined;
  /**
   * Display an icon on the left side.
   */
  leadingIcon?: any;
  /**
   * When `true`, the icon will be displayed on the right side.
   */
  trailing?: boolean | undefined;
  /**
   * Display an icon on the right side.
   */
  trailingIcon?: any;
  /**
   * When `true`, the loading icon will be displayed.
   */
  loading?: boolean | undefined;
  /**
   * The icon when the `loading` prop is `true`.
   */
  loadingIcon?: any;
}
```

> \[!NOTE]
> See: https\://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attributes
>
> Este componente também suporta todos os atributos HTML nativos de `<button>`.

### Slots

```ts
/**
 * Slots for the ContentSearchButton component
 */
interface ContentSearchButtonSlots {
  leading(): any;
  default(): any;
  trailing(): any;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    contentSearchButton: {
      slots: {
        base: '',
        label: '',
        trailing: 'hidden lg:flex items-center gap-0.5 ms-auto'
      },
      variants: {
        collapsed: {
          true: {
            label: 'hidden',
            trailing: 'lg:hidden'
          }
        }
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/content/ContentSearchButton.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/content/content-search-button.ts).


# ContentSurround

> \[!WARNING]
> See: /docs/getting-started/integrations/content
>
> Este componente só está disponível quando o módulo `@nuxt/content` está instalado.

## Uso

Use a prop `surround` com o valor `surround`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} que você obtém ao buscar as páginas adjacentes.

::component-example
---
props:
  class: w-full
name: content-surround-example
---
::

### Anterior / Próximo

Use as props `prev-icon` e `next-icon` para personalizar o [Icon](https://ui.nitro.news/docs/components/icon) dos botões.

```vue
<script setup lang="ts">
import type { ContentSurroundLink } from '@nitro/ui'

const surround = ref<ContentSurroundLink[]>([
  {
    title: "ContentSearchButton",
    path: "/components/content-search-button",
    stem: "3.components/content-search-button",
    description: "A pre-styled Button to open the ContentSearch modal."
  },
  {
    title: "ContentToc",
    path: "/components/content-toc",
    stem: "3.components/content-toc",
    description: "A sticky Table of Contents with customizable slots."
  }
])
</script>

<template>
  <UContentSurround prev-icon="i-lucide-chevron-left" next-icon="i-lucide-chevron-right" :surround="surround" />
</template>
```

## Exemplos

### Dentro de uma página

Use o componente ContentSurround em uma página para exibir os links de anterior e próximo:

```vue [pages/[...slug\\].vue] {19}
<script setup lang="ts">
const route = useRoute()

const { data: page } = await useAsyncData(route.path, () => queryCollection('docs').path(route.path).first())
if (!page.value) {
  throw createError({ statusCode: 404, statusMessage: 'Page not found', fatal: true })
}
</script>

<template>
  <NPage v-if="page">
    <NPageHeader :title="page.title" />

    <NPageBody>
      <ContentRenderer v-if="page.body" :value="page" />

      <NSeparator v-if="surround?.filter(Boolean).length" />

      <NContentSurround :surround="(surround as any)" />
    </NPageBody>

    <template v-if="page?.body?.toc?.links?.length" #right>
      <NContentToc :links="page.body.toc.links" />
    </template>
  </NPage>
</template>
```

## API

### Props

```ts
/**
 * Props for the ContentSurround component
 */
interface ContentSurroundProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  /**
   * The icon displayed in the prev link.
   */
  prevIcon?: any;
  /**
   * The icon displayed in the next link.
   */
  nextIcon?: any;
  surround?: T[] | undefined;
  ui?: { root?: SlotClass; link?: SlotClass; linkLeading?: SlotClass; linkLeadingIcon?: SlotClass; linkTitle?: SlotClass; linkDescription?: SlotClass; } | undefined;
}
```

### Slots

```ts
/**
 * Slots for the ContentSurround component
 */
interface ContentSurroundSlots {
  link(): any;
  link-leading(): any;
  link-title(): any;
  link-description(): any;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    contentSurround: {
      slots: {
        root: 'grid grid-cols-1 sm:grid-cols-2 gap-8',
        link: 'group block px-6 py-8 rounded-lg border border-default hover:bg-elevated/50 focus-visible:outline-primary transition-colors',
        linkLeading: 'inline-flex items-center rounded-full p-1.5 bg-elevated group-hover:bg-primary/10 ring ring-accented mb-4 group-hover:ring-primary/50 transition',
        linkLeadingIcon: 'size-5 shrink-0 text-highlighted group-hover:text-primary transition-[color,translate]',
        linkTitle: 'font-medium text-[15px] text-highlighted mb-1 truncate',
        linkDescription: 'text-sm text-muted line-clamp-2'
      },
      variants: {
        direction: {
          left: {
            linkLeadingIcon: 'group-active:-translate-x-0.5'
          },
          right: {
            link: 'text-right',
            linkLeadingIcon: 'group-active:translate-x-0.5'
          }
        }
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/content/ContentSurround.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/content/content-surround.ts).


# ContentToc

> \[!WARNING]
> See: /docs/getting-started/integrations/content
>
> Este componente só está disponível quando o módulo `@nuxt/content` está instalado.

## Uso

Use a prop `links` com o `page?.body?.toc?.links`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} que você obtém ao buscar uma página.

::component-example
---
props:
  class: w-full
name: content-toc-example
---
::

### Título

Use a prop `title` para alterar o título do sumário.

```vue
<script setup lang="ts">
import type { ContentTocLink } from '@nitro/ui'

const links = ref<ContentTocLink[]>([
  {
    id: "usage",
    depth: 2,
    text: "Usage",
    children: [
      {
        id: "title",
        depth: 3,
        text: "Title"
      },
      {
        id: "color",
        depth: 3,
        text: "Color"
      },
      {
        id: "highlight",
        depth: 3,
        text: "Highlight"
      },
      {
        id: "highlight-color",
        depth: 3,
        text: "Highlight Color"
      },
      {
        id: "highlight-variant",
        depth: 3,
        text: "Highlight Variant"
      }
    ]
  }
])
</script>

<template>
  <UContentToc title="On this page" :links="links" />
</template>
```

### Cor

Use a prop `color` para alterar a cor dos links.

```vue
<script setup lang="ts">
import type { ContentTocLink } from '@nitro/ui'

const links = ref<ContentTocLink[]>([
  {
    id: "usage",
    depth: 2,
    text: "Usage",
    children: [
      {
        id: "title",
        depth: 3,
        text: "Title"
      },
      {
        id: "color",
        depth: 3,
        text: "Color"
      },
      {
        id: "highlight",
        depth: 3,
        text: "Highlight"
      },
      {
        id: "highlight-color",
        depth: 3,
        text: "Highlight Color"
      },
      {
        id: "highlight-variant",
        depth: 3,
        text: "Highlight Variant"
      }
    ]
  }
])
</script>

<template>
  <UContentToc color="neutral" :links="links" />
</template>
```

### Destaque

Use a prop `highlight` para exibir uma borda destacada para o item ativo.

```vue
<script setup lang="ts">
import type { ContentTocLink } from '@nitro/ui'

const links = ref<ContentTocLink[]>([
  {
    id: "usage",
    depth: 2,
    text: "Usage",
    children: [
      {
        id: "title",
        depth: 3,
        text: "Title"
      },
      {
        id: "color",
        depth: 3,
        text: "Color"
      },
      {
        id: "highlight",
        depth: 3,
        text: "Highlight"
      },
      {
        id: "highlight-color",
        depth: 3,
        text: "Highlight Color"
      },
      {
        id: "highlight-variant",
        depth: 3,
        text: "Highlight Variant"
      }
    ]
  }
])
</script>

<template>
  <UContentToc highlight :links="links" />
</template>
```

### Cor do destaque

Use a prop `highlight-color` para alterar a cor do destaque. O padrão é o valor da prop `color`.

```vue
<script setup lang="ts">
import type { ContentTocLink } from '@nitro/ui'

const links = ref<ContentTocLink[]>([
  {
    id: "usage",
    depth: 2,
    text: "Usage",
    children: [
      {
        id: "title",
        depth: 3,
        text: "Title"
      },
      {
        id: "color",
        depth: 3,
        text: "Color"
      },
      {
        id: "highlight",
        depth: 3,
        text: "Highlight"
      },
      {
        id: "highlight-color",
        depth: 3,
        text: "Highlight Color"
      },
      {
        id: "highlight-variant",
        depth: 3,
        text: "Highlight Variant"
      }
    ]
  }
])
</script>

<template>
  <UContentToc highlight highlight-color="neutral" :links="links" />
</template>
```

### Variante de destaque `4.6+`

Use a prop `highlight-variant` para alterar o estilo do destaque. O padrão é `straight`.

```vue
<script setup lang="ts">
import type { ContentTocLink } from '@nitro/ui'

const links = ref<ContentTocLink[]>([
  {
    id: "usage",
    depth: 2,
    text: "Usage",
    children: [
      {
        id: "title",
        depth: 3,
        text: "Title"
      },
      {
        id: "color",
        depth: 3,
        text: "Color"
      },
      {
        id: "highlight",
        depth: 3,
        text: "Highlight"
      },
      {
        id: "highlight-color",
        depth: 3,
        text: "Highlight Color"
      },
      {
        id: "highlight-variant",
        depth: 3,
        text: "Highlight Variant"
      }
    ]
  },
  {
    id: "examples",
    depth: 2,
    text: "Examples",
    children: [
      {
        id: "within-a-page",
        depth: 3,
        text: "Within a Page"
      }
    ]
  },
  {
    id: "api",
    depth: 2,
    text: "API",
    children: [
      {
        id: "props",
        depth: 3,
        text: "Props"
      },
      {
        id: "slots",
        depth: 3,
        text: "Slots"
      },
      {
        id: "emits",
        depth: 3,
        text: "Emits"
      }
    ]
  },
  {
    id: "theme",
    depth: 2,
    text: "Theme"
  }
])
</script>

<template>
  <UContentToc highlight highlight-color="primary" highlight-variant="circuit" :links="links" />
</template>
```

## Exemplos

### Dentro de uma página

Use o componente ContentToc em uma página para exibir o sumário:

```vue [pages/[...slug\\].vue] {22-24}
<script setup lang="ts">
const route = useRoute()

const { data: page } = await useAsyncData(route.path, () => queryCollection('docs').path(route.path).first())
if (!page.value) {
  throw createError({ statusCode: 404, statusMessage: 'Page not found', fatal: true })
}
</script>

<template>
  <NPage v-if="page">
    <NPageHeader :title="page.title" />

    <NPageBody>
      <ContentRenderer v-if="page.body" :value="page" />

      <NSeparator v-if="surround?.filter(Boolean).length" />

      <NContentSurround :surround="(surround as any)" />
    </NPageBody>

    <template v-if="page?.body?.toc?.links?.length" #right>
      <NContentToc :links="page.body.toc.links" />
    </template>
  </NPage>
</template>
```

## API

### Props

```ts
/**
 * Props for the ContentToc component
 */
interface ContentTocProps {
  /**
   * The element or component this component should render as.
   * @default "\"nav\""
   */
  as?: any;
  /**
   * The icon displayed to collapse the content.
   */
  trailingIcon?: any;
  /**
   * The title of the table of contents.
   */
  title?: string | undefined;
  color?: "primary" | "secondary" | "accent" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
  /**
   * Display a line next to the active link.
   */
  highlight?: boolean | undefined;
  highlightColor?: "primary" | "secondary" | "accent" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
  links?: T[] | undefined;
  ui?: { root?: SlotClass; container?: SlotClass; top?: SlotClass; bottom?: SlotClass; trigger?: SlotClass; title?: SlotClass; trailing?: SlotClass; trailingIcon?: SlotClass; content?: SlotClass; list?: SlotClass; listWithChildren?: SlotClass; item?: SlotClass; itemWithChildren?: SlotClass; link?: SlotClass; linkText?: SlotClass; indicator?: SlotClass; indicatorLine?: SlotClass; indicatorActive?: SlotClass; } | undefined;
  /**
   * The open state of the collapsible when it is initially rendered. <br> Use when you do not need to control its open state.
   */
  defaultOpen?: boolean | undefined;
  /**
   * The controlled open state of the collapsible. Can be binded with `v-model`.
   */
  open?: boolean | undefined;
}
```

### Slots

```ts
/**
 * Slots for the ContentToc component
 */
interface ContentTocSlots {
  leading(): any;
  default(): any;
  trailing(): any;
  content(): any;
  link(): any;
  top(): any;
  bottom(): any;
}
```

### Emits

```ts
/**
 * Emitted events for the ContentToc component
 */
interface ContentTocEmits {
  update:open: (payload: [value: boolean]) => void;
  move: (payload: [id: string]) => void;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    contentToc: {
      slots: {
        root: 'sticky top-(--ui-header-height) z-10 bg-default/75 lg:bg-[initial] backdrop-blur -mx-4 px-4 sm:px-6 sm:-mx-6 lg:ms-0 flex flex-col overflow-y-auto lg:overflow-hidden max-h-[calc(100vh-var(--ui-header-height))]',
        container: 'pt-4 sm:pt-6 pb-2.5 sm:pb-4.5 lg:py-8 border-b border-dashed border-default lg:border-0 flex flex-col lg:min-h-0',
        top: 'lg:shrink-0',
        bottom: 'hidden lg:flex lg:flex-col lg:shrink-0 gap-6',
        trigger: 'group text-sm font-semibold flex-1 flex items-center gap-1.5 py-1.5 -mt-1.5 rounded-sm outline-primary/25 focus-visible:outline-3 lg:shrink-0',
        title: 'truncate',
        trailing: 'ms-auto inline-flex gap-1.5 items-center',
        trailingIcon: 'size-5 transform transition-transform duration-200 shrink-0 group-data-[state=open]:rotate-180 lg:hidden',
        content: 'relative data-[state=open]:animate-[collapsible-down_200ms_ease-out] data-[state=closed]:animate-[collapsible-up_200ms_ease-out] data-[state=closed]:overflow-hidden focus:outline-none lg:min-h-0 lg:overflow-y-auto lg:scrollbar-none',
        list: 'min-w-0',
        listWithChildren: 'ms-3',
        item: 'min-w-0',
        itemWithChildren: '',
        link: 'group relative text-sm flex items-center rounded-sm outline-primary/25 focus-visible:outline-3 py-1',
        linkText: 'truncate',
        indicator: '',
        indicatorLine: '',
        indicatorActive: ''
      },
      variants: {
        color: {
          primary: '',
          secondary: '',
          accent: '',
          success: '',
          info: '',
          warning: '',
          error: '',
          neutral: ''
        },
        highlightColor: {
          primary: {
            indicatorActive: 'bg-primary'
          },
          secondary: {
            indicatorActive: 'bg-secondary'
          },
          accent: {
            indicatorActive: 'bg-accent'
          },
          success: {
            indicatorActive: 'bg-success'
          },
          info: {
            indicatorActive: 'bg-info'
          },
          warning: {
            indicatorActive: 'bg-warning'
          },
          error: {
            indicatorActive: 'bg-error'
          },
          neutral: {
            indicatorActive: 'bg-inverted'
          }
        },
        active: {
          false: {
            link: [
              'text-muted hover:text-default',
              'transition-colors'
            ]
          }
        },
        highlight: {
          true: ''
        },
        highlightVariant: {
          straight: '',
          circuit: ''
        },
        body: {
          true: {
            bottom: 'mt-6'
          }
        }
      },
      compoundVariants: [
        {
          color: 'primary',
          active: true,
          class: {
            link: 'text-primary'
          }
        },
        {
          color: 'secondary',
          active: true,
          class: {
            link: 'text-secondary'
          }
        },
        {
          color: 'accent',
          active: true,
          class: {
            link: 'text-accent'
          }
        },
        {
          color: 'success',
          active: true,
          class: {
            link: 'text-success'
          }
        },
        {
          color: 'info',
          active: true,
          class: {
            link: 'text-info'
          }
        },
        {
          color: 'warning',
          active: true,
          class: {
            link: 'text-warning'
          }
        },
        {
          color: 'error',
          active: true,
          class: {
            link: 'text-error'
          }
        },
        {
          color: 'neutral',
          active: true,
          class: {
            link: 'text-highlighted'
          }
        },
        {
          highlight: true,
          highlightVariant: 'straight',
          class: {
            list: 'ms-2.5 ps-4 border-s border-default',
            item: '-ms-px',
            indicator: 'absolute ms-2.5 transition-[translate,height] duration-200 h-(--indicator-size) translate-y-(--indicator-position) w-px rounded-full',
            indicatorLine: 'hidden',
            indicatorActive: 'w-full h-full'
          }
        },
        {
          highlight: true,
          highlightVariant: 'circuit',
          class: {
            list: 'ps-6.5',
            item: '-ms-px',
            itemWithChildren: 'ps-px',
            indicator: 'absolute ms-2.5 start-0 top-0 rtl:-scale-x-100',
            indicatorLine: 'absolute inset-0 bg-(--ui-border)',
            indicatorActive: 'absolute w-full h-(--indicator-size) translate-y-(--indicator-position) transition-[translate,height] duration-200 ease-out'
          }
        }
      ],
      defaultVariants: {
        color: 'primary',
        highlightColor: 'primary',
        highlightVariant: 'straight'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/content/ContentToc.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/content/content-toc.ts).


# ContextMenu

## Uso

Use o que quiser no slot padrão do ContextMenu e clique com o botão direito nele para exibir o menu.

```vue
<script setup lang="ts">
import type { ContextMenuItem } from '@nitro/ui'

const items = ref<ContextMenuItem[][]>([
  [
    {
      label: "Appearance",
      children: [
        {
          label: "System",
          icon: "i-lucide-monitor"
        },
        {
          label: "Light",
          icon: "i-lucide-sun"
        },
        {
          label: "Dark",
          icon: "i-lucide-moon"
        }
      ]
    }
  ],
  [
    {
      label: "Show Sidebar",
      kbds: [
        "meta",
        "s"
      ]
    },
    {
      label: "Show Toolbar",
      kbds: [
        "shift",
        "meta",
        "d"
      ]
    },
    {
      label: "Collapse Pinned Tabs",
      disabled: true
    }
  ],
  [
    {
      label: "Refresh the Page"
    },
    {
      label: "Clear Cookies and Refresh"
    },
    {
      label: "Clear Cache and Refresh"
    },
    {
      type: "separator"
    },
    {
      label: "Developer",
      children: [
        [
          {
            label: "View Source",
            kbds: [
              "meta",
              "shift",
              "u"
            ]
          },
          {
            label: "Developer Tools",
            kbds: [
              "option",
              "meta",
              "i"
            ]
          },
          {
            label: "Inspect Elements",
            kbds: [
              "option",
              "meta",
              "c"
            ]
          }
        ],
        [
          {
            label: "JavaScript Console",
            kbds: [
              "option",
              "meta",
              "j"
            ]
          }
        ]
      ]
    }
  ]
])
</script>

<template>
  <UContextMenu :items="items">
    <div class="flex items-center justify-center rounded-md border border-dashed border-accented text-sm aspect-video w-72">
      Right click here
    </div>
  </UContextMenu>
</template>
```

### Itens

Use a prop `items` como um array de objetos com as seguintes propriedades:

- `label?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `icon?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `avatar?: AvatarProps`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `kbds?: string[] | KbdProps[]`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- [`type?: "link" | "label" | "separator" | "checkbox"`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}](https://ui.nitro.news/#with-checkbox-items)
- [`color?: "error" | "primary" | "secondary" | "success" | "info" | "warning" | "neutral"`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}](https://ui.nitro.news/#with-color-items)
- [`checked?: boolean`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}](https://ui.nitro.news/#with-checkbox-items)
- `disabled?: boolean`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- [`slot?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}](https://ui.nitro.news/#with-custom-slot)
- `onSelect?: (e: Event) => void`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- [`onUpdateChecked?: (checked: boolean) => void`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}](https://ui.nitro.news/#with-checkbox-items)
- `children?: ContextMenuItem[] | ContextMenuItem[][]`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `class?: any`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `ui?: { item?: ClassNameValue, label?: ClassNameValue, separator?: ClassNameValue, itemLeadingIcon?: ClassNameValue, itemLeadingAvatarSize?: ClassNameValue, itemLeadingAvatar?: ClassNameValue, itemLabel?: ClassNameValue, itemLabelExternalIcon?: ClassNameValue, itemTrailing?: ClassNameValue, itemTrailingIcon?: ClassNameValue, itemTrailingKbds?: ClassNameValue, itemTrailingKbdsSize?: ClassNameValue }`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Você pode passar qualquer propriedade do componente [Link](https://ui.nitro.news/docs/components/link#props), como `to`, `target`, etc.

```vue
<script setup lang="ts">
import type { ContextMenuItem } from '@nitro/ui'

const items = ref<ContextMenuItem[][]>([
  [
    {
      label: "Appearance",
      children: [
        {
          label: "System",
          icon: "i-lucide-monitor"
        },
        {
          label: "Light",
          icon: "i-lucide-sun"
        },
        {
          label: "Dark",
          icon: "i-lucide-moon"
        }
      ]
    }
  ],
  [
    {
      label: "Show Sidebar",
      kbds: [
        "meta",
        "s"
      ]
    },
    {
      label: "Show Toolbar",
      kbds: [
        "shift",
        "meta",
        "d"
      ]
    },
    {
      label: "Collapse Pinned Tabs",
      disabled: true
    }
  ],
  [
    {
      label: "Refresh the Page"
    },
    {
      label: "Clear Cookies and Refresh"
    },
    {
      label: "Clear Cache and Refresh"
    },
    {
      type: "separator"
    },
    {
      label: "Developer",
      children: [
        [
          {
            label: "View Source",
            kbds: [
              "meta",
              "shift",
              "u"
            ]
          },
          {
            label: "Developer Tools",
            kbds: [
              "option",
              "meta",
              "i"
            ]
          },
          {
            label: "Inspect Elements",
            kbds: [
              "option",
              "meta",
              "c"
            ]
          }
        ],
        [
          {
            label: "JavaScript Console",
            kbds: [
              "option",
              "meta",
              "j"
            ]
          }
        ]
      ]
    }
  ]
])
</script>

<template>
  <UContextMenu :items="items" :ui="{
  content: 'w-48'
}">
    <div class="flex items-center justify-center rounded-md border border-dashed border-accented text-sm aspect-video w-72">
      Right click here
    </div>
  </UContextMenu>
</template>
```

> \[!NOTE]
>
> Você também pode passar um array de arrays para a prop `items` para criar grupos separados de itens.

> \[!TIP]
>
> Cada item pode receber um array `children` de objetos com as mesmas propriedades da prop `items` para criar um menu aninhado que pode ser controlado usando as propriedades `open`, `defaultOpen` e `content`.

### Tamanho

Use a prop `size` para alterar o tamanho do ContextMenu.

```vue
<script setup lang="ts">
import type { ContextMenuItem } from '@nitro/ui'

const items = ref<ContextMenuItem[]>([
  {
    label: "System",
    icon: "i-lucide-monitor"
  },
  {
    label: "Light",
    icon: "i-lucide-sun"
  },
  {
    label: "Dark",
    icon: "i-lucide-moon"
  }
])
</script>

<template>
  <UContextMenu size="xl" :items="items" :ui="{
  content: 'w-48'
}">
    <div class="flex items-center justify-center rounded-md border border-dashed border-accented text-sm aspect-video w-72">
      Right click here
    </div>
  </UContextMenu>
</template>
```

### Modal

Use a prop `modal` para controlar se o ContextMenu bloqueia a interação com o conteúdo externo. O padrão é `true`.

```vue
<script setup lang="ts">
import type { ContextMenuItem } from '@nitro/ui'

const items = ref<ContextMenuItem[]>([
  {
    label: "System",
    icon: "i-lucide-monitor"
  },
  {
    label: "Light",
    icon: "i-lucide-sun"
  },
  {
    label: "Dark",
    icon: "i-lucide-moon"
  }
])
</script>

<template>
  <UContextMenu :modal="false" :items="items" :ui="{
  content: 'w-48'
}">
    <div class="flex items-center justify-center rounded-md border border-dashed border-accented text-sm aspect-video w-72">
      Right click here
    </div>
  </UContextMenu>
</template>
```

### Desabilitado

Use a prop `disabled` para desabilitar o ContextMenu.

```vue
<script setup lang="ts">
import type { ContextMenuItem } from '@nitro/ui'

const items = ref<ContextMenuItem[]>([
  {
    label: "System",
    icon: "i-lucide-monitor"
  },
  {
    label: "Light",
    icon: "i-lucide-sun"
  },
  {
    label: "Dark",
    icon: "i-lucide-moon"
  }
])
</script>

<template>
  <UContextMenu disabled :items="items" :ui="{
  content: 'w-48'
}">
    <div class="flex items-center justify-center rounded-md border border-dashed border-accented text-sm aspect-video w-72">
      Right click here
    </div>
  </UContextMenu>
</template>
```

## Exemplos

### Com itens de checkbox

Você pode usar a propriedade `type` com `checkbox` e usar as propriedades `checked` / `onUpdateChecked` para controlar o estado marcado do item.

::component-example{collapse name="context-menu-checkbox-items-example"}
::

> \[!NOTE]
>
> Para garantir a reatividade do estado `checked` dos itens, é recomendado envolver seu array `items` dentro de um `computed`.

### Com itens de cor

Você pode usar a propriedade `color` para destacar certos itens com uma cor.

::component-example{collapse name="context-menu-color-items-example"}
::

### Com slot personalizado

Use a propriedade `slot` para personalizar um item específico.

Você terá acesso aos seguintes slots:

- `#{{ item.slot }}`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `#{{ item.slot }}-leading`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `#{{ item.slot }}-label`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `#{{ item.slot }}-trailing`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

::component-example{collapse name="context-menu-custom-slot-example"}
::

> \[!TIP]
> See: #slots
>
> Você também pode usar os slots `#item`, `#item-leading`, `#item-label` e `#item-trailing` para personalizar todos os itens.

### Extrair atalhos

Use o utilitário [extractShortcuts](https://ui.nitro.news/docs/composables/extract-shortcuts) para definir automaticamente atalhos a partir de itens de menu com uma propriedade `kbds`. Ele extrai os atalhos recursivamente e retorna um objeto compatível com [defineShortcuts](https://ui.nitro.news/docs/composables/define-shortcuts).

```vue
<script setup lang="ts">
const items = [
  [{
    label: 'Show Sidebar',
    kbds: ['meta', 'S'],
    onSelect() {
      console.log('Show Sidebar clicked')
    }
  }, {
    label: 'Show Toolbar',
    kbds: ['shift', 'meta', 'D'],
    onSelect() {
      console.log('Show Toolbar clicked')
    }
  }, {
    label: 'Collapse Pinned Tabs',
    disabled: true
  }], [{
    label: 'Refresh the Page'
  }, {
    label: 'Clear Cookies and Refresh'
  }, {
    label: 'Clear Cache and Refresh'
  }, {
    type: 'separator' as const
  }, {
    label: 'Developer',
    children: [[{
      label: 'View Source',
      kbds: ['option', 'meta', 'U'],
      onSelect() {
        console.log('View Source clicked')
      }
    }, {
      label: 'Developer Tools',
      kbds: ['option', 'meta', 'I'],
      onSelect() {
        console.log('Developer Tools clicked')
      }
    }], [{
      label: 'Inspect Elements',
      kbds: ['option', 'meta', 'C'],
      onSelect() {
        console.log('Inspect Elements clicked')
      }
    }], [{
      label: 'JavaScript Console',
      kbds: ['option', 'meta', 'J'],
      onSelect() {
        console.log('JavaScript Console clicked')
      }
    }]]
  }]
]

defineShortcuts(extractShortcuts(items))
</script>
```

> \[!NOTE]
>
> Neste exemplo, :kbd{value="meta"} :kbd{.ms-px value="S"}, :kbd{value="shift"} :kbd{.ms-px value="meta"} :kbd{.ms-px value="D"}, :kbd{value="option"} :kbd{.ms-px value="meta"} :kbd{.ms-px value="U"}, :kbd{value="option"} :kbd{.ms-px value="meta"} :kbd{.ms-px value="I"}, :kbd{value="option"} :kbd{.ms-px value="meta"} :kbd{.ms-px value="C"} e :kbd{value="option"} :kbd{.ms-px value="meta"} :kbd{.ms-px value="J"} disparariam a função `select` do item correspondente.

## API

### Props

```ts
/**
 * Props for the ContextMenu component
 */
interface ContextMenuProps {
  size?: "sm" | "md" | "xs" | "lg" | "xl" | undefined;
  items?: T | undefined;
  /**
   * The icon displayed when an item is checked.
   */
  checkedIcon?: any;
  /**
   * The icon displayed when an item is loading.
   */
  loadingIcon?: any;
  /**
   * The icon displayed when the item is an external link.
   * Set to `false` to hide the external icon.
   * @default "true"
   */
  externalIcon?: any;
  /**
   * The content of the menu.
   */
  content?: (Omit<ContextMenuContentProps, "as" | "asChild" | "forceMount"> & Partial<EmitsToProps<MenuContentEmits>>) | undefined;
  /**
   * Render the menu in a portal.
   * @default "true"
   */
  portal?: string | boolean | HTMLElement | undefined;
  /**
   * The key used to get the label from the item.
   * @default "\"label\""
   */
  labelKey?: GetItemKeys<T> | undefined;
  /**
   * The key used to get the description from the item.
   * @default "\"description\""
   */
  descriptionKey?: GetItemKeys<T> | undefined;
  disabled?: boolean | undefined;
  ui?: { content?: SlotClass; viewport?: SlotClass; group?: SlotClass; label?: SlotClass; separator?: SlotClass; item?: SlotClass; itemLeadingIcon?: SlotClass; itemLeadingAvatar?: SlotClass; itemLeadingAvatarSize?: SlotClass; itemTrailing?: SlotClass; itemTrailingIcon?: SlotClass; itemTrailingKbds?: SlotClass; itemTrailingKbdsSize?: SlotClass; itemWrapper?: SlotClass; itemLabel?: SlotClass; itemDescription?: SlotClass; itemLabelExternalIcon?: SlotClass; } | undefined;
  /**
   * The modality of the dropdown menu.
   * 
   * When set to `true`, interaction with outside elements will be disabled and only menu content will be visible to screen readers.
   * @default "true"
   */
  modal?: boolean | undefined;
  /**
   * The duration from when the trigger is pressed until the menu opens.
   */
  pressOpenDelay?: number | undefined;
}
```

### Slots

```ts
/**
 * Slots for the ContextMenu component
 */
interface ContextMenuSlots {
  default(): any;
  item(): any;
  item-leading(): any;
  item-label(): any;
  item-description(): any;
  item-trailing(): any;
  content-top(): any;
  content-bottom(): any;
}
```

### Emits

```ts
/**
 * Emitted events for the ContextMenu component
 */
interface ContextMenuEmits {
  update:open: (payload: [payload: boolean]) => void;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    contextMenu: {
      slots: {
        content: 'min-w-32 bg-default shadow-lg rounded-md ring ring-default overflow-hidden data-[state=open]:animate-[scale-in_100ms_ease-out] data-[state=closed]:animate-[scale-out_100ms_ease-in] origin-(--reka-context-menu-content-transform-origin) flex flex-col',
        viewport: 'relative divide-y divide-default scroll-py-1 overflow-y-auto flex-1',
        group: 'p-1 isolate',
        label: 'w-full flex items-center font-semibold text-highlighted',
        separator: '-mx-1 my-1 h-px bg-border',
        item: 'group relative w-full flex items-start select-none outline-none before:absolute before:z-[-1] before:inset-px before:rounded-md data-disabled:cursor-not-allowed data-disabled:opacity-75',
        itemLeadingIcon: 'shrink-0',
        itemLeadingAvatar: 'shrink-0',
        itemLeadingAvatarSize: '',
        itemTrailing: 'ms-auto inline-flex gap-1.5 items-center',
        itemTrailingIcon: 'shrink-0',
        itemTrailingKbds: 'hidden lg:inline-flex items-center shrink-0',
        itemTrailingKbdsSize: '',
        itemWrapper: 'flex-1 flex flex-col text-start min-w-0',
        itemLabel: 'truncate',
        itemDescription: 'truncate text-muted',
        itemLabelExternalIcon: 'inline-block size-3 align-top text-dimmed'
      },
      variants: {
        color: {
          primary: '',
          secondary: '',
          accent: '',
          success: '',
          info: '',
          warning: '',
          error: '',
          neutral: ''
        },
        active: {
          true: {
            item: 'text-highlighted before:bg-elevated',
            itemLeadingIcon: 'text-default'
          },
          false: {
            item: [
              'text-default data-highlighted:text-highlighted data-[state=open]:text-highlighted data-highlighted:before:bg-elevated/50 data-[state=open]:before:bg-elevated/50',
              'transition-colors before:transition-colors'
            ],
            itemLeadingIcon: [
              'text-dimmed group-data-highlighted:text-default group-data-[state=open]:text-default',
              'transition-colors'
            ]
          }
        },
        loading: {
          true: {
            itemLeadingIcon: 'animate-spin'
          }
        },
        size: {
          xs: {
            label: 'p-1 text-xs gap-1',
            item: 'p-1 text-xs gap-1',
            itemLeadingIcon: 'size-4',
            itemLeadingAvatarSize: '3xs',
            itemTrailingIcon: 'size-4',
            itemTrailingKbds: 'gap-0.5',
            itemTrailingKbdsSize: 'sm'
          },
          sm: {
            label: 'p-1.5 text-xs gap-1.5',
            item: 'p-1.5 text-xs gap-1.5',
            itemLeadingIcon: 'size-4',
            itemLeadingAvatarSize: '3xs',
            itemTrailingIcon: 'size-4',
            itemTrailingKbds: 'gap-0.5',
            itemTrailingKbdsSize: 'sm'
          },
          md: {
            label: 'p-1.5 text-sm gap-1.5',
            item: 'p-1.5 text-sm gap-1.5',
            itemLeadingIcon: 'size-5',
            itemLeadingAvatarSize: '2xs',
            itemTrailingIcon: 'size-5',
            itemTrailingKbds: 'gap-0.5',
            itemTrailingKbdsSize: 'md'
          },
          lg: {
            label: 'p-2 text-sm gap-2',
            item: 'p-2 text-sm gap-2',
            itemLeadingIcon: 'size-5',
            itemLeadingAvatarSize: '2xs',
            itemTrailingIcon: 'size-5',
            itemTrailingKbds: 'gap-1',
            itemTrailingKbdsSize: 'md'
          },
          xl: {
            label: 'p-2 text-base gap-2',
            item: 'p-2 text-base gap-2',
            itemLeadingIcon: 'size-6',
            itemLeadingAvatarSize: 'xs',
            itemTrailingIcon: 'size-6',
            itemTrailingKbds: 'gap-1',
            itemTrailingKbdsSize: 'lg'
          }
        }
      },
      compoundVariants: [
        {
          color: 'primary',
          active: false,
          class: {
            item: 'text-primary data-highlighted:text-primary data-highlighted:before:bg-primary/10 data-[state=open]:before:bg-primary/10',
            itemLeadingIcon: 'text-primary/75 group-data-highlighted:text-primary group-data-[state=open]:text-primary'
          }
        },
        {
          color: 'secondary',
          active: false,
          class: {
            item: 'text-secondary data-highlighted:text-secondary data-highlighted:before:bg-secondary/10 data-[state=open]:before:bg-secondary/10',
            itemLeadingIcon: 'text-secondary/75 group-data-highlighted:text-secondary group-data-[state=open]:text-secondary'
          }
        },
        {
          color: 'accent',
          active: false,
          class: {
            item: 'text-accent data-highlighted:text-accent data-highlighted:before:bg-accent/10 data-[state=open]:before:bg-accent/10',
            itemLeadingIcon: 'text-accent/75 group-data-highlighted:text-accent group-data-[state=open]:text-accent'
          }
        },
        {
          color: 'success',
          active: false,
          class: {
            item: 'text-success data-highlighted:text-success data-highlighted:before:bg-success/10 data-[state=open]:before:bg-success/10',
            itemLeadingIcon: 'text-success/75 group-data-highlighted:text-success group-data-[state=open]:text-success'
          }
        },
        {
          color: 'info',
          active: false,
          class: {
            item: 'text-info data-highlighted:text-info data-highlighted:before:bg-info/10 data-[state=open]:before:bg-info/10',
            itemLeadingIcon: 'text-info/75 group-data-highlighted:text-info group-data-[state=open]:text-info'
          }
        },
        {
          color: 'warning',
          active: false,
          class: {
            item: 'text-warning data-highlighted:text-warning data-highlighted:before:bg-warning/10 data-[state=open]:before:bg-warning/10',
            itemLeadingIcon: 'text-warning/75 group-data-highlighted:text-warning group-data-[state=open]:text-warning'
          }
        },
        {
          color: 'error',
          active: false,
          class: {
            item: 'text-error data-highlighted:text-error data-highlighted:before:bg-error/10 data-[state=open]:before:bg-error/10',
            itemLeadingIcon: 'text-error/75 group-data-highlighted:text-error group-data-[state=open]:text-error'
          }
        },
        {
          color: 'primary',
          active: true,
          class: {
            item: 'text-primary before:bg-primary/10',
            itemLeadingIcon: 'text-primary'
          }
        },
        {
          color: 'secondary',
          active: true,
          class: {
            item: 'text-secondary before:bg-secondary/10',
            itemLeadingIcon: 'text-secondary'
          }
        },
        {
          color: 'accent',
          active: true,
          class: {
            item: 'text-accent before:bg-accent/10',
            itemLeadingIcon: 'text-accent'
          }
        },
        {
          color: 'success',
          active: true,
          class: {
            item: 'text-success before:bg-success/10',
            itemLeadingIcon: 'text-success'
          }
        },
        {
          color: 'info',
          active: true,
          class: {
            item: 'text-info before:bg-info/10',
            itemLeadingIcon: 'text-info'
          }
        },
        {
          color: 'warning',
          active: true,
          class: {
            item: 'text-warning before:bg-warning/10',
            itemLeadingIcon: 'text-warning'
          }
        },
        {
          color: 'error',
          active: true,
          class: {
            item: 'text-error before:bg-error/10',
            itemLeadingIcon: 'text-error'
          }
        }
      ],
      defaultVariants: {
        size: 'md'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/ContextMenu.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/context-menu.ts).


# DashboardGroup

## Uso

O componente DashboardGroup é o layout principal que envolve os componentes [DashboardSidebar](https://ui.nitro.news/docs/components/dashboard-sidebar) e [DashboardPanel](https://ui.nitro.news/docs/components/dashboard-panel) para criar uma interface de dashboard responsiva.

Use-o em um layout ou no seu `app.vue`:

```vue [layouts/dashboard.vue] {2,6}
<template>
  <NDashboardGroup>
    <NDashboardSidebar />

    <slot />
  </NDashboardGroup>
</template>
```

## API

### Props

```ts
/**
 * Props for the DashboardGroup component
 */
interface DashboardGroupProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  /**
   * The storage to use for the size.
   * @default "\"cookie\""
   */
  storage?: "cookie" | "local" | undefined;
  /**
   * Unique id used to auto-save size.
   * @default "\"dashboard\""
   */
  storageKey?: string | undefined;
  /**
   * Whether to persist the size in the storage.
   * @default "true"
   */
  persistent?: boolean | undefined;
  /**
   * The unit to use for size values.
   * @default "\"%\""
   */
  unit?: "%" | "rem" | "px" | undefined;
}
```

### Slots

```ts
/**
 * Slots for the DashboardGroup component
 */
interface DashboardGroupSlots {
  default(): any;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    dashboardGroup: {
      base: 'fixed inset-0 flex overflow-hidden'
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/DashboardGroup.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/dashboard-group.ts).


# DashboardNavbar

## Uso

O componente DashboardNavbar é uma barra de navegação responsiva que se integra ao componente [DashboardSidebar](https://ui.nitro.news/docs/components/dashboard-sidebar). Ele inclui um botão de alternância para mobile que habilita a navegação responsiva em layouts de dashboard.

Use-o dentro do slot `header` do componente [DashboardPanel](https://ui.nitro.news/docs/components/dashboard-panel):

```vue [pages/index.vue] {9-11}
<script setup lang="ts">
definePageMeta({
  layout: 'dashboard'
})
</script>

<template>
  <NDashboardPanel>
    <template #header>
      <NDashboardNavbar />
    </template>
  </NDashboardPanel>
</template>
```

Use os slots `left`, `default` e `right` para personalizar a navbar.

::component-example
---
prettier: true
props:
  class: w-full
class: "!px-0 !pt-0"
name: dashboard-navbar-example
---
::

> \[!NOTE]
>
> Neste exemplo, usamos o componente [Tabs](https://ui.nitro.news/docs/components/tabs) no slot right para exibir algumas abas.

### Título

Use a prop `title` para definir o título da navbar.

```vue
<template>
  <UDashboardNavbar title="Dashboard" />
</template>
```

### Ícone

Use a prop `icon` para definir o ícone da navbar.

```vue
<template>
  <UDashboardNavbar title="Dashboard" icon="i-lucide-house" />
</template>
```

### Alternar

Use a prop `toggle` para personalizar o botão de alternância exibido no mobile que abre o componente [DashboardSidebar](https://ui.nitro.news/docs/components/dashboard-sidebar).

Você pode passar qualquer propriedade do componente [Button](https://ui.nitro.news/docs/components/button) para personalizá-lo.

::component-example
---
iframe: true
iframeMobile: true
overflowHidden: true
props:
  class: w-full
name: dashboard-navbar-toggle-example
---
::

### Lado do toggle

Use a prop `toggle-side` para alterar o lado do botão de toggle. O padrão é `right`.

::component-example
---
iframe: true
iframeMobile: true
overflowHidden: true
props:
  class: w-full
name: dashboard-navbar-toggle-side-example
---
::

## API

### Props

```ts
/**
 * Props for the DashboardNavbar component
 */
interface DashboardNavbarProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  /**
   * The icon displayed next to the title.
   */
  icon?: any;
  title?: string | undefined;
  /**
   * Customize the toggle button to open the sidebar.
   * `{ color: 'neutral', variant: 'ghost' }`{lang="ts-type"}
   * @default "true"
   */
  toggle?: boolean | Omit<ButtonProps, LinkPropsKeys> | undefined;
  /**
   * The side to render the toggle button on.
   * @default "\"left\""
   */
  toggleSide?: "left" | "right" | undefined;
  ui?: { root?: SlotClass; left?: SlotClass; icon?: SlotClass; title?: SlotClass; center?: SlotClass; right?: SlotClass; toggle?: SlotClass; } | undefined;
}
```

### Slots

```ts
/**
 * Slots for the DashboardNavbar component
 */
interface DashboardNavbarSlots {
  title(): any;
  leading(): any;
  trailing(): any;
  left(): any;
  default(): any;
  right(): any;
  toggle(): any;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    dashboardNavbar: {
      slots: {
        root: 'h-(--ui-header-height) shrink-0 flex items-center justify-between px-4 sm:px-6 gap-1.5',
        left: 'flex items-center gap-1.5 min-w-0',
        icon: 'shrink-0 size-5 self-center me-1.5',
        title: 'flex items-center gap-1.5 font-semibold text-highlighted truncate',
        center: 'hidden lg:flex',
        right: 'flex items-center shrink-0 gap-1.5',
        toggle: ''
      },
      variants: {
        toggleSide: {
          left: {
            toggle: ''
          },
          right: {
            toggle: ''
          }
        }
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/DashboardNavbar.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/dashboard-navbar.ts).


# DashboardPanel

## Uso

O componente DashboardPanel é usado para exibir um painel. O estado dele (tamanho, recolhido, etc.) é salvo com base nas props `storage` e `storage-key` que você fornece ao componente [DashboardGroup](https://ui.nitro.news/docs/components/dashboard-group#props).

Use-o dentro do slot padrão do componente [DashboardGroup](https://ui.nitro.news/docs/components/dashboard-group); você pode colocar vários painéis lado a lado:

```vue [pages/index.vue] {8,10}
<script setup lang="ts">
definePageMeta({
  layout: 'dashboard'
})
</script>

<template>
  <NDashboardPanel id="inbox-1" resizable />

  <NDashboardPanel id="inbox-2" class="hidden lg:flex" />
</template>
```

> \[!CAUTION]
>
> É recomendado definir um `id` ao usar vários painéis em páginas diferentes para evitar conflitos.

> \[!WARNING]
>
> Este componente não tem um único elemento raiz ao usar a prop `resizable`, então envolva-o em um container (ex.: `<div class="flex flex-1">`) se você usar transições de página ou precisar de uma raiz única para o layout.

Use os slots `header`, `body` e `footer` para personalizar o painel, ou o slot padrão se você não quiser um corpo rolável com espaçamento interno.

::component-example
---
collapse: true
props:
  minSize: 22
  defaultSize: 35
  maxSize: 40
  class: "!min-h-96 h-136"
class: "!p-0 !justify-start"
name: dashboard-panel-example
---
::

> \[!NOTE]
>
> Na maioria das vezes, você usará o componente [`DashboardNavbar`](https://ui.nitro.news/docs/components/dashboard-navbar) no slot `header`.

### Redimensionável

Use a prop `resizable` para tornar o painel redimensionável.

```vue
<template>
  <UDashboardPanel resizable>
    <template #body>
      <Placeholder class="h-96" />
    </template></UDashboardPanel>
</template>
```

### Tamanho

Use as props `min-size`, `max-size` e `default-size` para personalizar o tamanho do painel.

```vue
<template>
  <UDashboardPanel resizable :min-size="22" :default-size="35" :max-size="40">
    <template #body>
      <Placeholder class="h-96" />
    </template></UDashboardPanel>
</template>
```

> \[!TIP]
> See: /docs/components/dashboard-group#props
>
> Os tamanhos são calculados como porcentagens por padrão. Você pode alterar isso usando a prop `unit` no componente `DashboardGroup`.

## API

### Props

```ts
/**
 * Props for the DashboardPanel component
 */
interface DashboardPanelProps {
  ui?: { root?: SlotClass; body?: SlotClass; handle?: SlotClass; } | undefined;
  /**
   * The id of the panel.
   */
  id?: string | undefined;
  /**
   * The minimum size of the panel.
   * @default "15"
   */
  minSize?: number | undefined;
  /**
   * The maximum size of the panel.
   */
  maxSize?: number | undefined;
  /**
   * The default size of the panel.
   */
  defaultSize?: number | undefined;
  /**
   * Whether to allow the user to resize the panel.
   * @default "false"
   */
  resizable?: boolean | undefined;
}
```

### Slots

```ts
/**
 * Slots for the DashboardPanel component
 */
interface DashboardPanelSlots {
  default(): any;
  header(): any;
  body(): any;
  footer(): any;
  resize-handle(): any;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    dashboardPanel: {
      slots: {
        root: 'relative flex flex-col min-w-0 min-h-svh lg:not-last:border-e lg:not-last:border-default shrink-0',
        body: 'flex flex-col gap-4 sm:gap-6 flex-1 overflow-y-auto p-4 sm:p-6',
        handle: ''
      },
      variants: {
        size: {
          true: {
            root: 'w-full lg:w-(--width)'
          },
          false: {
            root: 'flex-1'
          }
        }
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/DashboardPanel.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/dashboard-panel.ts).


# DashboardResizeHandle

## Uso

O componente DashboardResizeHandle é usado pelos componentes [DashboardSidebar](https://ui.nitro.news/docs/components/dashboard-sidebar) e [DashboardPanel](https://ui.nitro.news/docs/components/dashboard-panel).

Ele é exibido automaticamente quando a prop `resizable` está definida, **você não precisa adicioná-lo manualmente**.

## Exemplos

### Dentro do slot `resize-handle`

Embora este componente seja exibido automaticamente quando a prop `resizable` está definida, você pode usar o slot `resize-handle` dos componentes [DashboardSidebar](https://ui.nitro.news/docs/components/dashboard-sidebar) e [DashboardPanel](https://ui.nitro.news/docs/components/dashboard-panel) para personalizar a alça.

```vue [layouts/dashboard.vue] {4-10}
<template>
  <NDashboardGroup>
    <NDashboardSidebar resizable>
      <template #resize-handle="{ onMouseDown, onTouchStart, onDoubleClick }">
        <NDashboardResizeHandle
          class="after:absolute after:inset-y-0 after:right-0 after:w-px hover:after:bg-(--ui-border-accented) after:transition"
          @mousedown="onMouseDown"
          @touchstart="onTouchStart"
          @dblclick="onDoubleClick"
        />
      </template>
    </NDashboardSidebar>

    <slot />
  </NDashboardGroup>
</template>
```

```vue [pages/index.vue] {9-15}
<script setup lang="ts">
definePageMeta({
  layout: 'dashboard'
})
</script>

<template>
  <NDashboardPanel resizable>
    <template #resize-handle="{ onMouseDown, onTouchStart, onDoubleClick }">
      <NDashboardResizeHandle
        class="after:absolute after:inset-y-0 after:right-0 after:w-px hover:after:bg-(--ui-border-accented) after:transition"
        @mousedown="onMouseDown"
        @touchstart="onTouchStart"
        @dblclick="onDoubleClick"
      />
    </template>
  </NDashboardPanel>
</template>
```

> \[!NOTE]
>
> Neste exemplo, adicionamos um pseudo-elemento `after` para exibir uma linha vertical no hover.

## API

### Props

```ts
/**
 * Props for the DashboardResizeHandle component
 */
interface DashboardResizeHandleProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
}
```

### Slots

```ts
/**
 * Slots for the DashboardResizeHandle component
 */
interface DashboardResizeHandleSlots {
  default(): any;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    dashboardResizeHandle: {
      base: 'hidden lg:block touch-none select-none cursor-ew-resize relative before:absolute before:inset-y-0 before:-left-1.5 before:-right-1.5'
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/DashboardResizeHandle.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/dashboard-resize-handle.ts).


# DashboardSearch

## Uso

O componente DashboardSearch estende o componente [CommandPalette](https://ui.nitro.news/docs/components/command-palette), então você pode passar qualquer propriedade como `icon`, `placeholder`, etc.

Use-o dentro do slot padrão do componente [DashboardGroup](https://ui.nitro.news/docs/components/dashboard-group):

```vue [layouts/dashboard.vue] {3}
<template>
  <NDashboardGroup>
    <NDashboardSidebar>
      <NDashboardSearchButton />
    </NDashboardSidebar>

    <NDashboardSearch />

    <slot />
  </NDashboardGroup>
</template>
```

> \[!TIP]
>
> Você pode abrir o CommandPalette pressionando :kbd{value="meta"} :kbd{.ms-px value="K"}, usando o componente [DashboardSearchButton](https://ui.nitro.news/docs/components/dashboard-search-button) ou usando uma diretiva `v-model:open`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"}.

### Atalho

Use a prop `shortcut` para alterar o atalho usado em [defineShortcuts](https://ui.nitro.news/docs/composables/define-shortcuts) para abrir o componente ContentSearch. O padrão é `meta_k` ( :kbd{value="meta"} :kbd{value="K"} ).

```vue [app.vue] {4}
<template>
  <NDashboardSearch
    v-model:search-term="searchTerm"
    shortcut="meta_k"
    :groups="groups"
    :fuse="{ resultLimit: 42 }"
  />
</template>
```

### Modo de cor

Por padrão, um grupo de comandos será adicionado à paleta de comandos para você alternar entre os modos claro e escuro. Isso só terá efeito se o `colorMode` não estiver forçado em uma página específica, o que pode ser feito por meio de `definePageMeta`:

```vue [pages/index.vue]
<script setup lang="ts">
definePageMeta({
  colorMode: 'dark'
})
</script>
```

Você pode desabilitar esse comportamento definindo a prop `color-mode` como `false`:

```vue [app.vue] {4}
<template>
  <NDashboardSearch
    v-model:search-term="searchTerm"
    :color-mode="false"
    :groups="groups"
    :fuse="{ resultLimit: 42 }"
  />
</template>
```

## API

### Props

```ts
/**
 * Props for the DashboardSearch component
 */
interface DashboardSearchProps {
  size?: "sm" | "md" | "xs" | "lg" | "xl" | undefined;
  /**
   * Display a close button in the input (useful when inside a Modal for example).
   * `{ size: 'md', color: 'neutral', variant: 'ghost' }`{lang="ts-type"}
   * @default "true"
   */
  close?: boolean | Omit<ButtonProps, LinkPropsKeys> | undefined;
  /**
   * Configure the input or hide it with `false`.
   * `{ fixed: true }`{lang="ts-type"}
   */
  input?: boolean | Omit<InputProps<AcceptableValue, ModelModifiers>, "modelValue" | "defaultValue"> | undefined;
  /**
   * Keyboard shortcut to open the search (used by [`defineShortcuts`](https://ui.nitro.news/docs/composables/define-shortcuts))
   * @default "\"meta_k\""
   */
  shortcut?: string | undefined;
  /**
   * Options for [useFuse](https://vueuse.org/integrations/useFuse) passed to the [CommandPalette](https://ui.nitro.news/docs/components/command-palette).
   */
  fuse?: UseFuseOptions<CommandPaletteItem> | undefined;
  /**
   * Delay (in milliseconds) before the search term is passed to Fuse (debounced).
   * Useful for large datasets where running fuzzy search on every keystroke is the bottleneck — the input stays responsive while Fuse only re-runs after typing settles.
   * Set to `0` to disable.
   * @default "100"
   */
  searchDelay?: number | undefined;
  /**
   * When `true`, the theme command will be added to the groups.
   * @default "true"
   */
  colorMode?: boolean | undefined;
  ui?: ({ modal?: SlotClass; input?: SlotClass; } & { root?: SlotClass; input?: SlotClass; close?: SlotClass; back?: SlotClass; content?: SlotClass; footer?: SlotClass; viewport?: SlotClass; group?: SlotClass; empty?: SlotClass; label?: SlotClass; item?: SlotClass; itemLeadingIcon?: SlotClass; itemLeadingAvatar?: SlotClass; itemLeadingAvatarSize?: SlotClass; itemLeadingChip?: SlotClass; itemLeadingChipSize?: SlotClass; itemTrailing?: SlotClass; itemTrailingIcon?: SlotClass; itemTrailingHighlightedIcon?: SlotClass; itemTrailingKbds?: SlotClass; itemTrailingKbdsSize?: SlotClass; itemWrapper?: SlotClass; itemLabel?: SlotClass; itemLabelBase?: SlotClass; itemLabelPrefix?: SlotClass; itemLabelSuffix?: SlotClass; itemDescription?: SlotClass; }) | undefined;
  title?: string | undefined;
  /**
   * Animate the modal when opening or closing.
   */
  transition?: boolean | undefined;
  description?: string | undefined;
  /**
   * Render an overlay behind the modal.
   */
  overlay?: boolean | undefined;
  /**
   * The content of the modal.
   */
  content?: (Omit<DialogContentProps, "as" | "asChild" | "forceMount"> & Partial<EmitsToProps<DialogContentImplEmits>>) | undefined;
  /**
   * When `false`, the modal will not close when clicking outside or pressing escape.
   */
  dismissible?: boolean | undefined;
  /**
   * When `true`, the modal will take up the full screen.
   * @default "false"
   */
  fullscreen?: boolean | undefined;
  /**
   * The modality of the dialog When set to `true`, <br>
   * interaction with outside elements will be disabled and only dialog content will be visible to screen readers.
   */
  modal?: boolean | undefined;
  /**
   * Render the modal in a portal.
   */
  portal?: string | boolean | HTMLElement | undefined;
  /**
   * When set to `false`, the dialog content will not be unmounted when closed, but instead hidden with CSS. <br>
   * Useful for SEO or when you want to improve performance by not remounting the component on every open.
   */
  unmountOnHide?: boolean | undefined;
  /**
   * The icon displayed in the input. Set to `false` to hide the icon.
   */
  icon?: any;
  /**
   * Automatically focus the input when component is mounted.
   */
  autofocus?: boolean | undefined;
  /**
   * When `true`, prevents the user from interacting with listbox
   */
  disabled?: boolean | undefined;
  /**
   * The icon displayed on the right side of the input.
   */
  trailingIcon?: any;
  /**
   * When `true`, the loading icon will be displayed.
   */
  loading?: boolean | undefined;
  /**
   * The icon when the `loading` prop is `true`.
   */
  loadingIcon?: any;
  /**
   * The icon displayed when an item is selected.
   */
  selectedIcon?: any;
  /**
   * The icon displayed when an item has children.
   */
  childrenIcon?: any;
  /**
   * The placeholder text for the input.
   */
  placeholder?: string | undefined;
  /**
   * The icon displayed in the close button.
   */
  closeIcon?: any;
  /**
   * Display a button to navigate back in history.
   * `{ size: 'md', color: 'neutral', variant: 'link' }`{lang="ts-type"}
   */
  back?: boolean | Omit<ButtonProps, LinkPropsKeys> | undefined;
  /**
   * The icon displayed in the back button.
   */
  backIcon?: any;
  /**
   * When `true`, hover over item will trigger highlight
   */
  highlightOnHover?: boolean | undefined;
  /**
   * The key used to get the label from the item.
   */
  labelKey?: string | undefined;
  /**
   * The key used to get the description from the item.
   */
  descriptionKey?: string | undefined;
  /**
   * Whether to preserve the order of groups as defined in the `groups` prop when filtering.
   * When `false`, groups will appear based on item matches.
   */
  preserveGroupOrder?: boolean | undefined;
  /**
   * Enable virtualization for large lists.
   * Note: when enabled, all groups are flattened into a single list due to a limitation of Reka UI (https://github.com/unovue/reka-ui/issues/1885).
   */
  virtualize?: boolean | { overscan?: number | undefined; estimateSize?: number | ((index: number) => number) | undefined; } | undefined;
  groups?: CommandPaletteGroup<CommandPaletteItem>[] | undefined;
  /**
   * @default "false"
   */
  open?: boolean | undefined;
  /**
   * @default "\"\""
   */
  searchTerm?: string | undefined;
}
```

### Slots

```ts
/**
 * Slots for the DashboardSearch component
 */
interface DashboardSearchSlots {
  empty(): any;
  footer(): any;
  back(): any;
  close(): any;
  item(): any;
  item-leading(): any;
  item-label(): any;
  item-description(): any;
  item-trailing(): any;
  group-label(): any;
  content(): any;
}
```

### Emits

```ts
/**
 * Emitted events for the DashboardSearch component
 */
interface DashboardSearchEmits {
  update:open: (payload: [value: boolean]) => void;
  update:searchTerm: (payload: [value: string]) => void;
}
```

### Expose

Ao acessar o componente por meio de um template ref, você pode usar o seguinte:

| Name                                                                                                                                    | Type                                                                                                                                                                   |
| --------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `commandPaletteRef`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | `Ref<InstanceType<typeof UCommandPalette> | null>`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} |

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    dashboardSearch: {
      slots: {
        modal: '',
        input: ''
      },
      variants: {
        fullscreen: {
          false: {
            modal: 'sm:max-w-3xl h-full sm:h-[28rem]'
          }
        },
        size: {
          xs: {},
          sm: {},
          md: {},
          lg: {},
          xl: {}
        }
      },
      defaultVariants: {
        size: 'md'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/DashboardSearch.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/dashboard-search.ts).


# DashboardSearchButton

## Uso

O componente DashboardSearchButton é usado para abrir o modal do [DashboardSearch](https://ui.nitro.news/docs/components/dashboard-search).

```vue
<template>
  <UDashboardSearchButton />
</template>
```

Ele estende o componente [Button](https://ui.nitro.news/docs/components/button), então você pode passar qualquer propriedade como `color`, `variant`, `size`, etc.

```vue
<template>
  <UDashboardSearchButton variant="subtle" />
</template>
```

> \[!NOTE]
> See: #collapsed
>
> O botão usa por padrão `color="neutral"` e `variant="outline"` quando não está recolhido, e `variant="ghost"` quando recolhido.

### Recolhido

Use a prop `collapsed` para ocultar o rótulo do botão e os [kbds](https://ui.nitro.news/#kbds). O padrão é `false`.

```vue
<template>
  <UDashboardSearchButton collapsed />
</template>
```

> \[!TIP]
> See: /docs/components/dashboard-sidebar#slots
>
> Ao usar o botão no componente **DashboardSidebar**, use a prop de slot `collapsed` diretamente.

### Kbds

Use a prop `kbds` para exibir teclas do teclado no botão. O padrão é `['meta', 'K']`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} para corresponder ao atalho padrão do componente [DashboardSearch](https://ui.nitro.news/docs/components/dashboard-search#shortcut).

```vue
<template>
  <UDashboardSearchButton :collapsed="false" :kbds="[
  'alt',
  'O'
]" />
</template>
```

## API

### Props

```ts
/**
 * Props for the DashboardSearchButton component
 */
interface DashboardSearchButtonProps {
  /**
   * The icon displayed in the button. Set to `false` to hide the icon.
   */
  icon?: any;
  /**
   * The label displayed in the button.
   */
  label?: string | undefined;
  /**
   * The color of the button.
   * @default "\"neutral\""
   */
  color?: "error" | "neutral" | "primary" | "secondary" | "accent" | "success" | "info" | "warning" | undefined;
  /**
   * The variant of the button.
   * Defaults to 'outline' when not collapsed, 'ghost' when collapsed.
   */
  variant?: "solid" | "outline" | "soft" | "subtle" | "ghost" | "link" | undefined;
  /**
   * Whether the button is collapsed.
   * @default "false"
   */
  collapsed?: boolean | undefined;
  /**
   * Display a tooltip on the button when is collapsed with the button label.
   * This has priority over the global `tooltip` prop.
   * @default "false"
   */
  tooltip?: boolean | TooltipProps | undefined;
  /**
   * The keyboard keys to display in the button.
   * `{ variant: 'subtle' }`{lang="ts-type"}
   * @default "[\"meta\", \"k\"]"
   */
  kbds?: (string | undefined)[] | KbdProps[] | undefined;
  ui?: ({ base?: SlotClass; label?: SlotClass; trailing?: SlotClass; } & { base?: SlotClass; label?: SlotClass; leadingIcon?: SlotClass; leadingAvatar?: SlotClass; leadingAvatarSize?: SlotClass; trailingIcon?: SlotClass; }) | undefined;
  /**
   * Class to apply when the link is exact active
   */
  exactActiveClass?: string | undefined;
  /**
   * Pass the returned promise of `router.push()` to `document.startViewTransition()` if supported.
   */
  viewTransition?: boolean | undefined;
  autofocus?: Booleanish | undefined;
  disabled?: boolean | undefined;
  form?: string | undefined;
  formaction?: string | undefined;
  formenctype?: string | undefined;
  formmethod?: string | undefined;
  formnovalidate?: Booleanish | undefined;
  formtarget?: string | undefined;
  name?: string | undefined;
  /**
   * The type of the button when not a link.
   */
  type?: "reset" | "submit" | "button" | undefined;
  onClick?: ((event: MouseEvent) => void) | ((event: MouseEvent) => void)[] | undefined;
  /**
   * The element or component this component should render as when not a link.
   */
  as?: any;
  activeColor?: "error" | "neutral" | "primary" | "secondary" | "accent" | "success" | "info" | "warning" | undefined;
  activeVariant?: "solid" | "outline" | "soft" | "subtle" | "ghost" | "link" | undefined;
  size?: "xs" | "sm" | "md" | "lg" | "xl" | undefined;
  /**
   * Render the button with equal padding on all sides.
   */
  square?: boolean | undefined;
  /**
   * Render the button full width.
   */
  block?: boolean | undefined;
  /**
   * Set loading state automatically based on the `@click` promise state
   */
  loadingAuto?: boolean | undefined;
  /**
   * Display an avatar on the left side.
   */
  avatar?: AvatarProps | undefined;
  /**
   * When `true`, the icon will be displayed on the left side.
   */
  leading?: boolean | undefined;
  /**
   * Display an icon on the left side.
   */
  leadingIcon?: any;
  /**
   * When `true`, the icon will be displayed on the right side.
   */
  trailing?: boolean | undefined;
  /**
   * Display an icon on the right side.
   */
  trailingIcon?: any;
  /**
   * When `true`, the loading icon will be displayed.
   */
  loading?: boolean | undefined;
  /**
   * The icon when the `loading` prop is `true`.
   */
  loadingIcon?: any;
}
```

> \[!NOTE]
> See: https\://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attributes
>
> Este componente também suporta todos os atributos HTML nativos de `<button>`.

### Slots

```ts
/**
 * Slots for the DashboardSearchButton component
 */
interface DashboardSearchButtonSlots {
  leading(): any;
  default(): any;
  trailing(): any;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    dashboardSearchButton: {
      slots: {
        base: '',
        label: '',
        trailing: 'hidden lg:flex items-center gap-0.5 ms-auto'
      },
      variants: {
        collapsed: {
          true: {
            label: 'hidden',
            trailing: 'lg:hidden'
          }
        }
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/DashboardSearchButton.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/dashboard-search-button.ts).


# DashboardSidebar

## Uso

O componente DashboardSidebar é usado para exibir uma sidebar em um layout de dashboard. Ele suporta redimensionamento por arraste, persistência de estado e se integra com [DashboardGroup](https://ui.nitro.news/docs/components/dashboard-group), [DashboardPanel](https://ui.nitro.news/docs/components/dashboard-panel) e [DashboardNavbar](https://ui.nitro.news/docs/components/dashboard-navbar).

> \[!TIP]
> See: /docs/components/sidebar
>
> **DashboardSidebar vs Sidebar**: This component is designed for dashboard layouts with drag-to-resize, state persistence and `DashboardGroup` integration. For a simple, standalone sidebar (chat panel, settings, navigation), use [Sidebar](https://ui.nitro.news/docs/components/sidebar) instead.

O estado dele (tamanho, recolhido, etc.) é salvo com base nas props `storage` e `storage-key` que você fornece ao componente [DashboardGroup](https://ui.nitro.news/docs/components/dashboard-group#props).

Use-o dentro do slot padrão do componente [DashboardGroup](https://ui.nitro.news/docs/components/dashboard-group):

```vue [layouts/dashboard.vue] {3}
<template>
  <NDashboardGroup>
    <NDashboardSidebar />

    <slot />
  </NDashboardGroup>
</template>
```

> \[!WARNING]
>
> Este componente não tem um único elemento raiz ao usar a prop `resizable`, então envolva-o em um container (ex.: `<div class="flex flex-1">`) se você usar transições de página ou precisar de uma raiz única para o layout.

Use os slots `header`, `default` e `footer` para personalizar a sidebar e os slots `body` ou `content` para personalizar o menu da sidebar.

::component-example
---
collapse: true
props:
  minSize: 22
  defaultSize: 35
  maxSize: 40
  class: "!min-h-96 h-136"
class: "!p-0 !justify-start"
name: dashboard-sidebar-example
---
::

> \[!NOTE]
>
> Arraste a sidebar para perto da borda esquerda da tela para recolhê-la.

### Redimensionável

Use a prop `resizable` para tornar a sidebar redimensionável.

```vue
<template>
  <UDashboardSidebar resizable>
    <Placeholder class="h-96" />
  </UDashboardSidebar>
</template>
```

### Recolhível

Use a prop `collapsible` para tornar a sidebar recolhível ao arrastar para perto da borda da tela.

> \[!WARNING]
>
> O componente [`DashboardSidebarCollapse`](https://ui.nitro.news/docs/components/dashboard-sidebar-collapse) não terá efeito se a sidebar não for **collapsible**.

```vue
<template>
  <UDashboardSidebar resizable collapsible>
    <Placeholder class="h-96" />
  </UDashboardSidebar>
</template>
```

> \[!TIP]
> See: #slots
>
> Você pode acessar o estado `collapsed` nas props de slot para personalizar o conteúdo da sidebar quando ela está recolhida.

### Tamanho

Use as props `min-size`, `max-size`, `default-size` e `collapsed-size` para personalizar o tamanho da sidebar.

```vue
<template>
  <UDashboardSidebar resizable collapsible :min-size="22" :default-size="35" :max-size="40" :collapsed-size="0">
    <Placeholder class="h-96" />
  </UDashboardSidebar>
</template>
```

> \[!TIP]
> See: /docs/components/dashboard-group#props
>
> Os tamanhos são calculados como porcentagens por padrão. Você pode alterar isso usando a prop `unit` no componente `DashboardGroup`.

> \[!NOTE]
>
> A prop `collapsed-size` é definida como `0` por padrão, mas a sidebar tem um `min-w-16` para garantir que ela fique visível.

### Lado

Use a prop `side` para alterar o lado da sidebar. O padrão é `left`.

```vue
<template>
  <UDashboardSidebar side="right" resizable collapsible>
    <Placeholder class="h-96" />
  </UDashboardSidebar>
</template>
```

### Modo

Use a prop `mode` para alterar o modo do menu da sidebar. O padrão é `slideover`.

Use o slot `body` para preencher o corpo do menu (abaixo do cabeçalho) ou o slot `content` para preencher o menu inteiro.

> \[!TIP]
> See: #props
>
> Você pode usar a prop `menu` para personalizar o menu da sidebar; ele se adapta dependendo do modo que você escolher.

::component-example
---
collapse: true
iframe:
  height: 500px;
iframeMobile: true
options:
  - name: mode
    label: mode
    default: drawer
    items:
      - modal
      - slideover
      - drawer
overflowHidden: true
props:
  class: w-full
name: dashboard-sidebar-mode-example
---
::

> \[!NOTE]
>
> Estes exemplos contêm os componentes [`DashboardGroup`](https://ui.nitro.news/docs/components/dashboard-group), [`DashboardPanel`](https://ui.nitro.news/docs/components/dashboard-panel) e [`DashboardNavbar`](https://ui.nitro.news/docs/components/dashboard-navbar), pois eles são necessários para demonstrar a sidebar no mobile.

### Alternar

Use a prop `toggle` para personalizar o componente [DashboardSidebarToggle](https://ui.nitro.news/docs/components/dashboard-sidebar-toggle) exibido no mobile.

Você pode passar qualquer propriedade do componente [Button](https://ui.nitro.news/docs/components/button) para personalizá-lo.

::component-example
---
collapse: true
iframe:
  height: 500px;
iframeMobile: true
overflowHidden: true
props:
  class: w-full
name: dashboard-sidebar-toggle-example
---
::

### Lado do toggle

Use a prop `toggle-side` para alterar o lado do botão de alternância. O padrão é `left`.

::component-example
---
collapse: true
iframe:
  height: 500px;
iframeMobile: true
overflowHidden: true
props:
  class: w-full
name: dashboard-sidebar-toggle-side-example
---
::

## Exemplos

### Controlar o estado de abertura

Você pode controlar o estado de abertura usando a prop `open` ou a diretiva `v-model:open`.

::component-example
---
iframe:
  height: 500px;
iframeMobile: true
overflowHidden: true
class: "!p-0 !justify-start"
name: dashboard-sidebar-open-example
---
::

> \[!NOTE]
>
> Neste exemplo, aproveitando o [`defineShortcuts`](https://ui.nitro.news/docs/composables/define-shortcuts), você pode alternar o estado de abertura do DashboardSidebar pressionando :kbd{value="O"}.

### Controlar o estado recolhido

Você pode controlar o estado recolhido usando a prop `collapsed` ou a diretiva `v-model:collapsed`.

::component-example
---
props:
  minSize: 22
  defaultSize: 35
  maxSize: 40
  class: "!min-h-96 h-136"
class: "!p-0 !justify-start"
name: dashboard-sidebar-collapsed-example
---
::

> \[!NOTE]
>
> Neste exemplo, aproveitando o [`defineShortcuts`](https://ui.nitro.news/docs/composables/define-shortcuts), você pode alternar o estado recolhido do DashboardSidebar pressionando :kbd{value="C"}.

## API

### Props

```ts
/**
 * Props for the DashboardSidebar component
 */
interface DashboardSidebarProps {
  /**
   * The mode of the sidebar menu.
   * @default "\"slideover\" as never"
   */
  mode?: T | undefined;
  /**
   * The props for the sidebar menu component.
   */
  menu?: DashboardSidebarMenu<T> | undefined;
  /**
   * Customize the toggle button to open the sidebar.
   * `{ color: 'neutral', variant: 'ghost' }`{lang="ts-type"}
   * @default "true"
   */
  toggle?: boolean | Omit<ButtonProps, LinkPropsKeys> | undefined;
  /**
   * The side to render the toggle button on.
   * @default "\"left\""
   */
  toggleSide?: "left" | "right" | undefined;
  /**
   * Automatically close when route changes.
   * @default "true"
   */
  autoClose?: boolean | undefined;
  ui?: { root?: SlotClass; header?: SlotClass; body?: SlotClass; footer?: SlotClass; toggle?: SlotClass; handle?: SlotClass; content?: SlotClass; overlay?: SlotClass; } | undefined;
  /**
   * The id of the panel.
   */
  id?: string | undefined;
  /**
   * The side to render the panel on.
   * @default "\"left\""
   */
  side?: "left" | "right" | undefined;
  /**
   * The minimum size of the panel.
   * @default "10"
   */
  minSize?: number | undefined;
  /**
   * The maximum size of the panel.
   * @default "20"
   */
  maxSize?: number | undefined;
  /**
   * The default size of the panel.
   * @default "15"
   */
  defaultSize?: number | undefined;
  /**
   * Whether to allow the user to resize the panel.
   * @default "false"
   */
  resizable?: boolean | undefined;
  /**
   * Whether to allow the user to collapse the panel.
   * @default "false"
   */
  collapsible?: boolean | undefined;
  /**
   * The size of the panel when collapsed.
   * @default "0"
   */
  collapsedSize?: number | undefined;
  /**
   * @default "false"
   */
  open?: boolean | undefined;
  /**
   * @default "false"
   */
  collapsed?: boolean | undefined;
}
```

### Slots

```ts
/**
 * Slots for the DashboardSidebar component
 */
interface DashboardSidebarSlots {
  header(): any;
  default(): any;
  footer(): any;
  toggle(): any;
  content(): any;
  resize-handle(): any;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    dashboardSidebar: {
      slots: {
        root: 'relative hidden lg:flex flex-col min-h-svh min-w-16 w-(--width) shrink-0',
        header: 'h-(--ui-header-height) shrink-0 flex items-center gap-1.5 px-4',
        body: 'flex flex-col gap-4 flex-1 overflow-y-auto px-4 py-2',
        footer: 'shrink-0 flex items-center gap-1.5 px-4 py-2',
        toggle: '',
        handle: '',
        content: 'lg:hidden',
        overlay: 'lg:hidden'
      },
      variants: {
        menu: {
          true: {
            header: 'sm:px-6',
            body: 'sm:px-6',
            footer: 'sm:px-6'
          }
        },
        side: {
          left: {
            root: 'border-e border-default'
          },
          right: {
            root: ''
          }
        },
        toggleSide: {
          left: {
            toggle: ''
          },
          right: {
            toggle: 'ms-auto'
          }
        }
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/DashboardSidebar.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/dashboard-sidebar.ts).


# DashboardSidebarCollapse

## Uso

O componente DashboardSidebarCollapse é usado para recolher/expandir o componente [DashboardSidebar](https://ui.nitro.news/docs/components/dashboard-sidebar) **quando a prop `collapsible` dele está definida**.

```vue
<template>
  <UDashboardSidebarCollapse />
</template>
```

Ele estende o componente [Button](https://ui.nitro.news/docs/components/button), então você pode passar qualquer propriedade como `color`, `variant`, `size`, etc.

```vue
<template>
  <UDashboardSidebarCollapse variant="subtle" />
</template>
```

> \[!NOTE]
>
> O botão usa por padrão `color="neutral"` e `variant="ghost"`.

## Exemplos

### Dentro do slot `header`

Você pode colocar este componente no slot `header` do componente [DashboardSidebar](https://ui.nitro.news/docs/components/dashboard-sidebar) e usar a prop `collapsed` para ocultar a parte esquerda do cabeçalho, por exemplo:

```vue [layouts/dashboard.vue] {4-8}
<template>
  <NDashboardGroup>
    <NDashboardSidebar collapsible>
      <template #header="{ collapsed }">
        <Logo v-if="!collapsed" />

        <NDashboardSidebarCollapse variant="subtle" />
      </template>
    </NDashboardSidebar>

    <slot />
  </NDashboardGroup>
</template>
```

### Dentro do slot `leading`

Você pode colocar este componente no slot `leading` do componente [DashboardNavbar](https://ui.nitro.news/docs/components/dashboard-navbar) para exibi-lo antes do título, por exemplo:

```vue [pages/index.vue] {11-13}
<script setup lang="ts">
definePageMeta({
  layout: 'dashboard'
})
</script>

<template>
  <NDashboardPanel>
    <template #header>
      <NDashboardNavbar title="Home">
        <template #leading>
          <NDashboardSidebarCollapse variant="subtle" />
        </template>
      </NDashboardNavbar>
    </template>
  </NDashboardPanel>
</template>
```

## API

### Props

```ts
/**
 * Props for the DashboardSidebarCollapse component
 */
interface DashboardSidebarCollapseProps {
  /**
   * @default "\"neutral\""
   */
  color?: "error" | "neutral" | "primary" | "secondary" | "accent" | "success" | "info" | "warning" | undefined;
  /**
   * @default "\"ghost\""
   */
  variant?: "ghost" | "solid" | "outline" | "soft" | "subtle" | "link" | undefined;
  /**
   * The side of the sidebar to collapse.
   * @default "\"left\""
   */
  side?: "left" | "right" | undefined;
  ui?: { base?: any; } | undefined;
  /**
   * Class to apply when the link is exact active
   */
  exactActiveClass?: string | undefined;
  /**
   * Pass the returned promise of `router.push()` to `document.startViewTransition()` if supported.
   */
  viewTransition?: boolean | undefined;
  autofocus?: Booleanish | undefined;
  disabled?: boolean | undefined;
  form?: string | undefined;
  formaction?: string | undefined;
  formenctype?: string | undefined;
  formmethod?: string | undefined;
  formnovalidate?: Booleanish | undefined;
  formtarget?: string | undefined;
  name?: string | undefined;
  /**
   * The type of the button when not a link.
   */
  type?: "reset" | "submit" | "button" | undefined;
  onClick?: ((event: MouseEvent) => void) | ((event: MouseEvent) => void)[] | undefined;
  /**
   * The element or component this component should render as when not a link.
   */
  as?: any;
  label?: string | undefined;
  activeColor?: "error" | "neutral" | "primary" | "secondary" | "accent" | "success" | "info" | "warning" | undefined;
  activeVariant?: "ghost" | "solid" | "outline" | "soft" | "subtle" | "link" | undefined;
  size?: "xs" | "sm" | "md" | "lg" | "xl" | undefined;
  /**
   * Render the button with equal padding on all sides.
   */
  square?: boolean | undefined;
  /**
   * Render the button full width.
   */
  block?: boolean | undefined;
  /**
   * Set loading state automatically based on the `@click` promise state
   */
  loadingAuto?: boolean | undefined;
  /**
   * Display an icon based on the `leading` and `trailing` props.
   */
  icon?: any;
  /**
   * Display an avatar on the left side.
   */
  avatar?: AvatarProps | undefined;
  /**
   * When `true`, the icon will be displayed on the left side.
   */
  leading?: boolean | undefined;
  /**
   * Display an icon on the left side.
   */
  leadingIcon?: any;
  /**
   * When `true`, the icon will be displayed on the right side.
   */
  trailing?: boolean | undefined;
  /**
   * Display an icon on the right side.
   */
  trailingIcon?: any;
  /**
   * When `true`, the loading icon will be displayed.
   */
  loading?: boolean | undefined;
  /**
   * The icon when the `loading` prop is `true`.
   */
  loadingIcon?: any;
}
```

> \[!NOTE]
> See: https\://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attributes
>
> Este componente também suporta todos os atributos HTML nativos de `<button>`.

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    dashboardSidebarCollapse: {
      base: 'hidden lg:flex',
      variants: {
        side: {
          left: '',
          right: ''
        }
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/DashboardSidebarCollapse.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/dashboard-sidebar-collapse.ts).


# DashboardSidebarToggle

## Uso

O componente DashboardSidebarToggle é usado pelos componentes [DashboardNavbar](https://ui.nitro.news/docs/components/dashboard-navbar) e [DashboardSidebar](https://ui.nitro.news/docs/components/dashboard-sidebar).

Ele é exibido automaticamente no mobile para abrir e fechar a sidebar, **você não precisa adicioná-lo manualmente**.

```vue
<template>
  <UDashboardSidebarToggle />
</template>
```

Ele estende o componente [Button](https://ui.nitro.news/docs/components/button), então você pode passar qualquer propriedade como `color`, `variant`, `size`, etc.

```vue
<template>
  <UDashboardSidebarToggle variant="subtle" />
</template>
```

> \[!NOTE]
>
> O botão usa por padrão `color="neutral"` e `variant="ghost"`.

## Exemplos

### Dentro do slot `toggle`

Embora este componente seja exibido automaticamente no mobile, você pode usar o slot `toggle` dos componentes [DashboardNavbar](https://ui.nitro.news/docs/components/dashboard-navbar) e [DashboardSidebar](https://ui.nitro.news/docs/components/dashboard-sidebar) para personalizar o botão.

```vue [layouts/dashboard.vue] {4-6}
<template>
  <NDashboardGroup>
    <NDashboardSidebar>
      <template #toggle>
        <NDashboardSidebarToggle variant="subtle" />
      </template>
    </NDashboardSidebar>

    <slot />
  </NDashboardGroup>
</template>
```

```vue [pages/index.vue] {11-13}
<script setup lang="ts">
definePageMeta({
  layout: 'dashboard'
})
</script>

<template>
  <NDashboardPanel>
    <template #header>
      <NDashboardNavbar title="Home">
        <template #toggle>
          <NDashboardSidebarToggle variant="subtle" />
        </template>
      </NDashboardNavbar>
    </template>
  </NDashboardPanel>
</template>
```

> \[!TIP]
>
> Ao usar a prop `toggle-side` dos componentes `DashboardSidebar` e `DashboardNavbar`, o botão será exibido no lado especificado.

## API

### Props

```ts
/**
 * Props for the DashboardSidebarToggle component
 */
interface DashboardSidebarToggleProps {
  /**
   * @default "\"neutral\""
   */
  color?: "error" | "neutral" | "primary" | "secondary" | "accent" | "success" | "info" | "warning" | undefined;
  /**
   * @default "\"ghost\""
   */
  variant?: "ghost" | "solid" | "outline" | "soft" | "subtle" | "link" | undefined;
  /**
   * The side of the sidebar to toggle.
   * @default "\"left\""
   */
  side?: "left" | "right" | undefined;
  ui?: { base?: any; } | undefined;
  /**
   * Class to apply when the link is exact active
   */
  exactActiveClass?: string | undefined;
  /**
   * Pass the returned promise of `router.push()` to `document.startViewTransition()` if supported.
   */
  viewTransition?: boolean | undefined;
  autofocus?: Booleanish | undefined;
  disabled?: boolean | undefined;
  form?: string | undefined;
  formaction?: string | undefined;
  formenctype?: string | undefined;
  formmethod?: string | undefined;
  formnovalidate?: Booleanish | undefined;
  formtarget?: string | undefined;
  name?: string | undefined;
  /**
   * The type of the button when not a link.
   */
  type?: "reset" | "submit" | "button" | undefined;
  onClick?: ((event: MouseEvent) => void) | ((event: MouseEvent) => void)[] | undefined;
  /**
   * The element or component this component should render as when not a link.
   */
  as?: any;
  label?: string | undefined;
  activeColor?: "error" | "neutral" | "primary" | "secondary" | "accent" | "success" | "info" | "warning" | undefined;
  activeVariant?: "ghost" | "solid" | "outline" | "soft" | "subtle" | "link" | undefined;
  size?: "xs" | "sm" | "md" | "lg" | "xl" | undefined;
  /**
   * Render the button with equal padding on all sides.
   */
  square?: boolean | undefined;
  /**
   * Render the button full width.
   */
  block?: boolean | undefined;
  /**
   * Set loading state automatically based on the `@click` promise state
   */
  loadingAuto?: boolean | undefined;
  /**
   * Display an icon based on the `leading` and `trailing` props.
   */
  icon?: any;
  /**
   * Display an avatar on the left side.
   */
  avatar?: AvatarProps | undefined;
  /**
   * When `true`, the icon will be displayed on the left side.
   */
  leading?: boolean | undefined;
  /**
   * Display an icon on the left side.
   */
  leadingIcon?: any;
  /**
   * When `true`, the icon will be displayed on the right side.
   */
  trailing?: boolean | undefined;
  /**
   * Display an icon on the right side.
   */
  trailingIcon?: any;
  /**
   * When `true`, the loading icon will be displayed.
   */
  loading?: boolean | undefined;
  /**
   * The icon when the `loading` prop is `true`.
   */
  loadingIcon?: any;
}
```

> \[!NOTE]
> See: https\://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attributes
>
> Este componente também suporta todos os atributos HTML nativos de `<button>`.

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    dashboardSidebarToggle: {
      base: 'lg:hidden',
      variants: {
        side: {
          left: '',
          right: ''
        }
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/DashboardSidebarToggle.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/dashboard-sidebar-toggle.ts).


# DashboardToolbar

## Uso

O componente DashboardToolbar é usado para exibir uma barra de ferramentas abaixo do componente [DashboardNavbar](https://ui.nitro.news/docs/components/dashboard-navbar).

Use-o dentro do slot `header` do componente [DashboardPanel](https://ui.nitro.news/docs/components/dashboard-panel):

```vue [pages/index.vue] {9-13}
<script setup lang="ts">
definePageMeta({
  layout: 'dashboard'
})
</script>

<template>
  <NDashboardPanel>
    <template #header>
      <NDashboardNavbar />

      <NDashboardToolbar />
    </template>
  </NDashboardPanel>
</template>
```

Use os slots `left`, `default` e `right` para personalizar a barra de ferramentas.

::component-example
---
prettier: true
props:
  class: w-full
class: "!px-0 !pt-0"
name: dashboard-toolbar-example
---
::

> \[!NOTE]
>
> Neste exemplo, usamos o componente [NavigationMenu](https://ui.nitro.news/docs/components/navigation-menu) para renderizar alguns links.

## API

### Props

```ts
/**
 * Props for the DashboardToolbar component
 */
interface DashboardToolbarProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  ui?: { root?: SlotClass; left?: SlotClass; right?: SlotClass; } | undefined;
}
```

### Slots

```ts
/**
 * Slots for the DashboardToolbar component
 */
interface DashboardToolbarSlots {
  default(): any;
  left(): any;
  right(): any;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    dashboardToolbar: {
      slots: {
        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]',
        left: 'flex items-center gap-1.5',
        right: 'flex items-center gap-1.5'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/DashboardToolbar.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/dashboard-toolbar.ts).


# Drawer

## Uso

Use a [Button](https://ui.nitro.news/docs/components/button) or any other component in the default slot of the Drawer.

Depois, use o slot `#content` para adicionar o conteúdo exibido quando o Drawer está aberto.

```vue
<template>
  <UDrawer>
    <NButton label="Open" color="neutral" variant="subtle" trailing-icon="i-lucide-chevron-up" />
  
    <template #content>
      <Placeholder class="h-48 m-4" />
    </template></UDrawer>
</template>
```

Você também pode usar os slots `#header`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, `#body`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} e `#footer`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} para personalizar o conteúdo do Drawer.

### Título

Use a prop `title` para definir o título do cabeçalho do Drawer.

```vue
<template>
  <UDrawer title="Drawer with title">
    <NButton label="Open" color="neutral" variant="subtle" trailing-icon="i-lucide-chevron-up" />
  
    <template #body>
      <Placeholder class="h-48" />
    </template></UDrawer>
</template>
```

### Descrição

Use a prop `description` para definir a descrição do cabeçalho do Drawer.

```vue
<template>
  <UDrawer title="Drawer with description" description="Lorem ipsum dolor sit amet, consectetur adipiscing elit.">
    <NButton label="Open" color="neutral" variant="subtle" trailing-icon="i-lucide-chevron-up" />
  
    <template #body>
      <Placeholder class="h-48" />
    </template></UDrawer>
</template>
```

### Fechar `Soon`

Use a prop `close` para exibir um botão de fechar no Drawer. O padrão é `false`.

Você pode passar qualquer propriedade do componente [Button](https://ui.nitro.news/docs/components/button) para personalizá-lo.

```vue
<template>
  <UDrawer title="Drawer with close button" :close="{
  color: 'primary',
  variant: 'outline',
  class: 'rounded-full'
}">
    <NButton label="Open" color="neutral" variant="subtle" trailing-icon="i-lucide-chevron-up" />
  
    <template #body>
      <Placeholder class="h-48" />
    </template></UDrawer>
</template>
```

### Ícone de fechar `Soon`

Use a prop `close-icon` para personalizar o [Icon](https://ui.nitro.news/docs/components/icon) do botão de fechar. O padrão é `i-lucide-x`.

```vue
<template>
  <UDrawer title="Drawer with close button" close close-icon="i-lucide-arrow-right">
    <NButton label="Open" color="neutral" variant="subtle" trailing-icon="i-lucide-chevron-up" />
  
    <template #body>
      <Placeholder class="h-48" />
    </template></UDrawer>
</template>
```

### Direção

Use a prop `direction` para controlar a direção do Drawer. O padrão é `bottom`.

```vue
<template>
  <UDrawer direction="right">
    <NButton label="Open" color="neutral" variant="subtle" trailing-icon="i-lucide-chevron-up" />
  
    <template #content>
      <Placeholder class="min-w-96 min-h-96 size-full m-4" />
    </template></UDrawer>
</template>
```

### Inset

Use a prop `inset` para recuar o Drawer em relação às bordas.

```vue
<template>
  <UDrawer direction="right" inset>
    <NButton label="Open" color="neutral" variant="subtle" trailing-icon="i-lucide-chevron-up" />
  
    <template #content>
      <Placeholder class="min-w-96 min-h-96 size-full m-4" />
    </template></UDrawer>
</template>
```

### Alça

Use a prop `handle` para controlar se o Drawer tem uma alça ou não. O padrão é `true`.

```vue
<template>
  <UDrawer :handle="false">
    <NButton label="Open" color="neutral" variant="subtle" trailing-icon="i-lucide-chevron-up" />
  
    <template #content>
      <Placeholder class="h-48 m-4" />
    </template></UDrawer>
</template>
```

### Somente a alça

Use a prop `handle-only` para permitir que o Drawer seja arrastado apenas pela alça.

```vue
<template>
  <UDrawer handle-only>
    <NButton label="Open" color="neutral" variant="subtle" trailing-icon="i-lucide-chevron-up" />
  
    <template #content>
      <Placeholder class="h-48 m-4" />
    </template></UDrawer>
</template>
```

### Overlay

Use a prop `overlay` para controlar se o Drawer tem um overlay ou não. O padrão é `true`.

```vue
<template>
  <UDrawer :overlay="false">
    <NButton label="Open" color="neutral" variant="subtle" trailing-icon="i-lucide-chevron-up" />
  
    <template #content>
      <Placeholder class="h-48 m-4" />
    </template></UDrawer>
</template>
```

### Modal

Use a prop `modal` para controlar se o Drawer bloqueia a interação com o conteúdo externo. O padrão é `true`.

> \[!NOTE]
>
> Quando `modal` é definido como `false`, o overlay é automaticamente desabilitado e o conteúdo externo se torna interativo.

```vue
<template>
  <UDrawer :modal="false">
    <NButton label="Open" color="neutral" variant="subtle" trailing-icon="i-lucide-chevron-up" />
  
    <template #content>
      <Placeholder class="h-48 m-4" />
    </template></UDrawer>
</template>
```

### Dispensável

Use a prop `dismissible` para controlar se o Drawer pode ser dispensado ao clicar fora dele ou pressionar escape. O padrão é `true`.

> \[!NOTE]
>
> Um evento `close:prevent` será emitido quando o usuário tentar fechá-lo.

> \[!TIP]
>
> Você pode combinar `modal: false` com `dismissible: false` para tornar o fundo do Drawer interativo sem fechá-lo.

::component-example{prettier name="drawer-dismissible-example"}
::

### Escalar o fundo

Use a prop `should-scale-background` para escalar o fundo quando o Drawer está aberto, criando um efeito visual de profundidade. Você pode definir a prop `set-background-color-on-scale` como `false` para evitar a mudança da cor de fundo.

```vue
<template>
  <UDrawer should-scale-background set-background-color-on-scale>
    <NButton label="Open" color="neutral" variant="subtle" trailing-icon="i-lucide-chevron-up" />
  
    <template #content>
      <Placeholder class="h-48 m-4" />
    </template></UDrawer>
</template>
```

> \[!WARNING]
>
> Certifique-se de adicionar a diretiva `data-vaul-drawer-wrapper` a um elemento pai do seu app para que isso funcione.
>
> ```vue [app.vue]
> <template>
>   <NApp>
>     <div class="bg-default" data-vaul-drawer-wrapper>
>       <NuxtLayout>
>         <NuxtPage />
>       </NuxtLayout>
>     </div>
>   </NApp>
> </template>
> ```
>
> ```ts [nuxt.config.ts]
> export default defineNuxtConfig({
>   app: {
>     rootAttrs: {
>       'data-vaul-drawer-wrapper': '',
>       'class': 'bg-default'
>     }
>   }
> })
> ```

## Exemplos

### Controlar o estado de abertura

Você pode controlar o estado de abertura usando a prop `default-open` ou a diretiva `v-model:open`.

::component-example{prettier name="drawer-open-example"}
::

> \[!NOTE]
>
> Neste exemplo, aproveitando o [`defineShortcuts`](https://ui.nitro.news/docs/composables/define-shortcuts), você pode abrir e fechar o Drawer pressionando :kbd{value="O"}.

> \[!TIP]
>
> Isso permite mover o gatilho para fora do Drawer ou removê-lo por completo.

### Gaveta responsiva

Você pode renderizar um componente [Modal](https://ui.nitro.news/docs/components/modal) no desktop e um Drawer no mobile, por exemplo.

::component-example{prettier name="drawer-responsive-example"}
::

### Gavetas aninhadas

Você pode aninhar gavetas umas dentro das outras usando a prop `nested`.

::component-example{prettier name="drawer-nested-example"}
::

### Com slot de rodapé

Use o slot `#footer` para adicionar conteúdo após o corpo do Drawer.

::component-example{collapse prettier name="drawer-footer-slot-example"}
::

### Com paleta de comandos

Você pode usar um componente [CommandPalette](https://ui.nitro.news/docs/components/command-palette) dentro do conteúdo do Drawer.

::component-example{collapse name="drawer-command-palette-example"}
::

> \[!NOTE]
>
> Este exemplo usa `useLazyFetch` com `immediate: false` para buscar os dados apenas quando o Drawer abre.

## API

### Props

```ts
/**
 * Props for the Drawer component
 */
interface DrawerProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  title?: string | undefined;
  description?: string | undefined;
  /**
   * Whether to inset the drawer from the edges.
   */
  inset?: boolean | undefined;
  /**
   * The content of the drawer.
   */
  content?: (Omit<DialogContentProps, "as" | "asChild" | "forceMount"> & Partial<EmitsToProps<DialogContentImplEmits>>) | undefined;
  /**
   * Render an overlay behind the drawer.
   * @default "true"
   */
  overlay?: boolean | undefined;
  /**
   * Render a handle on the drawer.
   * @default "true"
   */
  handle?: boolean | undefined;
  /**
   * Render the drawer in a portal.
   * @default "true"
   */
  portal?: string | boolean | HTMLElement | undefined;
  /**
   * Whether the drawer is nested in another drawer.
   */
  nested?: boolean | undefined;
  ui?: { overlay?: SlotClass; content?: SlotClass; handle?: SlotClass; container?: SlotClass; header?: SlotClass; title?: SlotClass; description?: SlotClass; body?: SlotClass; footer?: SlotClass; } | undefined;
  /**
   * When `false` it allows to interact with elements outside of the drawer without closing it.
   * @default "true"
   */
  modal?: boolean | undefined;
  open?: boolean | undefined;
  activeSnapPoint?: string | number | null | undefined;
  /**
   * Number between 0 and 1 that determines when the drawer should be closed.
   * Example: threshold of 0.5 would close the drawer if the user swiped for 50% of the height of the drawer or more.
   */
  closeThreshold?: number | undefined;
  shouldScaleBackground?: boolean | undefined;
  /**
   * When `false` we don't change body's background color when the drawer is open.
   */
  setBackgroundColorOnScale?: boolean | undefined;
  /**
   * Duration for which the drawer is not draggable after scrolling content inside of the drawer.
   */
  scrollLockTimeout?: number | undefined;
  /**
   * When `true`, don't move the drawer upwards if there's space, but rather only change it's height so it's fully scrollable when the keyboard is open
   */
  fixed?: boolean | undefined;
  /**
   * When `false` dragging, clicking outside, pressing esc, etc. will not close the drawer.
   * Use this in combination with the `open` prop, otherwise you won't be able to open/close the drawer.
   * @default "true"
   */
  dismissible?: boolean | undefined;
  /**
   * Opened by default, skips initial enter animation. Still reacts to `open` state changes
   */
  defaultOpen?: boolean | undefined;
  /**
   * Direction of the drawer. Can be `top` or `bottom`, `left`, `right`.
   * @default "\"bottom\""
   */
  direction?: DrawerDirection | undefined;
  /**
   * When `true` the `body` doesn't get any styles assigned from Vaul
   */
  noBodyStyles?: boolean | undefined;
  /**
   * When `true` only allows the drawer to be dragged by the `<Drawer.Handle />` component.
   */
  handleOnly?: boolean | undefined;
  preventScrollRestoration?: boolean | undefined;
  /**
   * Array of numbers from 0 to 100 that corresponds to % of the screen a given snap point should take up.
   * Should go from least visible. Example `[0.2, 0.5, 0.8]`.
   * You can also use px values, which doesn't take screen height into account.
   */
  snapPoints?: (string | number)[] | undefined;
}
```

### Slots

```ts
/**
 * Slots for the Drawer component
 */
interface DrawerSlots {
  default(): any;
  content(): any;
  header(): any;
  title(): any;
  description(): any;
  body(): any;
  footer(): any;
}
```

### Emits

```ts
/**
 * Emitted events for the Drawer component
 */
interface DrawerEmits {
  update:open: (payload: [open: boolean]) => void;
  drag: (payload: [percentageDragged: number]) => void;
  close: (payload: []) => void;
  close:prevent: (payload: []) => void;
  release: (payload: [open: boolean]) => void;
  update:activeSnapPoint: (payload: [val: string | number]) => void;
  animationEnd: (payload: [open: boolean]) => void;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    drawer: {
      slots: {
        overlay: 'fixed inset-0 bg-elevated/75',
        content: 'fixed bg-default ring ring-default flex focus:outline-none',
        handle: 'shrink-0 !bg-accented transition-opacity',
        container: 'w-full flex flex-col gap-4 p-4 overflow-y-auto',
        header: '',
        title: 'text-highlighted font-semibold',
        description: 'mt-1 text-muted text-sm',
        body: 'flex-1',
        footer: 'flex flex-col gap-1.5'
      },
      variants: {
        direction: {
          top: {
            content: 'mb-24 flex-col-reverse',
            handle: 'mb-4'
          },
          right: {
            content: 'flex-row',
            handle: '!ml-4'
          },
          bottom: {
            content: 'mt-24 flex-col',
            handle: 'mt-4'
          },
          left: {
            content: 'flex-row-reverse',
            handle: '!mr-4'
          }
        },
        inset: {
          true: {
            content: 'rounded-lg after:hidden overflow-hidden [--initial-transform:calc(100%+1.5rem)]'
          }
        },
        snapPoints: {
          true: ''
        }
      },
      compoundVariants: [
        {
          direction: [
            'top',
            'bottom'
          ],
          class: {
            content: 'h-auto max-h-[96%]',
            handle: '!w-12 !h-1.5 mx-auto'
          }
        },
        {
          direction: [
            'top',
            'bottom'
          ],
          snapPoints: true,
          class: {
            content: 'h-full'
          }
        },
        {
          direction: [
            'right',
            'left'
          ],
          class: {
            content: 'w-auto max-w-[calc(100%-2rem)]',
            handle: '!h-12 !w-1.5 mt-auto mb-auto'
          }
        },
        {
          direction: [
            'right',
            'left'
          ],
          snapPoints: true,
          class: {
            content: 'w-full'
          }
        },
        {
          direction: 'top',
          inset: true,
          class: {
            content: 'inset-x-4 top-4'
          }
        },
        {
          direction: 'top',
          inset: false,
          class: {
            content: 'inset-x-0 top-0 rounded-b-lg'
          }
        },
        {
          direction: 'bottom',
          inset: true,
          class: {
            content: 'inset-x-4 bottom-4'
          }
        },
        {
          direction: 'bottom',
          inset: false,
          class: {
            content: 'inset-x-0 bottom-0 rounded-t-lg'
          }
        },
        {
          direction: 'left',
          inset: true,
          class: {
            content: 'inset-y-4 left-4'
          }
        },
        {
          direction: 'left',
          inset: false,
          class: {
            content: 'inset-y-0 left-0 rounded-r-lg'
          }
        },
        {
          direction: 'right',
          inset: true,
          class: {
            content: 'inset-y-4 right-4'
          }
        },
        {
          direction: 'right',
          inset: false,
          class: {
            content: 'inset-y-0 right-0 rounded-l-lg'
          }
        }
      ]
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/Drawer.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/drawer.ts).


# DropdownMenu

## Uso

Use a [Button](https://ui.nitro.news/docs/components/button) or any other component in the default slot of the DropdownMenu.

```vue
<script setup lang="ts">
import type { DropdownMenuItem } from '@nitro/ui'

const items = ref<DropdownMenuItem[][]>([
  [
    {
      label: "Benjamin",
      avatar: {
        src: "https://github.com/benjamincanac.png",
        loading: "lazy"
      },
      type: "label"
    }
  ],
  [
    {
      label: "Profile",
      icon: "i-lucide-user"
    },
    {
      label: "Billing",
      icon: "i-lucide-credit-card"
    },
    {
      label: "Settings",
      icon: "i-lucide-cog",
      kbds: [
        ","
      ]
    },
    {
      label: "Keyboard shortcuts",
      icon: "i-lucide-monitor"
    }
  ],
  [
    {
      label: "Team",
      icon: "i-lucide-users",
      filter: {
        placeholder: "Search members..."
      },
      children: [
        [
          {
            label: "benjamincanac",
            avatar: {
              src: "https://github.com/benjamincanac.png",
              loading: "lazy"
            }
          },
          {
            label: "HugoRCD",
            avatar: {
              src: "https://github.com/HugoRCD.png",
              loading: "lazy"
            }
          },
          {
            label: "romhml",
            avatar: {
              src: "https://github.com/romhml.png",
              loading: "lazy"
            }
          },
          {
            label: "sandros94",
            avatar: {
              src: "https://github.com/sandros94.png",
              loading: "lazy"
            }
          },
          {
            label: "hywax",
            avatar: {
              src: "https://github.com/hywax.png",
              loading: "lazy"
            }
          },
          {
            label: "J-Michalek",
            avatar: {
              src: "https://github.com/J-Michalek.png",
              loading: "lazy"
            }
          },
          {
            label: "genu",
            avatar: {
              src: "https://github.com/genu.png",
              loading: "lazy"
            }
          }
        ]
      ]
    },
    {
      label: "Invite users",
      icon: "i-lucide-user-plus",
      children: [
        [
          {
            label: "Email",
            icon: "i-lucide-mail"
          },
          {
            label: "Message",
            icon: "i-lucide-message-square"
          }
        ],
        [
          {
            label: "More",
            icon: "i-lucide-circle-plus",
            children: [
              {
                label: "Import from Slack",
                icon: "i-simple-icons-slack",
                to: "https://slack.com",
                target: "_blank"
              },
              {
                label: "Import from Trello",
                icon: "i-simple-icons-trello"
              },
              {
                label: "Import from Asana",
                icon: "i-simple-icons-asana"
              }
            ]
          }
        ]
      ]
    },
    {
      label: "New team",
      icon: "i-lucide-plus",
      kbds: [
        "meta",
        "n"
      ]
    }
  ],
  [
    {
      label: "GitLab",
      icon: "i-simple-icons-gitlab",
      to: "https://github.com/nuxt/ui",
      target: "_blank"
    },
    {
      label: "Support",
      icon: "i-lucide-life-buoy",
      to: "/docs/components/dropdown-menu"
    },
    {
      label: "API",
      icon: "i-lucide-cloud",
      disabled: true
    }
  ],
  [
    {
      label: "Logout",
      icon: "i-lucide-log-out",
      color: "error",
      kbds: [
        "shift",
        "meta",
        "q"
      ]
    }
  ]
])
</script>

<template>
  <UDropdownMenu :items="items">
    <NButton icon="i-lucide-menu" color="neutral" variant="outline" />
  </UDropdownMenu>
</template>
```

### Itens

Use a prop `items` como um array de objetos com as seguintes propriedades:

- `label?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `icon?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `avatar?: AvatarProps`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `kbds?: string[] | KbdProps[]`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- [`type?: "link" | "label" | "separator" | "checkbox"`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}](https://ui.nitro.news/#with-checkbox-items)
- [`color?: "error" | "primary" | "secondary" | "success" | "info" | "warning" | "neutral"`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}](https://ui.nitro.news/#with-color-items)
- [`checked?: boolean`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}](https://ui.nitro.news/#with-checkbox-items)
- `disabled?: boolean`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- [`slot?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}](https://ui.nitro.news/#with-custom-slot)
- `onSelect?: (e: Event) => void`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- [`onUpdateChecked?: (checked: boolean) => void`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}](https://ui.nitro.news/#with-checkbox-items)
- `children?: DropdownMenuItem[] | DropdownMenuItem[][]`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- [`filter?: boolean | InputProps`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}](https://ui.nitro.news/#with-filter-items)
- `filterFields?: string[]`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `ignoreFilter?: boolean`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `class?: any`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `ui?: { item?: ClassNameValue, label?: ClassNameValue, separator?: ClassNameValue, itemLeadingIcon?: ClassNameValue, itemLeadingAvatarSize?: ClassNameValue, itemLeadingAvatar?: ClassNameValue, itemLabel?: ClassNameValue, itemLabelExternalIcon?: ClassNameValue, itemTrailing?: ClassNameValue, itemTrailingIcon?: ClassNameValue, itemTrailingKbds?: ClassNameValue, itemTrailingKbdsSize?: ClassNameValue }`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Você pode passar qualquer propriedade do componente [Link](https://ui.nitro.news/docs/components/link#props), como `to`, `target`, etc.

```vue
<script setup lang="ts">
import type { DropdownMenuItem } from '@nitro/ui'

const items = ref<DropdownMenuItem[][]>([
  [
    {
      label: "Benjamin",
      avatar: {
        src: "https://github.com/benjamincanac.png",
        loading: "lazy"
      },
      type: "label"
    }
  ],
  [
    {
      label: "Profile",
      icon: "i-lucide-user"
    },
    {
      label: "Billing",
      icon: "i-lucide-credit-card"
    },
    {
      label: "Settings",
      icon: "i-lucide-cog",
      kbds: [
        ","
      ]
    },
    {
      label: "Keyboard shortcuts",
      icon: "i-lucide-monitor"
    }
  ],
  [
    {
      label: "Team",
      icon: "i-lucide-users"
    },
    {
      label: "Invite users",
      icon: "i-lucide-user-plus",
      children: [
        [
          {
            label: "Email",
            icon: "i-lucide-mail"
          },
          {
            label: "Message",
            icon: "i-lucide-message-square"
          }
        ],
        [
          {
            label: "More",
            icon: "i-lucide-circle-plus",
            children: [
              {
                label: "Import from Slack",
                icon: "i-simple-icons-slack",
                to: "https://slack.com",
                target: "_blank"
              },
              {
                label: "Import from Trello",
                icon: "i-simple-icons-trello"
              },
              {
                label: "Import from Asana",
                icon: "i-simple-icons-asana"
              }
            ]
          }
        ]
      ]
    },
    {
      label: "New team",
      icon: "i-lucide-plus",
      kbds: [
        "meta",
        "n"
      ]
    }
  ],
  [
    {
      label: "GitLab",
      icon: "i-simple-icons-gitlab",
      to: "https://github.com/nuxt/ui",
      target: "_blank"
    },
    {
      label: "Support",
      icon: "i-lucide-life-buoy",
      to: "/docs/components/dropdown-menu"
    },
    {
      label: "API",
      icon: "i-lucide-cloud",
      disabled: true
    }
  ],
  [
    {
      label: "Logout",
      icon: "i-lucide-log-out",
      kbds: [
        "shift",
        "meta",
        "q"
      ]
    }
  ]
])
</script>

<template>
  <UDropdownMenu :items="items" :ui="{
  content: 'w-48'
}">
    <NButton icon="i-lucide-menu" color="neutral" variant="outline" />
  </UDropdownMenu>
</template>
```

> \[!NOTE]
>
> Você também pode passar um array de arrays para a prop `items` para criar grupos separados de itens.

> \[!TIP]
>
> Cada item pode receber um array `children` de objetos com as mesmas propriedades da prop `items` para criar um menu aninhado que pode ser controlado usando as propriedades `open`, `defaultOpen` e `content`.

### Conteúdo

Use a prop `content` para controlar como o conteúdo do DropdownMenu é renderizado, como seu `align` ou `side`, por exemplo.

```vue
<script setup lang="ts">
import type { DropdownMenuItem } from '@nitro/ui'

const items = ref<DropdownMenuItem[]>([
  {
    label: "Profile",
    icon: "i-lucide-user"
  },
  {
    label: "Billing",
    icon: "i-lucide-credit-card"
  },
  {
    label: "Settings",
    icon: "i-lucide-cog"
  }
])
</script>

<template>
  <UDropdownMenu :items="items" :content="{
  align: 'start',
  side: 'bottom',
  sideOffset: 8
}" :ui="{
  content: 'w-48'
}">
    <NButton label="Open" icon="i-lucide-menu" color="neutral" variant="outline" />
  </UDropdownMenu>
</template>
```

### Filtro `4.6+`

Use a prop `filter` para exibir um campo de filtro dentro do DropdownMenu. O padrão é `false`.

> \[!NOTE]
> See: #with-ignore-filter
>
> Use a prop `ignore-filter` para desabilitar a busca interna e usar sua própria lógica de busca.

> \[!NOTE]
> See: #with-filter-fields
>
> Use a prop `filter-fields` para especificar por quais campos filtrar. Por padrão, ela usa a prop `labelKey`.

Você pode passar qualquer propriedade do componente [Input](https://ui.nitro.news/docs/components/input) para personalizá-lo.

```vue
<script setup lang="ts">
import type { DropdownMenuItem } from '@nitro/ui'

const items = ref<DropdownMenuItem[]>([
  {
    label: "Profile",
    icon: "i-lucide-user"
  },
  {
    label: "Billing",
    icon: "i-lucide-credit-card"
  },
  {
    label: "Settings",
    icon: "i-lucide-cog"
  },
  {
    label: "Team",
    icon: "i-lucide-users"
  },
  {
    label: "Invite users",
    icon: "i-lucide-user-plus"
  },
  {
    label: "New team",
    icon: "i-lucide-plus"
  }
])
</script>

<template>
  <UDropdownMenu :filter="{
  icon: 'i-lucide-search'
}" :items="items" :content="{
  align: 'start'
}" :ui="{
  content: 'w-48'
}">
    <NButton label="Open" icon="i-lucide-menu" color="neutral" variant="outline" />
  </UDropdownMenu>
</template>
```

> \[!TIP]
> See: #with-filter-items
>
> Você também pode habilitar o filtro em submenus específicos usando o campo `filter` em itens com `children`.

### Seta

Use a prop `arrow` para exibir uma seta no DropdownMenu.

```vue
<script setup lang="ts">
import type { DropdownMenuItem } from '@nitro/ui'

const items = ref<DropdownMenuItem[]>([
  {
    label: "Profile",
    icon: "i-lucide-user"
  },
  {
    label: "Billing",
    icon: "i-lucide-credit-card"
  },
  {
    label: "Settings",
    icon: "i-lucide-cog"
  }
])
</script>

<template>
  <UDropdownMenu arrow :items="items" :ui="{
  content: 'w-48'
}">
    <NButton label="Open" icon="i-lucide-menu" color="neutral" variant="outline" />
  </UDropdownMenu>
</template>
```

### Tamanho

Use a prop `size` para controlar o tamanho do DropdownMenu.

```vue
<script setup lang="ts">
import type { DropdownMenuItem } from '@nitro/ui'

const items = ref<DropdownMenuItem[]>([
  {
    label: "Profile",
    icon: "i-lucide-user"
  },
  {
    label: "Billing",
    icon: "i-lucide-credit-card"
  },
  {
    label: "Settings",
    icon: "i-lucide-cog"
  }
])
</script>

<template>
  <UDropdownMenu size="xl" :items="items" :content="{
  align: 'start'
}" :ui="{
  content: 'w-48'
}">
    <NButton size="xl" label="Open" icon="i-lucide-menu" color="neutral" variant="outline" />
  </UDropdownMenu>
</template>
```

> \[!WARNING]
>
> A prop `size` não é repassada ao Button; você precisa defini-la você mesmo.

> \[!NOTE]
>
> Ao usar o mesmo tamanho, os itens do DropdownMenu ficarão perfeitamente alinhados com o Button.

### Modal

Use a prop `modal` para controlar se o DropdownMenu bloqueia a interação com o conteúdo externo. O padrão é `true`.

```vue
<script setup lang="ts">
import type { DropdownMenuItem } from '@nitro/ui'

const items = ref<DropdownMenuItem[]>([
  {
    label: "Profile",
    icon: "i-lucide-user"
  },
  {
    label: "Billing",
    icon: "i-lucide-credit-card"
  },
  {
    label: "Settings",
    icon: "i-lucide-cog"
  }
])
</script>

<template>
  <UDropdownMenu :modal="false" :items="items" :ui="{
  content: 'w-48'
}">
    <NButton label="Open" icon="i-lucide-menu" color="neutral" variant="outline" />
  </UDropdownMenu>
</template>
```

### Desabilitado

Use a prop `disabled` para desabilitar o DropdownMenu.

```vue
<script setup lang="ts">
import type { DropdownMenuItem } from '@nitro/ui'

const items = ref<DropdownMenuItem[]>([
  {
    label: "Profile",
    icon: "i-lucide-user"
  },
  {
    label: "Billing",
    icon: "i-lucide-credit-card"
  },
  {
    label: "Settings",
    icon: "i-lucide-cog"
  }
])
</script>

<template>
  <UDropdownMenu disabled :items="items" :ui="{
  content: 'w-48'
}">
    <NButton label="Open" icon="i-lucide-menu" color="neutral" variant="outline" />
  </UDropdownMenu>
</template>
```

## Exemplos

### Com itens de checkbox

Você pode usar a propriedade `type` com `checkbox` e usar as propriedades `checked` / `onUpdateChecked` para controlar o estado marcado do item.

::component-example{collapse name="dropdown-menu-checkbox-items-example"}
::

> \[!NOTE]
>
> Para garantir a reatividade do estado `checked` dos itens, é recomendado envolver seu array `items` dentro de um `computed`.

### Com itens de cor

Você pode usar a propriedade `color` para destacar certos itens com uma cor.

::component-example{collapse name="dropdown-menu-color-items-example"}
::

### Com itens de filtro `4.6+`

Você pode usar a propriedade `filter` em itens com `children` para exibir um campo de filtro dentro do submenu.

::component-example{collapse name="dropdown-menu-filter-items-example"}
::

### Controlar o estado de abertura

Você pode controlar o estado de abertura usando a prop `default-open` ou a diretiva `v-model:open`.

::component-example{collapse name="dropdown-menu-open-example"}
::

> \[!NOTE]
>
> Neste exemplo, aproveitando o [`defineShortcuts`](https://ui.nitro.news/docs/composables/define-shortcuts), você pode abrir e fechar o DropdownMenu pressionando :kbd{value="O"}.

### Com slot personalizado

Use a propriedade `slot` para personalizar um item específico.

Você terá acesso aos seguintes slots:

- `#{{ item.slot }}`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `#{{ item.slot }}-leading`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `#{{ item.slot }}-label`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `#{{ item.slot }}-trailing`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

::component-example{collapse name="dropdown-menu-custom-slot-example"}
::

> \[!TIP]
> See: #slots
>
> Você também pode usar os slots `#item`, `#item-leading`, `#item-label` e `#item-trailing` para personalizar todos os itens.

### Com switch nos itens

Você pode usar a propriedade `slot` com um slot `#{{ slot }}-trailing` para renderizar um [Switch](https://ui.nitro.news/docs/components/switch) dentro de um item.

::component-example{collapse name="dropdown-menu-switch-items-example"}
::

### Com filtro ignorado `4.6+`

Ao usar a prop `filter` ou o campo `filter` em itens com `children`, você pode definir a prop `ignore-filter` como `true` para desabilitar a busca interna e usar sua própria lógica de busca.

::component-example{collapse name="dropdown-menu-ignore-filter-example"}
::

> \[!NOTE]
>
> Este exemplo usa [`refDebounced`](https://vueuse.org/shared/refDebounced/#refdebounced){rel="&#x22;nofollow&#x22;"} para aplicar debounce nas chamadas de API. A busca é adiada com `immediate: false`, então nenhuma requisição é feita até o menu abrir.

### Com campos de filtro `4.6+`

Ao usar a prop `filter` ou o campo `filter` em itens com `children`, você pode definir a prop `filter-fields` com um array de campos para filtrar. O padrão é `[labelKey]`.

::component-example{collapse name="dropdown-menu-filter-fields-example"}
::

### Com largura do conteúdo do gatilho

Você pode expandir o conteúdo até a largura total do seu botão adicionando a classe `w-(--reka-dropdown-menu-trigger-width)` no slot `ui.content`.

::component-example{collapse name="dropdown-menu-content-width-example"}
::

> \[!TIP]
>
> Você também pode alterar a largura do conteúdo globalmente no seu `app.config.ts`:
>
> ```text
> export default defineAppConfig({
>   ui: {
>     dropdownMenu: {
>       slots: {
>         content: 'w-(--reka-dropdown-menu-trigger-width)'
>       }
>     }
>   }
> })
> ```

### Extrair atalhos

Use o utilitário [extractShortcuts](https://ui.nitro.news/docs/composables/extract-shortcuts) para definir automaticamente atalhos a partir de itens de menu com uma propriedade `kbds`. Ele extrai os atalhos recursivamente e retorna um objeto compatível com [defineShortcuts](https://ui.nitro.news/docs/composables/define-shortcuts).

```vue
<script setup lang="ts">
import type { DropdownMenuItem } from '@nitro/ui'

const items: DropdownMenuItem[] = [{
  label: 'Invite users',
  icon: 'i-lucide-user-plus',
  children: [{
    label: 'Invite by email',
    icon: 'i-lucide-send-horizontal',
    kbds: ['meta', 'e'],
    onSelect() {
      console.log('Invite by email clicked')
    }
  }, {
    label: 'Invite by link',
    icon: 'i-lucide-link',
    kbds: ['meta', 'i'],
    onSelect() {
      console.log('Invite by link clicked')
    }
  }]
}, {
  label: 'New team',
  icon: 'i-lucide-plus',
  kbds: ['meta', 'n'],
  onSelect() {
    console.log('New team clicked')
  }
}]

defineShortcuts(extractShortcuts(items))
</script>
```

> \[!NOTE]
>
> Neste exemplo, :kbd{value="meta"} :kbd{.ms-px value="E"}, :kbd{value="meta"} :kbd{.ms-px value="I"} e :kbd{value="meta"} :kbd{.ms-px value="N"} disparariam a função `select` do item correspondente.

## API

### Props

```ts
/**
 * Props for the DropdownMenu component
 */
interface DropdownMenuProps {
  size?: "sm" | "md" | "xs" | "lg" | "xl" | undefined;
  items?: T | undefined;
  /**
   * The icon displayed when an item is checked.
   */
  checkedIcon?: any;
  /**
   * The icon displayed when an item is loading.
   */
  loadingIcon?: any;
  /**
   * The icon displayed when the item is an external link.
   * Set to `false` to hide the external icon.
   * @default "true"
   */
  externalIcon?: any;
  /**
   * The content of the menu.
   */
  content?: (Omit<DropdownMenuContentProps, "as" | "asChild" | "forceMount"> & Partial<EmitsToProps<MenuContentEmits>>) | undefined;
  /**
   * Display an arrow alongside the menu.
   * `{ rounded: true }`{lang="ts-type"}
   */
  arrow?: boolean | Omit<DropdownMenuArrowProps, "as" | "asChild"> | undefined;
  /**
   * Render the menu in a portal.
   * @default "true"
   */
  portal?: string | boolean | HTMLElement | undefined;
  /**
   * The key used to get the label from the item.
   * @default "\"label\""
   */
  labelKey?: GetItemKeys<T> | undefined;
  /**
   * The key used to get the description from the item.
   * @default "\"description\""
   */
  descriptionKey?: GetItemKeys<T> | undefined;
  /**
   * Whether to display a filter input or not.
   * Can be an object to pass additional props to the input.
   * `{ placeholder: 'Search...', variant: 'none' }`{lang="ts-type"}
   * @default "false"
   */
  filter?: boolean | Omit<InputProps<AcceptableValue, ModelModifiers>, "modelValue" | "defaultValue"> | undefined;
  /**
   * The fields to filter by.
   */
  filterFields?: string[] | undefined;
  /**
   * When `true`, items will not be filtered which is useful for custom filtering.
   * @default "false"
   */
  ignoreFilter?: boolean | undefined;
  disabled?: boolean | undefined;
  ui?: { content?: SlotClass; input?: SlotClass; empty?: SlotClass; viewport?: SlotClass; arrow?: SlotClass; group?: SlotClass; label?: SlotClass; separator?: SlotClass; item?: SlotClass; itemLeadingIcon?: SlotClass; itemLeadingAvatar?: SlotClass; itemLeadingAvatarSize?: SlotClass; itemTrailing?: SlotClass; itemTrailingIcon?: SlotClass; itemTrailingKbds?: SlotClass; itemTrailingKbdsSize?: SlotClass; itemWrapper?: SlotClass; itemLabel?: SlotClass; itemDescription?: SlotClass; itemLabelExternalIcon?: SlotClass; } | undefined;
  /**
   * The open state of the dropdown menu when it is initially rendered. Use when you do not need to control its open state.
   */
  defaultOpen?: boolean | undefined;
  /**
   * The controlled open state of the menu. Can be used as `v-model:open`.
   */
  open?: boolean | undefined;
  /**
   * The modality of the dropdown menu.
   * 
   * When set to `true`, interaction with outside elements will be disabled and only menu content will be visible to screen readers.
   * @default "true"
   */
  modal?: boolean | undefined;
  /**
   * @default "\"\""
   */
  searchTerm?: string | undefined;
}
```

### Slots

```ts
/**
 * Slots for the DropdownMenu component
 */
interface DropdownMenuSlots {
  default(): any;
  item(): any;
  item-leading(): any;
  item-label(): any;
  item-description(): any;
  item-trailing(): any;
  empty(): any;
  content-top(): any;
  content-bottom(): any;
}
```

### Emits

```ts
/**
 * Emitted events for the DropdownMenu component
 */
interface DropdownMenuEmits {
  update:open: (payload: [payload: boolean]) => void;
  update:searchTerm: (payload: [value: string]) => void;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    dropdownMenu: {
      slots: {
        content: 'min-w-32 bg-default shadow-lg rounded-md ring ring-default overflow-hidden data-[state=open]:animate-[scale-in_100ms_ease-out] data-[state=closed]:animate-[scale-out_100ms_ease-in] origin-(--reka-dropdown-menu-content-transform-origin) flex flex-col',
        input: 'border-b border-default',
        empty: 'text-center text-muted',
        viewport: 'relative divide-y divide-default scroll-py-1 overflow-y-auto flex-1',
        arrow: 'fill-bg stroke-default',
        group: 'p-1 isolate',
        label: 'w-full flex items-center font-semibold text-highlighted',
        separator: '-mx-1 my-1 h-px bg-border',
        item: 'group relative w-full flex items-start select-none outline-none before:absolute before:z-[-1] before:inset-px before:rounded-md data-disabled:cursor-not-allowed data-disabled:opacity-75',
        itemLeadingIcon: 'shrink-0',
        itemLeadingAvatar: 'shrink-0',
        itemLeadingAvatarSize: '',
        itemTrailing: 'ms-auto inline-flex gap-1.5 items-center',
        itemTrailingIcon: 'shrink-0',
        itemTrailingKbds: 'hidden lg:inline-flex items-center shrink-0',
        itemTrailingKbdsSize: '',
        itemWrapper: 'flex-1 flex flex-col text-start min-w-0',
        itemLabel: 'truncate',
        itemDescription: 'truncate text-muted',
        itemLabelExternalIcon: 'inline-block size-3 align-top text-dimmed'
      },
      variants: {
        color: {
          primary: '',
          secondary: '',
          accent: '',
          success: '',
          info: '',
          warning: '',
          error: '',
          neutral: ''
        },
        active: {
          true: {
            item: 'text-highlighted before:bg-elevated',
            itemLeadingIcon: 'text-default'
          },
          false: {
            item: [
              'text-default data-highlighted:text-highlighted data-[state=open]:text-highlighted data-highlighted:before:bg-elevated/50 data-[state=open]:before:bg-elevated/50',
              'transition-colors before:transition-colors'
            ],
            itemLeadingIcon: [
              'text-dimmed group-data-highlighted:text-default group-data-[state=open]:text-default',
              'transition-colors'
            ]
          }
        },
        loading: {
          true: {
            itemLeadingIcon: 'animate-spin'
          }
        },
        size: {
          xs: {
            label: 'p-1 text-xs gap-1',
            item: 'p-1 text-xs gap-1',
            empty: 'p-2 text-xs',
            itemLeadingIcon: 'size-4',
            itemLeadingAvatarSize: '3xs',
            itemTrailingIcon: 'size-4',
            itemTrailingKbds: 'gap-0.5',
            itemTrailingKbdsSize: 'sm'
          },
          sm: {
            label: 'p-1.5 text-xs gap-1.5',
            item: 'p-1.5 text-xs gap-1.5',
            empty: 'p-2.5 text-xs',
            itemLeadingIcon: 'size-4',
            itemLeadingAvatarSize: '3xs',
            itemTrailingIcon: 'size-4',
            itemTrailingKbds: 'gap-0.5',
            itemTrailingKbdsSize: 'sm'
          },
          md: {
            label: 'p-1.5 text-sm gap-1.5',
            item: 'p-1.5 text-sm gap-1.5',
            empty: 'p-2.5 text-sm',
            itemLeadingIcon: 'size-5',
            itemLeadingAvatarSize: '2xs',
            itemTrailingIcon: 'size-5',
            itemTrailingKbds: 'gap-0.5',
            itemTrailingKbdsSize: 'md'
          },
          lg: {
            label: 'p-2 text-sm gap-2',
            item: 'p-2 text-sm gap-2',
            empty: 'p-3 text-sm',
            itemLeadingIcon: 'size-5',
            itemLeadingAvatarSize: '2xs',
            itemTrailingIcon: 'size-5',
            itemTrailingKbds: 'gap-1',
            itemTrailingKbdsSize: 'md'
          },
          xl: {
            label: 'p-2 text-base gap-2',
            item: 'p-2 text-base gap-2',
            empty: 'p-3 text-base',
            itemLeadingIcon: 'size-6',
            itemLeadingAvatarSize: 'xs',
            itemTrailingIcon: 'size-6',
            itemTrailingKbds: 'gap-1',
            itemTrailingKbdsSize: 'lg'
          }
        }
      },
      compoundVariants: [
        {
          color: 'primary',
          active: false,
          class: {
            item: 'text-primary data-highlighted:text-primary data-highlighted:before:bg-primary/10 data-[state=open]:before:bg-primary/10',
            itemLeadingIcon: 'text-primary/75 group-data-highlighted:text-primary group-data-[state=open]:text-primary'
          }
        },
        {
          color: 'secondary',
          active: false,
          class: {
            item: 'text-secondary data-highlighted:text-secondary data-highlighted:before:bg-secondary/10 data-[state=open]:before:bg-secondary/10',
            itemLeadingIcon: 'text-secondary/75 group-data-highlighted:text-secondary group-data-[state=open]:text-secondary'
          }
        },
        {
          color: 'accent',
          active: false,
          class: {
            item: 'text-accent data-highlighted:text-accent data-highlighted:before:bg-accent/10 data-[state=open]:before:bg-accent/10',
            itemLeadingIcon: 'text-accent/75 group-data-highlighted:text-accent group-data-[state=open]:text-accent'
          }
        },
        {
          color: 'success',
          active: false,
          class: {
            item: 'text-success data-highlighted:text-success data-highlighted:before:bg-success/10 data-[state=open]:before:bg-success/10',
            itemLeadingIcon: 'text-success/75 group-data-highlighted:text-success group-data-[state=open]:text-success'
          }
        },
        {
          color: 'info',
          active: false,
          class: {
            item: 'text-info data-highlighted:text-info data-highlighted:before:bg-info/10 data-[state=open]:before:bg-info/10',
            itemLeadingIcon: 'text-info/75 group-data-highlighted:text-info group-data-[state=open]:text-info'
          }
        },
        {
          color: 'warning',
          active: false,
          class: {
            item: 'text-warning data-highlighted:text-warning data-highlighted:before:bg-warning/10 data-[state=open]:before:bg-warning/10',
            itemLeadingIcon: 'text-warning/75 group-data-highlighted:text-warning group-data-[state=open]:text-warning'
          }
        },
        {
          color: 'error',
          active: false,
          class: {
            item: 'text-error data-highlighted:text-error data-highlighted:before:bg-error/10 data-[state=open]:before:bg-error/10',
            itemLeadingIcon: 'text-error/75 group-data-highlighted:text-error group-data-[state=open]:text-error'
          }
        },
        {
          color: 'primary',
          active: true,
          class: {
            item: 'text-primary before:bg-primary/10',
            itemLeadingIcon: 'text-primary'
          }
        },
        {
          color: 'secondary',
          active: true,
          class: {
            item: 'text-secondary before:bg-secondary/10',
            itemLeadingIcon: 'text-secondary'
          }
        },
        {
          color: 'accent',
          active: true,
          class: {
            item: 'text-accent before:bg-accent/10',
            itemLeadingIcon: 'text-accent'
          }
        },
        {
          color: 'success',
          active: true,
          class: {
            item: 'text-success before:bg-success/10',
            itemLeadingIcon: 'text-success'
          }
        },
        {
          color: 'info',
          active: true,
          class: {
            item: 'text-info before:bg-info/10',
            itemLeadingIcon: 'text-info'
          }
        },
        {
          color: 'warning',
          active: true,
          class: {
            item: 'text-warning before:bg-warning/10',
            itemLeadingIcon: 'text-warning'
          }
        },
        {
          color: 'error',
          active: true,
          class: {
            item: 'text-error before:bg-error/10',
            itemLeadingIcon: 'text-error'
          }
        }
      ],
      defaultVariants: {
        size: 'md'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/DropdownMenu.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/dropdown-menu.ts).


# Editor

## Uso

O componente Editor oferece uma poderosa experiência de edição de texto rico construída sobre o [TipTap](https://tiptap.dev/){rel="&#x22;nofollow&#x22;"}. Ele suporta múltiplos formatos de conteúdo (JSON, HTML, Markdown), barras de ferramentas personalizáveis, reordenação de blocos por arrastar e soltar, comandos de barra, menções, seletor de emoji e uma arquitetura extensível para adicionar funcionalidades personalizadas.

::component-example
---
elevated: true
source: false
class: relative h-176 overflow-y-auto !p-0 rounded-b-md
name: editor-example
---
::

> \[!NOTE]
> See: https\://gitlab.nitro.news/nitro/ui/-/blob/main/docs/app/components/content/examples/editor/EditorExample.vue
>
> Este exemplo demonstra um componente Editor pronto para produção. Confira o código-fonte no GitHub.

> \[!WARNING]
>
> Se você encontrar erros relacionados ao prosemirror, como `Adding different instances of a keyed plugin`, ao usar o componente Editor ou suas extensões, talvez seja necessário adicionar os pacotes do prosemirror à lista `vite.optimizeDeps.include` no seu arquivo `nuxt.config.ts`. Isso garante que o Vite pré-empacote essas dependências para evitar o carregamento de múltiplas instâncias.
>
> ```ts [nuxt.config.ts]
> export default defineNuxtConfig({
>   vite: {
>     optimizeDeps: {
>       include: [
>         '@nitro/ui > prosemirror-state',
>         '@nitro/ui > prosemirror-transform',
>         '@nitro/ui > prosemirror-model',
>         '@nitro/ui > prosemirror-view',
>         '@nitro/ui > prosemirror-gapcursor'
>       ]
>     }
>   }
> })
> ```

### Conteúdo

Use a diretiva `v-model` para controlar o valor do Editor.

```vue
<script setup lang="ts">
const value = ref({
  type: "doc",
  content: [
    {
      type: "heading",
      attrs: {
        level: 1
      },
      content: [
        {
          type: "text",
          text: "Hello World"
        }
      ]
    },
    {
      type: "paragraph",
      content: [
        {
          type: "text",
          text: "This is a "
        },
        {
          type: "text",
          marks: [
            {
              type: "bold"
            }
          ],
          text: "rich text"
        },
        {
          type: "text",
          text: " editor."
        }
      ]
    }
  ]
})
</script>

<template>
  <UEditor v-model="value" class="w-full min-h-21" />
</template>
```

### Tipo de conteúdo

O Editor detecta automaticamente o formato do conteúdo com base no tipo do `v-model`: strings são tratadas como `html`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} e objetos como `json`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}.

Você pode definir explicitamente o formato usando a prop `content-type`: `json`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, `html`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} ou `markdown`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}.

```vue
<script setup lang="ts">
const value = ref("<h1>Hello World</h1>\n<p>This is a <strong>rich text</strong> editor.</p>\n")
</script>

<template>
  <UEditor v-model="value" content-type="html" class="w-full min-h-21" />
</template>
```

### Extensões

O Editor inclui as seguintes extensões por padrão:

- [**StarterKit**](https://ui.nitro.news/#starter-kit) - Core editing features (bold, italic, headings, lists, etc.)
- [**Placeholder**](https://ui.nitro.news/#placeholder) - Show placeholder text (when placeholder prop is provided)
- **Image** - Insert and display images
- **Mention** - Add @ mentions support
- **Markdown** - Parse and serialize markdown (when content type is markdown)

> \[!NOTE]
>
> Cada extensão embutida pode ser configurada usando sua prop correspondente (`starter-kit`, `placeholder`, `image`, `mention`, `markdown`) para personalizar seu comportamento com as opções do TipTap.

Você pode usar a prop `extensions` para adicionar extensões adicionais do TipTap e ampliar os recursos do Editor:

```vue
<script setup lang="ts">
import { Emoji } from '@tiptap/extension-emoji'
import { TextAlign } from '@tiptap/extension-text-align'

const value = ref('<h1>Hello World</h1>\n')
</script>

<template>
  <NEditor
    v-model="value"
    :extensions="[
      Emoji,
      TextAlign.configure({
        types: ['heading', 'paragraph']
      })
    ]"
  />
</template>
```

> \[!TIP]
> See: #with-image-upload
>
> Confira o exemplo de upload de imagem para criar extensões personalizadas do TipTap.

### Placeholder

Use a prop `placeholder` para definir um texto de placeholder que aparece em parágrafos vazios.

```vue
<script setup lang="ts">
const value = ref("")
</script>

<template>
  <UEditor placeholder="Start writing..." class="w-full min-h-7" />
</template>
```

> \[!NOTE]
>
> A prop `placeholder` aceita uma string ou um objeto com [PlaceholderOptions](https://tiptap.dev/docs/editor/extensions/functionality/placeholder){rel="&#x22;nofollow&#x22;"} e uma propriedade adicional `mode`:
>
> - `everyLine`: Display placeholder on every empty line when focused (default).
> - `firstLine`: Display placeholder only on the first line when the editor is empty.
>
> ```vue
> <template>
>   <NEditor :placeholder="{ placeholder: 'Start writing...', mode: 'firstLine' }" />
> </template>
> ```

> \[!TIP]
>
> Por padrão, os placeholders só aparecem em nodes vazios de nível superior. Para exibir placeholders em elementos aninhados, como itens de lista, defina `includeChildren` como `true`:
>
> ```vue
> <template>
>   <NEditor :placeholder="{ placeholder: 'Start writing...', includeChildren: true }" />
> </template>
> ```

> \[!NOTE]
> See: https\://tiptap.dev/docs/editor/extensions/functionality/placeholder
>
> Saiba mais sobre a extensão Placeholder na documentação do TipTap.

### Kit inicial

Use a prop `starter-kit` para configurar a extensão StarterKit embutida do TipTap, que inclui recursos comuns do editor como negrito, itálico, títulos, listas, citações, blocos de código e mais.

```vue
<script setup lang="ts">
const value = ref('<h1>Hello World</h1>\n')
</script>

<template>
  <NEditor
    v-model="value"
    :starter-kit="{
      blockquote: false,
      headings: {
        levels: [1, 2, 3, 4]
      },
      dropcursor: {
        color: 'var(--ui-primary)',
        width: 2
      },
      link: {
        openOnClick: false
      }
    }"
  />
</template>
```

> \[!TIP]
>
> Defina `starter-kit` como `false` para um editor de texto simples. Ele mantém os nodes essenciais (parágrafo, texto, histórico) e desabilita todos os recursos de formatação, como negrito, itálico, títulos, listas, código, citação, links e réguas horizontais.

> \[!NOTE]
> See: https\://tiptap.dev/docs/editor/extensions/functionality/starterkit
>
> Saiba mais sobre a extensão StarterKit na documentação do TipTap.

### Manipuladores

Os handlers envolvem os comandos embutidos do TipTap para oferecer uma interface unificada para as ações do editor. Quando você adiciona uma propriedade `kind` a um item de [EditorToolbar](https://ui.nitro.news/docs/components/editor-toolbar) ou [EditorSuggestionMenu](https://ui.nitro.news/docs/components/editor-suggestion-menu), o handler correspondente executa o comando do TipTap e gerencia seu estado (ativo, desabilitado, etc.).

#### Manipuladores padrão

O componente Editor fornece estes handlers padrão, que você pode referenciar em itens da barra de ferramentas ou do menu de sugestões usando a propriedade `kind`:

| Handler                                                                                                                               | Description                                               | Usage                             |
| ------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | --------------------------------- |
| `mark`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"}            | Toggle text marks (bold, italic, strike, code, underline) | Requires `mark` property in item  |
| `textAlign`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"}       | Set text alignment (left, center, right, justify)         | Requires `align` property in item |
| `heading`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"}         | Toggle heading levels (1-6)                               | Requires `level` property in item |
| `link`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"}            | Add, edit, or remove links                                | Prompts for URL if not provided   |
| `image`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"}           | Insert images                                             | Prompts for URL if not provided   |
| `blockquote`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"}      | Toggle blockquotes                                        |                                   |
| `bulletList`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"}      | Toggle bullet lists                                       | Handles list conversions          |
| `orderedList`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"}     | Toggle ordered lists                                      | Handles list conversions          |
| `taskList`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"}        | Toggle task lists                                         | Handles list conversions          |
| `codeBlock`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"}       | Toggle code blocks                                        |                                   |
| `horizontalRule`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"}  | Insert horizontal rules                                   |                                   |
| `paragraph`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"}       | Set paragraph format                                      |                                   |
| `undo`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"}            | Undo last change                                          |                                   |
| `redo`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"}            | Redo last undone change                                   |                                   |
| `clearFormatting`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | Remove all formatting                                     | Works with selection or position  |
| `duplicate`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"}       | Duplicate a node                                          | Requires `pos` property in item   |
| `delete`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"}          | Delete a node                                             | Requires `pos` property in item   |
| `moveUp`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"}          | Move a node up                                            | Requires `pos` property in item   |
| `moveDown`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"}        | Move a node down                                          | Requires `pos` property in item   |
| `suggestion`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"}      | Trigger suggestion menu                                   | Inserts `/` character             |
| `mention`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"}         | Trigger mention menu                                      | Inserts `@` character             |
| `emoji`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"}           | Trigger emoji picker                                      | Inserts `:` character             |

> \[!WARNING]
>
> Os handlers `taskList` e `textAlign` só funcionam quando suas respectivas extensões estão instaladas, já que não são incluídos no Editor por padrão.

Veja como usar os handlers padrão em itens da barra de ferramentas ou do menu de sugestões:

```vue
<script setup lang="ts">
import type { EditorToolbarItem } from '@nitro/ui'

const value = ref('<h1>Hello World</h1>\n')

const items: EditorToolbarItem[] = [
  { kind: 'mark', mark: 'bold', icon: 'i-lucide-bold' },
  { kind: 'mark', mark: 'italic', icon: 'i-lucide-italic' },
  { kind: 'heading', level: 1, icon: 'i-lucide-heading-1' },
  { kind: 'heading', level: 2, icon: 'i-lucide-heading-2' },
  { kind: 'textAlign', align: 'left', icon: 'i-lucide-align-left' },
  { kind: 'textAlign', align: 'center', icon: 'i-lucide-align-center' },
  { kind: 'bulletList', icon: 'i-lucide-list' },
  { kind: 'orderedList', icon: 'i-lucide-list-ordered' },
  { kind: 'blockquote', icon: 'i-lucide-quote' },
  { kind: 'link', icon: 'i-lucide-link' }
]
</script>

<template>
  <NEditor v-slot="{ editor }" v-model="value">
    <NEditorToolbar :editor="editor" :items="items" />
  </NEditor>
</template>
```

#### Manipuladores personalizados

Use a prop `handlers` para estender ou sobrescrever os handlers padrão. Os handlers personalizados são mesclados com os padrão, permitindo adicionar novas ações ou modificar o comportamento existente.

Cada handler implementa a interface `EditorHandler`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}:

```ts
interface EditorHandler {
  /* Checks if the command can be executed in the current editor state */
  canExecute: (editor: Editor, item?: any) => boolean
  /* Executes the command and returns a Tiptap chain */
  execute: (editor: Editor, item?: any) => any
  /* Determines if the item should appear active (used for toggle states) */
  isActive: (editor: Editor, item?: any) => boolean
  /* Optional additional check to disable the item (combined with `canExecute`) */
  isDisabled?: (editor: Editor, item?: any) => boolean
}
```

Aqui está um exemplo de criação de handlers personalizados:

```vue
<script setup lang="ts">
import type { Editor } from '@tiptap/vue-3'
import type { EditorCustomHandlers, EditorToolbarItem } from '@nitro/ui'

const value = ref('<h1>Hello World</h1>\n')

const customHandlers = {
  highlight: {
    canExecute: (editor: Editor) => editor.can().toggleHighlight(),
    execute: (editor: Editor) => editor.chain().focus().toggleHighlight(),
    isActive: (editor: Editor) => editor.isActive('highlight'),
    isDisabled: (editor: Editor) => !editor.isEditable
  }
} satisfies EditorCustomHandlers

const items = [
  // Built-in handler
  { kind: 'mark', mark: 'bold', icon: 'i-lucide-bold' },
  // Custom handler
  { kind: 'highlight', icon: 'i-lucide-highlighter' }
] satisfies EditorToolbarItem<typeof customHandlers>[]
</script>

<template>
  <NEditor v-slot="{ editor }" v-model="value" :handlers="customHandlers">
    <NEditorToolbar :editor="editor" :items="items" />
  </NEditor>
</template>
```

> \[!TIP]
> See: #with-image-upload
>
> Confira o exemplo de upload de imagem para uma implementação completa com handlers personalizados.

### Com barra de ferramentas

Você pode usar o componente [EditorToolbar](https://ui.nitro.news/docs/components/editor-toolbar) para adicionar uma barra de ferramentas `fixed`, `bubble` ou `floating` ao Editor com ações de formatação comuns.

::component-example
---
collapse: true
elevated: true
prettier: true
class: p-8
name: editor-toolbar-example
---
::

### Com alça de arrastar

Você pode usar o componente [EditorDragHandle](https://ui.nitro.news/docs/components/editor-drag-handle) para adicionar uma alça arrastável para reordenar blocos.

::component-example
---
collapse: true
elevated: true
prettier: true
class: p-8
name: editor-drag-handle-example
---
::

### Com menu de sugestões

Você pode usar o componente [EditorSuggestionMenu](https://ui.nitro.news/docs/components/editor-suggestion-menu) para adicionar comandos de barra para formatação e inserções rápidas.

::component-example
---
collapse: true
elevated: true
prettier: true
class: p-8
name: editor-suggestion-menu-example
---
::

### Com menu de menções

Você pode usar o componente [EditorMentionMenu](https://ui.nitro.news/docs/components/editor-mention-menu) para adicionar menções com @ para marcar usuários ou entidades.

::component-example
---
collapse: true
elevated: true
prettier: true
class: p-8
name: editor-mention-menu-example
---
::

### Com menu de emojis

Você pode usar o componente [EditorEmojiMenu](https://ui.nitro.news/docs/components/editor-emoji-menu) para adicionar suporte ao seletor de emojis.

::component-example
---
collapse: true
elevated: true
prettier: true
class: p-8
name: editor-emoji-menu-example
---
::

### Com upload de imagem

Este exemplo demonstra como criar um recurso de upload de imagem usando a prop `extensions` para registrar um node personalizado do TipTap e a prop `handlers` para definir como o botão da barra de ferramentas dispara o fluxo de upload.

1. Crie um componente Vue que usa o componente [FileUpload](https://ui.nitro.news/docs/components/file-upload):

::component-example{collapse :preview='false' name="editor-image-upload-node"}
::

2. Crie uma extensão personalizada do TipTap para registrar o node:

::component-example
---
collapse: true
preview: false
lang: ts
name: editor-image-upload-extension
---
::

3. Use a extensão personalizada no Editor:

::component-example
---
collapse: true
elevated: true
prettier: true
class: "!p-0"
name: editor-image-upload-example
---
::

> \[!NOTE]
> See: https\://tiptap.dev/docs/editor/extensions/custom-extensions
>
> Saiba mais sobre a criação de extensões personalizadas na documentação do TipTap.

### Com completar por IA

Este exemplo demonstra como adicionar recursos com IA ao Editor usando o [Vercel AI SDK](https://ai-sdk.dev/){rel="&#x22;nofollow&#x22;"}, especificamente o composable [`useCompletion`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-completion){rel="&#x22;nofollow&#x22;"} para completar texto em streaming, combinado com o [Vercel AI Gateway](https://vercel.com/ai-gateway){rel="&#x22;nofollow&#x22;"} para acessar modelos de IA por meio de um endpoint centralizado. Ele inclui autocompletar com texto fantasma e ações de transformação de texto (corrigir gramática, estender, reduzir, simplificar, traduzir, etc.).

> \[!NOTE]
>
> Você precisa instalar estas dependências primeiro para usar este exemplo:
>
> ```bash [pnpm]
> pnpm add ai @ai-sdk/gateway @ai-sdk/vue
> ```
>
> ```bash [yarn]
> yarn add ai @ai-sdk/gateway @ai-sdk/vue
> ```
>
> ```bash [npm]
> npm install ai @ai-sdk/gateway @ai-sdk/vue
> ```
>
> ```bash [bun]
> bun add ai @ai-sdk/gateway @ai-sdk/vue
> ```

1. Crie uma extensão personalizada do TipTap que trata as sugestões de texto fantasma inline:

::component-example
---
collapse: true
preview: false
lang: ts
name: editor-completion-extension
---
::

2. Crie um composable que gerencia o estado e os handlers da conclusão por IA:

::component-example
---
collapse: true
preview: false
filename: useEditorCompletion
lang: ts
name: editor-use-completion
---
::

3. Crie um endpoint de API no servidor para tratar as requisições de conclusão usando [`streamText`](https://ai-sdk.dev/docs/reference/ai-sdk-core/stream-text#streamtext){rel="&#x22;nofollow&#x22;"}:

```ts [server/api/completion.post.ts]
import { streamText, createTextStreamResponse } from 'ai'
import { gateway } from '@ai-sdk/gateway'

export default defineEventHandler(async (event) => {
  const { prompt, mode, language } = await readBody(event)
  if (!prompt) {
    throw createError({ statusCode: 400, message: 'Prompt is required' })
  }

  let instructions: string
  let maxOutputTokens: number

  const preserveMarkdown = 'IMPORTANT: Preserve all markdown formatting (bold, italic, links, etc.) exactly as in the original.'

  switch (mode) {
    case 'fix':
      instructions = `You are a writing assistant. Fix all spelling and grammar errors in the given text. ${preserveMarkdown} Only output the corrected text, nothing else.`
      maxOutputTokens = 500
      break
    case 'extend':
      instructions = `You are a writing assistant. Extend the given text with more details, examples, and explanations while maintaining the same style. ${preserveMarkdown} Only output the extended text, nothing else.`
      maxOutputTokens = 500
      break
    case 'reduce':
      instructions = `You are a writing assistant. Make the given text more concise by removing unnecessary words while keeping the meaning. ${preserveMarkdown} Only output the reduced text, nothing else.`
      maxOutputTokens = 300
      break
    case 'simplify':
      instructions = `You are a writing assistant. Simplify the given text to make it easier to understand, using simpler words and shorter sentences. ${preserveMarkdown} Only output the simplified text, nothing else.`
      maxOutputTokens = 400
      break
    case 'summarize':
      instructions = 'You are a writing assistant. Summarize the given text concisely while keeping the key points. Only output the summary, nothing else.'
      maxOutputTokens = 200
      break
    case 'translate':
      instructions = `You are a writing assistant. Translate the given text to ${language || 'English'}. ${preserveMarkdown} Only output the translated text, nothing else.`
      maxOutputTokens = 500
      break
    case 'continue':
    default:
      instructions = `You are a writing assistant providing inline autocompletions.
CRITICAL RULES:
- Output ONLY the NEW text that comes AFTER the user's input
- NEVER repeat any words from the end of the user's text
- Keep completions short (1 sentence max)
- Match the tone and style of the existing text
- ${preserveMarkdown}`
      maxOutputTokens = 25
      break
  }

  const result = streamText({
    model: gateway('anthropic/claude-haiku-4.5'),
    instructions,
    prompt,
    maxOutputTokens
  })

  return createTextStreamResponse({ stream: result.textStream })
})
```

4. Use o composable no Editor:

::component-example
---
collapse: true
elevated: true
prettier: true
class: "!p-0"
name: editor-completion-example
---
::

> \[!NOTE]
>
> A extensão de conclusão pode ser configurada com `autoTrigger: true` para sugerir conclusões automaticamente enquanto você digita (desabilitado por padrão). Você também pode dispará-la manualmente com :kbd{value="meta"} :kbd{.ms-px value="j"}.

> \[!NOTE]
> See: https\://ai-sdk.dev/
>
> Saiba mais sobre o Vercel AI SDK e os provedores disponíveis.

## API

### Props

```ts
/**
 * Props for the Editor component
 */
interface EditorProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  modelValue?: null | string | JSONContent | JSONContent[];
  /**
   * The content type the content is provided as.
   * When not specified, it's automatically inferred: strings are treated as 'html', objects as 'json'.
   */
  contentType?: EditorContentType | undefined;
  /**
   * The starter kit options to configure the editor.
   * Set to `false` for a plain-text editor: keeps the essential nodes (paragraph, text, history) and disables all rich-text formatting.
   * @default "true"
   */
  starterKit?: boolean | Partial<StarterKitOptions> | undefined;
  /**
   * The placeholder text to show in empty paragraphs. Can be a string or PlaceholderOptions from `@tiptap/extension-placeholder`.
   */
  placeholder?: string | (Partial<PlaceholderOptions> & { mode?: "firstLine" | "everyLine" | undefined; }) | undefined;
  /**
   * The markdown extension options to configure markdown parsing and serialization.
   */
  markdown?: Partial<MarkdownExtensionOptions> | undefined;
  /**
   * The image extension options to configure image handling. Set to `false` to disable the extension.
   * @default "true"
   */
  image?: boolean | Partial<ImageOptions> | undefined;
  /**
   * The mention extension options to configure mention handling. Set to `false` to disable the extension.
   * The `suggestion` and `suggestions` options are omitted as they are managed by the `EditorMentionMenu` component.
   * @default "true"
   */
  mention?: boolean | Partial<Omit<MentionOptions<any, MentionNodeAttrs>, "suggestion" | "suggestions">> | undefined;
  /**
   * Custom item handlers to override or extend the default handlers.
   * These handlers are provided to all child components (toolbar, suggestion menu, etc.).
   */
  handlers?: H | undefined;
  ui?: { root?: SlotClass; content?: SlotClass; base?: SlotClass; } | undefined;
  /**
   * The extensions to use
   */
  extensions?: Extensions | undefined;
  /**
   * Whether to inject base CSS styles
   */
  injectCSS?: boolean | undefined;
  /**
   * A nonce to use for CSP while injecting styles
   */
  injectNonce?: string | undefined;
  /**
   * The editor's initial focus position
   */
  autofocus?: FocusPosition | undefined;
  /**
   * Whether the editor is editable
   */
  editable?: boolean | undefined;
  /**
   * The default text direction for all content in the editor.
   * When set to 'ltr' or 'rtl', all nodes will have the corresponding dir attribute.
   * When set to 'auto', the dir attribute will be set based on content detection.
   * When undefined, no dir attribute will be added.
   */
  textDirection?: "ltr" | "rtl" | "auto" | undefined;
  /**
   * The editor's props
   */
  editorProps?: EditorProps<any> | undefined;
  parseOptions?: ParseOptions;
  /**
   * The editor's core extension options
   */
  coreExtensionOptions?: { clipboardTextSerializer?: { blockSeparator?: string | undefined; } | undefined; tabindex?: { value?: string | undefined; } | undefined; delete?: { async?: boolean | undefined; filterTransaction?: ((transaction: Transaction) => boolean) | undefined; } | undefined; } | undefined;
  /**
   * Whether to enable input rules behavior
   */
  enableInputRules?: EnableRules | undefined;
  /**
   * Whether to enable paste rules behavior
   */
  enablePasteRules?: EnableRules | undefined;
  /**
   * Determines whether core extensions are enabled.
   * 
   * If set to `false`, all core extensions will be disabled.
   * To disable specific core extensions, provide an object where the keys are the extension names and the values are `false`.
   * Extensions not listed in the object will remain enabled.
   */
  enableCoreExtensions?: boolean | Partial<Record<"editable" | "textDirection" | "clipboardTextSerializer" | "commands" | "focusEvents" | "keymap" | "tabindex" | "drop" | "paste" | "delete", false>> | undefined;
  /**
   * If `true`, the editor will check the content for errors on initialization.
   * Emitting the `contentError` event if the content is invalid.
   * Which can be used to show a warning or error message to the user.
   */
  enableContentCheck?: boolean | undefined;
  /**
   * If `true`, the editor will emit the `contentError` event if invalid content is
   * encountered but `enableContentCheck` is `false`. This lets you preserve the
   * invalid editor content while still showing a warning or error message to
   * the user.
   */
  emitContentError?: boolean | undefined;
  /**
   * Called before the editor is constructed.
   */
  onBeforeCreate?: ((props: { editor: Editor; }) => void) | undefined;
  /**
   * Called after the editor is constructed.
   */
  onCreate?: ((props: { editor: Editor; }) => void) | undefined;
  /**
   * Called when the editor is mounted.
   */
  onMount?: ((props: { editor: Editor; }) => void) | undefined;
  /**
   * Called when the editor is unmounted.
   */
  onUnmount?: ((props: { editor: Editor; }) => void) | undefined;
  /**
   * Called when the editor encounters an error while parsing the content.
   * Only enabled if `enableContentCheck` is `true`.
   */
  onContentError?: ((props: { editor: Editor; error: Error; disableCollaboration: () => void; }) => void) | undefined;
  /**
   * Called when the editor's content is updated.
   */
  onUpdate?: ((props: { editor: Editor; transaction: Transaction; appendedTransactions: Transaction[]; }) => void) | undefined;
  /**
   * Called when the editor's selection is updated.
   */
  onSelectionUpdate?: ((props: { editor: Editor; transaction: Transaction; }) => void) | undefined;
  /**
   * Called after a transaction is applied to the editor.
   */
  onTransaction?: ((props: { editor: Editor; transaction: Transaction; appendedTransactions: Transaction[]; }) => void) | undefined;
  /**
   * Called on focus events.
   */
  onFocus?: ((props: { editor: Editor; event: FocusEvent; transaction: Transaction; }) => void) | undefined;
  /**
   * Called on blur events.
   */
  onBlur?: ((props: { editor: Editor; event: FocusEvent; transaction: Transaction; }) => void) | undefined;
  /**
   * Called when the editor is destroyed.
   */
  onDestroy?: ((props: void) => void) | undefined;
  /**
   * Called when content is pasted into the editor.
   */
  onPaste?: ((e: ClipboardEvent, slice: Slice) => void) | undefined;
  /**
   * Called when content is dropped into the editor.
   */
  onDrop?: ((e: DragEvent, slice: Slice, moved: boolean) => void) | undefined;
  /**
   * Called when content is deleted from the editor.
   */
  onDelete?: ((props: { editor: Editor; deletedRange: Range; newRange: Range; transaction: Transaction; combinedTransform: Transform; partial: boolean; from: number; to: number; } & ({ type: "node"; node: Node; newFrom: number; newTo: number; } | { type: "mark"; mark: Mark; })) => void) | undefined;
  /**
   * Whether to enable extension-level dispatching of transactions.
   * If `false`, extensions cannot define their own `dispatchTransaction` hook.
   */
  enableExtensionDispatchTransaction?: boolean | undefined;
}
```

### Slots

```ts
/**
 * Slots for the Editor component
 */
interface EditorSlots {
  default(): any;
}
```

### Emits

```ts
/**
 * Emitted events for the Editor component
 */
interface EditorEmits {
  update:modelValue: (payload: [value: T]) => void;
}
```

### Expose

Ao acessar o componente por meio de um template ref, você pode usar o seguinte:

| Name                                                                                                                         | Type                                                                                                                                          |
| ---------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `editor`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | `Ref<Editor | undefined>`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} |

> \[!NOTE]
> See: https\://tiptap.dev/docs/editor/api/editor
>
> A instância do editor exposta é a API do Editor do TipTap. Consulte a documentação do TipTap para todos os métodos e propriedades disponíveis.

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    editor: {
      slots: {
        root: '',
        content: 'relative size-full flex-1',
        base: [
          'w-full outline-none *:my-5 *:first:mt-0 *:last:mb-0 sm:px-8 selection:bg-primary/20',
          '[&_:is(p,h1,h2,h3,h4).is-empty]:before:content-[attr(data-placeholder)] [&_:is(p,h1,h2,h3,h4).is-empty]:before:text-dimmed [&_:is(p,h1,h2,h3,h4).is-empty]:before:float-left [&_:is(p,h1,h2,h3,h4).is-empty]:before:h-0 [&_:is(p,h1,h2,h3,h4).is-empty]:before:pointer-events-none',
          '[&_li_.is-empty]:before:content-none',
          '[&_p]:leading-7',
          '[&_a]:text-primary [&_a]:border-b [&_a]:border-transparent [&_a]:hover:border-primary [&_a]:font-medium',
          '[&_a]:transition-colors',
          '[&_.mention]:text-primary [&_.mention]:font-medium',
          '[&_:is(h1,h2,h3,h4)]:text-highlighted [&_:is(h1,h2,h3,h4)]:font-bold',
          '[&_h1]:text-3xl',
          '[&_h2]:text-2xl',
          '[&_h3]:text-xl',
          '[&_h4]:text-lg',
          '[&_:is(h1,h2,h3,h4)>code]:border-dashed [&_:is(h1,h2,h3,h4)>code]:font-bold',
          '[&_h2>code]:text-xl/6',
          '[&_h3>code]:text-lg/5',
          '[&_blockquote]:border-s-4 [&_blockquote]:border-accented [&_blockquote]:ps-4 [&_blockquote]:italic',
          '[&_[data-type=horizontalRule]]:my-8 [&_[data-type=horizontalRule]]:py-2',
          '[&_hr]:border-t [&_hr]:border-default',
          '[&_pre]:text-sm/6 [&_pre]:border [&_pre]:border-muted [&_pre]:bg-muted [&_pre]:rounded-md [&_pre]:px-4 [&_pre]:py-3 [&_pre]:whitespace-pre-wrap [&_pre]:break-words [&_pre]:overflow-x-auto',
          '[&_pre_code]:p-0 [&_pre_code]:text-inherit [&_pre_code]:font-inherit [&_pre_code]:rounded-none [&_pre_code]:inline [&_pre_code]:border-0 [&_pre_code]:bg-transparent',
          '[&_code]:px-1.5 [&_code]:py-0.5 [&_code]:text-sm [&_code]:font-mono [&_code]:font-medium [&_code]:rounded-md [&_code]:inline-block [&_code]:border [&_code]:border-muted [&_code]:text-highlighted [&_code]:bg-muted',
          '[&_:is(ul,ol)]:ps-6',
          '[&_ul]:list-disc [&_ul]:marker:text-(--ui-border-accented)',
          '[&_ol]:list-decimal [&_ol]:marker:text-muted',
          '[&_li]:my-1.5 [&_li]:ps-1.5',
          '[&_img]:rounded-md [&_img]:block [&_img]:max-w-full [&_img.ProseMirror-selectednode]:outline-2 [&_img.ProseMirror-selectednode]:outline-primary',
          '[&_.ProseMirror-selectednode:not(img):not(pre):not([data-node-view-wrapper])]:bg-primary/20'
        ]
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/Editor.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/editor.ts).


# EditorDragHandle

## Uso

O componente EditorDragHandle oferece funcionalidade de arrastar e soltar para reordenar blocos do editor usando o pacote `@tiptap/extension-drag-handle-vue-3`.

> \[!CAUTION]
>
> Ele deve ser usado dentro do slot padrão de um componente [Editor](https://ui.nitro.news/docs/components/editor) para ter acesso à instância do editor.

Ele estende o componente [Button](https://ui.nitro.news/docs/components/button), então você pode passar qualquer propriedade como `color`, `variant`, `size`, etc.

::component-example
---
collapse: true
elevated: true
class: p-8
name: editor-drag-handle-example
---
::

> \[!NOTE]
> See: https\://tiptap.dev/docs/editor/extensions/functionality/drag-handle-vue
>
> Saiba mais sobre a extensão Drag Handle na documentação do TipTap.

### Ícone

Use a prop `icon` para personalizar o ícone da alça de arrastar.

```vue
<template>
  <NEditor v-slot="{ editor }">
    <NEditorDragHandle :editor="editor" icon="i-lucide-move" />
  </NEditor>
</template>
```

**Nuxt:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/nuxt#theme
>
> Você pode personalizar esse ícone globalmente no seu `app.config.ts` na chave `ui.icons.drag`.

**Vue:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/vue#theme
>
> Você pode personalizar esse ícone globalmente no seu `vite.config.ts` na chave `ui.icons.drag`.

### Opções

Use a prop `options` para personalizar o comportamento de posicionamento usando as [opções do Floating UI](https://floating-ui.com/docs/computeposition#options){rel="&#x22;nofollow&#x22;"}.

> \[!NOTE]
>
> O deslocamento é calculado automaticamente para centralizar a alça em blocos pequenos e alinhá-la ao topo em blocos mais altos.

```vue
<template>
  <NEditor v-slot="{ editor }">
    <NEditorDragHandle
      :editor="editor"
      :options="{
        placement: 'left'
      }"
    />
  </NEditor>
</template>
```

## Exemplos

### Com dropdown menu

Use o slot padrão para adicionar um [DropdownMenu](https://ui.nitro.news/docs/components/dropdown-menu) com ações no nível do bloco, como duplicar, excluir, mover para cima/baixo ou transformar blocos em tipos diferentes.

Escute o evento `@node-change` para acompanhar o node atualmente sob o cursor e sua posição, e então use `editor.chain().setMeta('lockDragHandle', open).run()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} para travar a posição da alça enquanto o menu está aberto.

::component-example
---
collapse: true
elevated: true
class: p-8
name: editor-drag-handle-dropdown-menu-example
---
::

> \[!NOTE]
>
> Este exemplo usa o utilitário `mapEditorItems` de `@nitro/ui/utils/editor` para mapear automaticamente os tipos de handler (como `duplicate`, `delete`, `moveUp`, etc.) para os comandos correspondentes do editor, com o devido gerenciamento de estado.

### Com menu de sugestões

Use o slot padrão para adicionar um [Button](https://ui.nitro.news/docs/components/button) ao lado da alça de arrastar para abrir o [EditorSuggestionMenu](https://ui.nitro.news/docs/components/editor-suggestion-menu).

Chame a função de slot `onClick` para obter a posição atual do node e então use `handlers.suggestion?.execute(editor, { pos: node?.pos }).run()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} para inserir novos blocos naquela posição.

::component-example
---
collapse: true
elevated: true
class: "!p-0"
name: editor-drag-handle-suggestion-menu-example
---
::

## API

### Props

```ts
/**
 * Props for the EditorDragHandle component
 */
interface EditorDragHandleProps {
  editor?: Editor;
  icon?: any;
  /**
   * @default "\"neutral\""
   */
  color?: "error" | "neutral" | "primary" | "secondary" | "accent" | "success" | "info" | "warning" | undefined;
  /**
   * @default "\"ghost\""
   */
  variant?: "ghost" | "solid" | "outline" | "soft" | "subtle" | "link" | undefined;
  /**
   * The options for positioning the drag handle. Those are passed to Floating UI and include options for the placement, offset, flip, shift, size, autoPlacement, hide, and inline middleware.
   */
  options?: FloatingUIOptions | undefined;
  ui?: ({ root?: SlotClass; handle?: SlotClass; } & { base?: SlotClass; label?: SlotClass; leadingIcon?: SlotClass; leadingAvatar?: SlotClass; leadingAvatarSize?: SlotClass; trailingIcon?: SlotClass; }) | undefined;
  pluginKey?: string | PluginKey<any> | undefined;
  nestedOptions?: NormalizedNestedOptions | undefined;
  onElementDragStart?: ((e: DragEvent) => void) | undefined;
  onElementDragEnd?: ((e: DragEvent) => void) | undefined;
  getReferencedVirtualElement?: (() => VirtualElement | null) | undefined;
  dragImageProperties?: string[] | undefined;
  /**
   * Enable drag handles for nested content (list items, blockquotes, etc.).
   * 
   * When enabled, the drag handle will appear for nested blocks, not just
   * top-level blocks. A rule-based scoring system determines which node
   * to target based on cursor position and configured rules.
   */
  nested?: boolean | NestedOptions | undefined;
  /**
   * Class to apply when the link is exact active
   */
  exactActiveClass?: string | undefined;
  /**
   * Pass the returned promise of `router.push()` to `document.startViewTransition()` if supported.
   */
  viewTransition?: boolean | undefined;
  autofocus?: Booleanish | undefined;
  disabled?: boolean | undefined;
  form?: string | undefined;
  formaction?: string | undefined;
  formenctype?: string | undefined;
  formmethod?: string | undefined;
  formnovalidate?: Booleanish | undefined;
  formtarget?: string | undefined;
  name?: string | undefined;
  /**
   * The type of the button when not a link.
   */
  type?: "reset" | "submit" | "button" | undefined;
  onClick?: ((event: MouseEvent) => void) | ((event: MouseEvent) => void)[] | undefined;
  /**
   * The element or component this component should render as when not a link.
   */
  as?: any;
  label?: string | undefined;
  activeColor?: "error" | "neutral" | "primary" | "secondary" | "accent" | "success" | "info" | "warning" | undefined;
  activeVariant?: "ghost" | "solid" | "outline" | "soft" | "subtle" | "link" | undefined;
  /**
   * @default "\"sm\""
   */
  size?: "sm" | "xs" | "md" | "lg" | "xl" | undefined;
  /**
   * Render the button with equal padding on all sides.
   */
  square?: boolean | undefined;
  /**
   * Render the button full width.
   */
  block?: boolean | undefined;
  /**
   * Set loading state automatically based on the `@click` promise state
   */
  loadingAuto?: boolean | undefined;
  /**
   * Display an avatar on the left side.
   */
  avatar?: AvatarProps | undefined;
  /**
   * When `true`, the icon will be displayed on the left side.
   */
  leading?: boolean | undefined;
  /**
   * Display an icon on the left side.
   */
  leadingIcon?: any;
  /**
   * When `true`, the icon will be displayed on the right side.
   */
  trailing?: boolean | undefined;
  /**
   * Display an icon on the right side.
   */
  trailingIcon?: any;
  /**
   * When `true`, the loading icon will be displayed.
   */
  loading?: boolean | undefined;
  /**
   * The icon when the `loading` prop is `true`.
   */
  loadingIcon?: any;
}
```

### Slots

```ts
/**
 * Slots for the EditorDragHandle component
 */
interface EditorDragHandleSlots {
  default(): any;
}
```

### Emits

```ts
/**
 * Emitted events for the EditorDragHandle component
 */
interface EditorDragHandleEmits {
  nodeChange: (payload: [{ node: JSONContent; pos: number; }]) => void;
  hover: (payload: [{ node: JSONContent; pos: number; }]) => void;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    editorDragHandle: {
      slots: {
        root: 'hidden sm:flex items-center justify-center transition-all duration-200 ease-out',
        handle: 'cursor-grab px-1'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/EditorDragHandle.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/editor-drag-handle.ts).


# EditorEmojiMenu

## Uso

O componente EditorEmojiMenu exibe um menu de sugestões de emoji ao digitar o caractere `:` no editor e insere o emoji selecionado. Ele funciona junto com o pacote `@tiptap/extension-emoji` para oferecer suporte a emojis.

> \[!NOTE]
>
> Ele usa o composable `useEditorMenu`, construído sobre o utilitário [Suggestion](https://tiptap.dev/docs/editor/api/utilities/suggestion){rel="&#x22;nofollow&#x22;"} do TipTap, para filtrar os itens conforme você digita e dar suporte à navegação por teclado (setas, enter para selecionar, escape para fechar).

> \[!CAUTION]
>
> Ele deve ser usado dentro do slot padrão de um componente [Editor](https://ui.nitro.news/docs/components/editor) para ter acesso à instância do editor.

::component-example
---
collapse: true
elevated: true
class: p-8
name: editor-emoji-menu-example
---
::

> \[!WARNING]
>
> O pacote `@tiptap/extension-emoji` não é instalado por padrão; você precisa instalá-lo separadamente.

> \[!NOTE]
> See: https\://tiptap.dev/docs/editor/extensions/nodes/emoji
>
> Saiba mais sobre a extensão Emoji na documentação do TipTap.

### Itens

Use a prop `items` como um array de objetos com as seguintes propriedades:

- `name: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `emoji: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `shortcodes?: string[]`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `tags?: string[]`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `group?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `fallbackImage?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

::component-example
---
collapse: true
elevated: true
class: p-8
name: editor-emoji-menu-items-example
---
::

> \[!NOTE]
>
> Você também pode passar um array de arrays para a prop `items` para criar grupos separados de itens.

### Caractere

Use a prop `char` para alterar o caractere de gatilho. O padrão é `:`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}.

```vue
<template>
  <NEditor v-slot="{ editor }">
    <NEditorEmojiMenu :editor="editor" :items="items" char=";" />
  </NEditor>
</template>
```

### Sugestão `4.7+`

Use a prop `suggestion` para personalizar o [comportamento de correspondência do Suggestion](https://tiptap.dev/docs/editor/api/utilities/suggestion#settings){rel="&#x22;nofollow&#x22;"} do TipTap.

Isso é útil quando o caractere de gatilho deve abrir logo após outros caracteres em vez de exigir o prefixo de espaço em branco padrão.

```vue
<template>
  <NEditor v-slot="{ editor }">
    <NEditorEmojiMenu
      :editor="editor"
      :items="items"
      :suggestion="{
        allowedPrefixes: null
      }"
    />
  </NEditor>
</template>
```

### Opções

Use a prop `options` para personalizar o comportamento de posicionamento usando as [opções do Floating UI](https://floating-ui.com/docs/computeposition#options){rel="&#x22;nofollow&#x22;"}.

```vue
<template>
  <NEditor v-slot="{ editor }">
    <NEditorEmojiMenu
      :editor="editor"
      :items="items"
      :options="{
        placement: 'bottom-start',
        offset: 4
      }"
    />
  </NEditor>
</template>
```

## API

### Props

```ts
/**
 * Props for the EditorEmojiMenu component
 */
interface EditorEmojiMenuProps {
  size?: "xs" | "md" | "sm" | "lg" | "xl" | undefined;
  items?: T[] | T[][] | undefined;
  ui?: { content?: SlotClass; viewport?: SlotClass; group?: SlotClass; label?: SlotClass; separator?: SlotClass; item?: SlotClass; itemLeadingIcon?: SlotClass; itemLeadingAvatar?: SlotClass; itemLeadingAvatarSize?: SlotClass; itemWrapper?: SlotClass; itemLabel?: SlotClass; itemDescription?: SlotClass; itemLabelExternalIcon?: SlotClass; } | undefined;
  editor?: Editor;
  /**
   * The trigger character (e.g., '/', '@', ':')
   * @default "\":\""
   */
  char?: string | undefined;
  /**
   * Plugin key to identify this menu
   * @default "\"emojiMenu\""
   */
  pluginKey?: string | undefined;
  /**
   * Fields to filter items by.
   * @default "[\"name\", \"shortcodes\", \"tags\"]"
   */
  filterFields?: string[] | undefined;
  /**
   * Maximum number of items to display
   */
  limit?: number | undefined;
  /**
   * The options for positioning the menu. Those are passed to Floating UI and include options for the placement, offset, flip, shift, size, autoPlacement, hide, and inline middleware.
   */
  options?: FloatingUIOptions | undefined;
  /**
   * Optional TipTap Suggestion matching options.
   */
  suggestion?: Omit<Partial<SuggestionOptions<any, any>>, "editor" | "char" | "pluginKey" | "items" | "command" | "render"> | undefined;
  /**
   * The DOM element to append the menu to. Default is the editor's parent element.
   * 
   * Sometimes the menu needs to be appended to a different DOM context due to accessibility, clipping, or z-index issues.
   */
  appendTo?: HTMLElement | (() => HTMLElement) | undefined;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    editorEmojiMenu: {
      slots: {
        content: 'min-w-48 max-w-60 max-h-96 bg-default shadow-lg rounded-md ring ring-default overflow-hidden data-[state=open]:animate-[scale-in_100ms_ease-out] data-[state=closed]:animate-[scale-out_100ms_ease-in] origin-(--reka-dropdown-menu-content-transform-origin) flex flex-col',
        viewport: 'relative divide-y divide-default scroll-py-1 overflow-y-auto flex-1',
        group: 'p-1 isolate',
        label: 'w-full flex items-center font-semibold text-highlighted',
        separator: '-mx-1 my-1 h-px bg-border',
        item: 'group relative w-full flex items-start select-none outline-none before:absolute before:z-[-1] before:inset-px before:rounded-md data-disabled:cursor-not-allowed data-disabled:opacity-75',
        itemLeadingIcon: 'shrink-0 flex items-center justify-center',
        itemLeadingAvatar: 'shrink-0',
        itemLeadingAvatarSize: '',
        itemWrapper: 'flex-1 flex flex-col text-start min-w-0',
        itemLabel: 'truncate',
        itemDescription: 'truncate text-muted',
        itemLabelExternalIcon: 'inline-block size-3 align-top text-dimmed'
      },
      variants: {
        size: {
          xs: {
            label: 'p-1 text-[10px]/3 gap-1',
            item: 'p-1 text-xs gap-1',
            itemLeadingIcon: 'size-4 text-sm',
            itemLeadingAvatarSize: '3xs'
          },
          sm: {
            label: 'p-1.5 text-[10px]/3 gap-1.5',
            item: 'p-1.5 text-xs gap-1.5',
            itemLeadingIcon: 'size-4 text-sm',
            itemLeadingAvatarSize: '3xs'
          },
          md: {
            label: 'p-1.5 text-xs gap-1.5',
            item: 'p-1.5 text-sm gap-1.5',
            itemLeadingIcon: 'size-5 text-base',
            itemLeadingAvatarSize: '2xs'
          },
          lg: {
            label: 'p-2 text-xs gap-2',
            item: 'p-2 text-sm gap-2',
            itemLeadingIcon: 'size-5 text-base',
            itemLeadingAvatarSize: '2xs'
          },
          xl: {
            label: 'p-2 text-sm gap-2',
            item: 'p-2 text-base gap-2',
            itemLeadingIcon: 'size-6 text-xl',
            itemLeadingAvatarSize: 'xs'
          }
        },
        active: {
          true: {
            item: 'text-highlighted before:bg-elevated/75',
            itemLeadingIcon: 'text-default'
          },
          false: {
            item: [
              'text-default data-highlighted:not-data-disabled:text-highlighted data-highlighted:not-data-disabled:before:bg-elevated/50',
              'transition-colors before:transition-colors'
            ],
            itemLeadingIcon: [
              'text-dimmed group-data-highlighted:not-group-data-disabled:text-default',
              'transition-colors'
            ]
          }
        }
      },
      defaultVariants: {
        size: 'md'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/EditorEmojiMenu.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/editor-emoji-menu.ts).


# EditorMentionMenu

## Uso

O componente EditorMentionMenu exibe um menu de sugestões de usuários ao digitar um caractere de gatilho (o padrão é `@`) no editor e insere a menção selecionada usando o pacote `@tiptap/extension-mention`. O caractere de gatilho também é usado como prefixo ao renderizar a menção inserida.

> \[!NOTE]
>
> Ele usa o composable `useEditorMenu`, construído sobre o utilitário [Suggestion](https://tiptap.dev/docs/editor/api/utilities/suggestion){rel="&#x22;nofollow&#x22;"} do TipTap, para filtrar os itens conforme você digita e dar suporte à navegação por teclado (setas, enter para selecionar, escape para fechar).

> \[!CAUTION]
>
> Ele deve ser usado dentro do slot padrão de um componente [Editor](https://ui.nitro.news/docs/components/editor) para ter acesso à instância do editor.

::component-example
---
collapse: true
elevated: true
class: p-8
name: editor-mention-menu-example
---
::

> \[!NOTE]
> See: https\://tiptap.dev/docs/editor/extensions/nodes/mention
>
> Saiba mais sobre a extensão Mention na documentação do TipTap.

### Itens

Use a prop `items` como um array de objetos com as seguintes propriedades:

- `label: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `avatar?: AvatarProps`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `icon?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `description?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `disabled?: boolean`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

::component-example
---
collapse: true
elevated: true
class: p-8
name: editor-mention-menu-items-example
---
::

> \[!NOTE]
>
> Você também pode passar um array de arrays para a prop `items` para criar grupos separados de itens.

### Caractere

Use a prop `char` para alterar o caractere de gatilho. O padrão é `@`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}. O caractere de gatilho também é usado como prefixo ao renderizar a menção inserida (ex.: `#channel` em vez de `@channel`).

```vue
<template>
  <NEditor v-slot="{ editor }">
    <NEditorMentionMenu :editor="editor" :items="channels" char="#" />
  </NEditor>
</template>
```

> \[!NOTE]
>
> Você pode usar vários componentes `EditorMentionMenu` no mesmo editor com props `char` e `plugin-key` diferentes para suportar diferentes tipos de menção.
>
> ```vue
> <template>
>   <NEditor v-slot="{ editor }">
>     <NEditorMentionMenu :editor="editor" :items="users" plugin-key="mentionMenu" />
>     <NEditorMentionMenu :editor="editor" :items="tags" char="#" plugin-key="tagMenu" />
>   </NEditor>
> </template>
> ```

### Sugestão `4.7+`

Use a prop `suggestion` para personalizar o [comportamento de correspondência do Suggestion](https://tiptap.dev/docs/editor/api/utilities/suggestion#settings){rel="&#x22;nofollow&#x22;"} do TipTap.

Isso é útil quando o caractere de gatilho deve abrir logo após outros caracteres em vez de exigir o prefixo de espaço em branco padrão.

```vue
<template>
  <NEditor v-slot="{ editor }">
    <NEditorMentionMenu
      :editor="editor"
      :items="items"
      char="#"
      :suggestion="{
        allowedPrefixes: null
      }"
    />
  </NEditor>
</template>
```

### Opções

Use a prop `options` para personalizar o comportamento de posicionamento usando as [opções do Floating UI](https://floating-ui.com/docs/computeposition#options){rel="&#x22;nofollow&#x22;"}.

```vue
<template>
  <NEditor v-slot="{ editor }">
    <NEditorMentionMenu
      :editor="editor"
      :items="items"
      :options="{
        placement: 'bottom-start',
        offset: 4
      }"
    />
  </NEditor>
</template>
```

## Exemplos

### Com filtro ignorado `4.4+`

Você pode definir a prop `ignore-filter` como `true` para desabilitar a busca interna e usar sua própria lógica de busca. Use `v-model:search-term` para acessar o termo de busca atual e buscar itens de uma API.

::component-example
---
collapse: true
elevated: true
class: p-8
name: editor-mention-menu-ignore-filter-example
---
::

> \[!NOTE]
>
> Este exemplo usa [`refDebounced`](https://vueuse.org/shared/refDebounced/){rel="&#x22;nofollow&#x22;"} para aplicar debounce nas chamadas de API.

## API

### Props

```ts
/**
 * Props for the EditorMentionMenu component
 */
interface EditorMentionMenuProps {
  size?: "xs" | "md" | "sm" | "lg" | "xl" | undefined;
  items?: T[] | T[][] | undefined;
  ui?: { content?: SlotClass; viewport?: SlotClass; group?: SlotClass; label?: SlotClass; separator?: SlotClass; item?: SlotClass; itemLeadingIcon?: SlotClass; itemLeadingAvatar?: SlotClass; itemLeadingAvatarSize?: SlotClass; itemWrapper?: SlotClass; itemLabel?: SlotClass; itemDescription?: SlotClass; itemLabelExternalIcon?: SlotClass; } | undefined;
  editor?: Editor;
  /**
   * The trigger character (e.g., '/', '@', ':')
   * @default "\"@\""
   */
  char?: string | undefined;
  /**
   * Plugin key to identify this menu
   * @default "\"mentionMenu\""
   */
  pluginKey?: string | undefined;
  /**
   * Fields to filter items by.
   */
  filterFields?: string[] | undefined;
  /**
   * Maximum number of items to display
   */
  limit?: number | undefined;
  /**
   * The options for positioning the menu. Those are passed to Floating UI and include options for the placement, offset, flip, shift, size, autoPlacement, hide, and inline middleware.
   */
  options?: FloatingUIOptions | undefined;
  /**
   * Optional TipTap Suggestion matching options.
   */
  suggestion?: Omit<Partial<SuggestionOptions<any, any>>, "editor" | "char" | "pluginKey" | "items" | "command" | "render"> | undefined;
  /**
   * The DOM element to append the menu to. Default is the editor's parent element.
   * 
   * Sometimes the menu needs to be appended to a different DOM context due to accessibility, clipping, or z-index issues.
   */
  appendTo?: HTMLElement | (() => HTMLElement) | undefined;
  /**
   * Whether to ignore the default filtering.
   * When `true`, items will not be filtered which is useful for custom filtering (useAsyncData, useFetch, etc.).
   */
  ignoreFilter?: boolean | undefined;
  /**
   * @default "\"\""
   */
  searchTerm?: string | undefined;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    editorMentionMenu: {
      slots: {
        content: 'min-w-48 max-w-60 max-h-96 bg-default shadow-lg rounded-md ring ring-default overflow-hidden data-[state=open]:animate-[scale-in_100ms_ease-out] data-[state=closed]:animate-[scale-out_100ms_ease-in] origin-(--reka-dropdown-menu-content-transform-origin) flex flex-col',
        viewport: 'relative divide-y divide-default scroll-py-1 overflow-y-auto flex-1',
        group: 'p-1 isolate',
        label: 'w-full flex items-center font-semibold text-highlighted',
        separator: '-mx-1 my-1 h-px bg-border',
        item: 'group relative w-full flex items-start select-none outline-none before:absolute before:z-[-1] before:inset-px before:rounded-md data-disabled:cursor-not-allowed data-disabled:opacity-75',
        itemLeadingIcon: 'shrink-0 flex items-center justify-center',
        itemLeadingAvatar: 'shrink-0',
        itemLeadingAvatarSize: '',
        itemWrapper: 'flex-1 flex flex-col text-start min-w-0',
        itemLabel: 'truncate',
        itemDescription: 'truncate text-muted',
        itemLabelExternalIcon: 'inline-block size-3 align-top text-dimmed'
      },
      variants: {
        size: {
          xs: {
            label: 'p-1 text-[10px]/3 gap-1',
            item: 'p-1 text-xs gap-1',
            itemLeadingIcon: 'size-4 text-sm',
            itemLeadingAvatarSize: '3xs'
          },
          sm: {
            label: 'p-1.5 text-[10px]/3 gap-1.5',
            item: 'p-1.5 text-xs gap-1.5',
            itemLeadingIcon: 'size-4 text-sm',
            itemLeadingAvatarSize: '3xs'
          },
          md: {
            label: 'p-1.5 text-xs gap-1.5',
            item: 'p-1.5 text-sm gap-1.5',
            itemLeadingIcon: 'size-5 text-base',
            itemLeadingAvatarSize: '2xs'
          },
          lg: {
            label: 'p-2 text-xs gap-2',
            item: 'p-2 text-sm gap-2',
            itemLeadingIcon: 'size-5 text-base',
            itemLeadingAvatarSize: '2xs'
          },
          xl: {
            label: 'p-2 text-sm gap-2',
            item: 'p-2 text-base gap-2',
            itemLeadingIcon: 'size-6 text-xl',
            itemLeadingAvatarSize: 'xs'
          }
        },
        active: {
          true: {
            item: 'text-highlighted before:bg-elevated/75',
            itemLeadingIcon: 'text-default'
          },
          false: {
            item: [
              'text-default data-highlighted:not-data-disabled:text-highlighted data-highlighted:not-data-disabled:before:bg-elevated/50',
              'transition-colors before:transition-colors'
            ],
            itemLeadingIcon: [
              'text-dimmed group-data-highlighted:not-group-data-disabled:text-default',
              'transition-colors'
            ]
          }
        }
      },
      defaultVariants: {
        size: 'md'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/EditorMentionMenu.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/editor-mention-menu.ts).


# EditorSuggestionMenu

## Uso

O componente EditorSuggestionMenu exibe um menu de sugestões de formatação e ações ao digitar um caractere de gatilho no editor e executa o [handler](https://ui.nitro.news/docs/components/editor#handlers) correspondente quando um item é selecionado.

> \[!NOTE]
>
> Ele usa o composable `useEditorMenu`, construído sobre o utilitário [Suggestion](https://tiptap.dev/docs/editor/api/utilities/suggestion){rel="&#x22;nofollow&#x22;"} do TipTap, para filtrar os itens conforme você digita e dar suporte à navegação por teclado (setas, enter para selecionar, escape para fechar).

> \[!CAUTION]
>
> Ele deve ser usado dentro do slot padrão de um componente [Editor](https://ui.nitro.news/docs/components/editor) para ter acesso à instância do editor.

::component-example
---
collapse: true
elevated: true
class: p-8
name: editor-suggestion-menu-example
---
::

### Itens

Use a prop `items` como um array de objetos com as seguintes propriedades:

- [`kind?: "textAlign" | "heading" | "link" | "image" | "blockquote" | "bulletList" | "orderedList" | "taskList" | "codeBlock" | "horizontalRule" | "paragraph" | "clearFormatting" | "duplicate" | "delete" | "moveUp" | "moveDown" | "suggestion" | "mention" | "emoji"`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}](https://ui.nitro.news/docs/components/editor#handlers)
- `label?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `description?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `icon?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `type?: "label" | "separator"`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `disabled?: boolean`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

::component-example
---
collapse: true
elevated: true
class: p-8
name: editor-suggestion-menu-items-example
---
::

> \[!NOTE]
>
> Você também pode passar um array de arrays para a prop `items` para criar grupos separados de itens.

> \[!TIP]
>
> Use `type: 'label'` para cabeçalhos de seção e `type: 'separator'` para divisórias visuais, organizando os comandos em grupos lógicos para facilitar a descoberta.

### Caractere

Use a prop `char` para alterar o caractere de gatilho. O padrão é `/`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}.

```vue
<template>
  <NEditor v-slot="{ editor }">
    <NEditorSuggestionMenu :editor="editor" :items="items" char=">" />
  </NEditor>
</template>
```

### Sugestão `4.7+`

Use a prop `suggestion` para personalizar o [comportamento de correspondência do Suggestion](https://tiptap.dev/docs/editor/api/utilities/suggestion#settings){rel="&#x22;nofollow&#x22;"} do TipTap.

Isso é útil quando o caractere de gatilho deve abrir logo após outros caracteres em vez de exigir o prefixo de espaço em branco padrão.

```vue
<template>
  <NEditor v-slot="{ editor }">
    <NEditorSuggestionMenu
      :editor="editor"
      :items="items"
      char=":"
      :suggestion="{
        allowedPrefixes: null
      }"
    />
  </NEditor>
</template>
```

### Opções

Use a prop `options` para personalizar o comportamento de posicionamento usando as [opções do Floating UI](https://floating-ui.com/docs/computeposition#options){rel="&#x22;nofollow&#x22;"}.

```vue
<template>
  <NEditor v-slot="{ editor }">
    <NEditorSuggestionMenu
      :editor="editor"
      :items="items"
      :options="{
        placement: 'bottom-start',
        offset: 4
      }"
    />
  </NEditor>
</template>
```

## API

### Props

```ts
/**
 * Props for the EditorSuggestionMenu component
 */
interface EditorSuggestionMenuProps {
  size?: "xs" | "md" | "sm" | "lg" | "xl" | undefined;
  items?: T[] | T[][] | undefined;
  ui?: { content?: SlotClass; viewport?: SlotClass; group?: SlotClass; label?: SlotClass; separator?: SlotClass; item?: SlotClass; itemLeadingIcon?: SlotClass; itemLeadingAvatar?: SlotClass; itemLeadingAvatarSize?: SlotClass; itemWrapper?: SlotClass; itemLabel?: SlotClass; itemDescription?: SlotClass; itemLabelExternalIcon?: SlotClass; } | undefined;
  editor?: Editor;
  /**
   * The trigger character (e.g., '/', '@', ':')
   * @default "\"/\""
   */
  char?: string | undefined;
  /**
   * Plugin key to identify this menu
   * @default "\"suggestionMenu\""
   */
  pluginKey?: string | undefined;
  /**
   * Fields to filter items by.
   */
  filterFields?: string[] | undefined;
  /**
   * Maximum number of items to display
   */
  limit?: number | undefined;
  /**
   * The options for positioning the menu. Those are passed to Floating UI and include options for the placement, offset, flip, shift, size, autoPlacement, hide, and inline middleware.
   */
  options?: FloatingUIOptions | undefined;
  /**
   * Optional TipTap Suggestion matching options.
   */
  suggestion?: Omit<Partial<SuggestionOptions<any, any>>, "editor" | "char" | "pluginKey" | "items" | "command" | "render"> | undefined;
  /**
   * The DOM element to append the menu to. Default is the editor's parent element.
   * 
   * Sometimes the menu needs to be appended to a different DOM context due to accessibility, clipping, or z-index issues.
   */
  appendTo?: HTMLElement | (() => HTMLElement) | undefined;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    editorSuggestionMenu: {
      slots: {
        content: 'min-w-48 max-w-60 max-h-96 bg-default shadow-lg rounded-md ring ring-default overflow-hidden data-[state=open]:animate-[scale-in_100ms_ease-out] data-[state=closed]:animate-[scale-out_100ms_ease-in] origin-(--reka-dropdown-menu-content-transform-origin) flex flex-col',
        viewport: 'relative divide-y divide-default scroll-py-1 overflow-y-auto flex-1',
        group: 'p-1 isolate',
        label: 'w-full flex items-center font-semibold text-highlighted',
        separator: '-mx-1 my-1 h-px bg-border',
        item: 'group relative w-full flex items-start select-none outline-none before:absolute before:z-[-1] before:inset-px before:rounded-md data-disabled:cursor-not-allowed data-disabled:opacity-75',
        itemLeadingIcon: 'shrink-0 flex items-center justify-center',
        itemLeadingAvatar: 'shrink-0',
        itemLeadingAvatarSize: '',
        itemWrapper: 'flex-1 flex flex-col text-start min-w-0',
        itemLabel: 'truncate',
        itemDescription: 'truncate text-muted',
        itemLabelExternalIcon: 'inline-block size-3 align-top text-dimmed'
      },
      variants: {
        size: {
          xs: {
            label: 'p-1 text-[10px]/3 gap-1',
            item: 'p-1 text-xs gap-1',
            itemLeadingIcon: 'size-4 text-sm',
            itemLeadingAvatarSize: '3xs'
          },
          sm: {
            label: 'p-1.5 text-[10px]/3 gap-1.5',
            item: 'p-1.5 text-xs gap-1.5',
            itemLeadingIcon: 'size-4 text-sm',
            itemLeadingAvatarSize: '3xs'
          },
          md: {
            label: 'p-1.5 text-xs gap-1.5',
            item: 'p-1.5 text-sm gap-1.5',
            itemLeadingIcon: 'size-5 text-base',
            itemLeadingAvatarSize: '2xs'
          },
          lg: {
            label: 'p-2 text-xs gap-2',
            item: 'p-2 text-sm gap-2',
            itemLeadingIcon: 'size-5 text-base',
            itemLeadingAvatarSize: '2xs'
          },
          xl: {
            label: 'p-2 text-sm gap-2',
            item: 'p-2 text-base gap-2',
            itemLeadingIcon: 'size-6 text-xl',
            itemLeadingAvatarSize: 'xs'
          }
        },
        active: {
          true: {
            item: 'text-highlighted before:bg-elevated/75',
            itemLeadingIcon: 'text-default'
          },
          false: {
            item: [
              'text-default data-highlighted:not-data-disabled:text-highlighted data-highlighted:not-data-disabled:before:bg-elevated/50',
              'transition-colors before:transition-colors'
            ],
            itemLeadingIcon: [
              'text-dimmed group-data-highlighted:not-group-data-disabled:text-default',
              'transition-colors'
            ]
          }
        }
      },
      defaultVariants: {
        size: 'md'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/EditorSuggestionMenu.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/editor-suggestion-menu.ts).


# EditorToolbar

## Uso

O componente EditorToolbar exibe uma barra de ferramentas com botões de formatação que sincronizam automaticamente seu estado ativo com o conteúdo do editor. Ele suporta três modos de layout usando o pacote `@tiptap/vue-3/menus`:

- `fixed`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} (always visible)
- `bubble`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} (appears on text selection)
- `floating`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} (appears on empty lines)

> \[!CAUTION]
>
> Ele deve ser usado dentro do slot padrão de um componente [Editor](https://ui.nitro.news/docs/components/editor) para ter acesso à instância do editor.

::component-example
---
collapse: true
elevated: true
class: p-8
name: editor-toolbar-example
---
::

> \[!NOTE]
>
> Os layouts bubble e floating usam as extensões [BubbleMenu](https://tiptap.dev/docs/editor/extensions/functionality/bubble-menu){rel="&#x22;nofollow&#x22;"} e [FloatingMenu](https://tiptap.dev/docs/editor/extensions/functionality/floating-menu){rel="&#x22;nofollow&#x22;"} do TipTap.

### Itens

Use a prop `items` como um array de objetos com as seguintes propriedades:

- `label?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `icon?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `color?: "error" | "primary" | "secondary" | "success" | "info" | "warning" | "neutral"`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `activeColor?: "error" | "primary" | "secondary" | "success" | "info" | "warning" | "neutral"`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `variant?: "solid" | "outline" | "soft" | "ghost" | "link" | "subtle"`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `activeVariant?: "solid" | "outline" | "soft" | "ghost" | "link" | "subtle"`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `size?: "xs" | "sm" | "md" | "lg" | "xl"`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- [`kind?: "mark" | "textAlign" | "heading" | "link" | "image" | "blockquote" | "bulletList" | "orderedList" | "taskList" | "codeBlock" | "horizontalRule" | "paragraph" | "undo" | "redo" | "clearFormatting" | "duplicate" | "delete" | "moveUp" | "moveDown" | "suggestion" | "mention" | "emoji"`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}](https://ui.nitro.news/docs/components/editor#handlers)
- `disabled?: boolean`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `loading?: boolean`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `active?: boolean`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `tooltip?: TooltipProps`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- [`slot?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}](https://ui.nitro.news/#with-link-popover)
- `onClick?: (e: MouseEvent) => void`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `items?: EditorToolbarItem[] | EditorToolbarItem[][]`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `class?: any`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Você pode passar qualquer propriedade do componente [Button](https://ui.nitro.news/docs/components/button#props), como `color`, `variant`, `size`, etc.

::component-example
---
collapse: true
elevated: true
class: p-8
name: editor-toolbar-items-example
---
::

> \[!NOTE]
>
> Você também pode passar um array de arrays para a prop `items` para criar grupos separados de itens.

> \[!TIP]
>
> Cada item pode receber um array `items` de objetos com as mesmas propriedades da prop `items` para criar um [DropdownMenu](https://ui.nitro.news/docs/components/dropdown-menu).

### Layout

Use a prop `layout` para alterar como a barra de ferramentas é exibida. O padrão é `fixed`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}.

::component-example
---
collapse: true
elevated: true
options:
  - name: layout
    label: Layout
    default: bubble
    items:
      - fixed
      - bubble
      - floating
class: p-8
name: editor-toolbar-layout-example
---
::

### Opções

Ao usar os layouts `bubble`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} ou `floating`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, use a prop `options` para personalizar o comportamento de posicionamento usando as [opções do Floating UI](https://floating-ui.com/docs/computeposition#options){rel="&#x22;nofollow&#x22;"}.

```vue
<template>
  <NEditor v-slot="{ editor }">
    <NEditorToolbar
      :editor="editor"
      :items="items"
      layout="bubble"
      :options="{
        placement: 'top',
        offset: 8,
        flip: { padding: 8 },
        shift: { padding: 8 }
      }"
    />
  </NEditor>
</template>
```

### Deve exibir

Ao usar os layouts `bubble`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} ou `floating`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, use a prop `should-show` para controlar quando a barra de ferramentas aparece. Essa função recebe o contexto sobre o estado do editor e retorna um booleano.

```vue
<template>
  <NEditor v-slot="{ editor }">
    <NEditorToolbar
      :editor="editor"
      :items="items"
      layout="bubble"
      :should-show="({ view, state }) => {
        const { selection } = state
        const { from, to } = selection
        const text = state.doc.textBetween(from, to)
        return view.hasFocus() && !selection.empty && text.length > 10
      }"
    />
  </NEditor>
</template>
```

## Exemplos

### Com barra de ferramentas de imagem

Use a prop `should-show` para criar barras de ferramentas específicas de contexto que aparecem apenas para certos tipos de node. Este exemplo mostra uma barra de ferramentas `bubble` com ações de download e exclusão que só aparece quando uma imagem é selecionada.

::component-example
---
collapse: true
elevated: true
class: p-8
name: editor-toolbar-image-example
---
::

### Com popover de link

Este exemplo demonstra como criar um popover de link personalizado usando a propriedade `slot` nos itens da barra de ferramentas e o componente [Popover](https://ui.nitro.news/docs/components/popover).

1. Crie um componente Vue que envolve um [Popover](https://ui.nitro.news/docs/components/popover) com funcionalidade de edição de link:

::component-example{collapse :preview='false' name="editor-link-popover"}
::

2. Use o componente personalizado na barra de ferramentas com um slot nomeado:

::component-example
---
collapse: true
elevated: true
class: p-8
name: editor-toolbar-custom-slot-example
---
::

## API

### Props

```ts
/**
 * Props for the EditorToolbar component
 */
interface EditorToolbarProps {
  editor?: Editor;
  /**
   * The element or component this component should render as.
   */
  as?: any;
  /**
   * The color of the toolbar controls.
   * @default "\"neutral\""
   */
  color?: "primary" | "secondary" | "accent" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
  /**
   * The variant of the toolbar controls.
   * @default "\"ghost\""
   */
  variant?: "solid" | "outline" | "soft" | "subtle" | "ghost" | "link" | undefined;
  /**
   * The color of the active toolbar control.
   * @default "\"primary\""
   */
  activeColor?: "primary" | "secondary" | "accent" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
  /**
   * The variant of the active toolbar control.
   * @default "\"soft\""
   */
  activeVariant?: "solid" | "outline" | "soft" | "subtle" | "ghost" | "link" | undefined;
  /**
   * The size of the toolbar controls.
   * @default "\"sm\""
   */
  size?: "xs" | "sm" | "md" | "lg" | "xl" | undefined;
  items?: T | undefined;
  ui?: { root?: SlotClass; base?: SlotClass; group?: SlotClass; separator?: SlotClass; } | undefined;
  /**
   * @default "\"fixed\""
   */
  layout?: "fixed" | "floating" | "bubble" | undefined;
  /**
   * The plugin key.
   * The plugin key for the floating menu.
   */
  pluginKey?: unknown;
  /**
   * The delay in milliseconds before the menu should be updated.
   * This can be useful to prevent performance issues.
   */
  updateDelay?: unknown;
  /**
   * The delay in milliseconds before the menu position should be updated on window resize.
   * This can be useful to prevent performance issues.
   */
  resizeDelay?: unknown;
  /**
   * A function that determines whether the menu should be shown or not.
   * If this function returns `false`, the menu will be hidden, otherwise it will be shown.
   */
  shouldShow?: unknown;
  /**
   * The DOM element to append your menu to. Default is the editor's parent element.
   * 
   * Sometimes the menu needs to be appended to a different DOM context due to accessibility, clipping, or z-index issues.
   */
  appendTo?: unknown;
  /**
   * A function that returns the virtual element for the menu.
   * This is useful when the menu needs to be positioned relative to a specific DOM element.
   */
  getReferencedVirtualElement?: unknown;
  /**
   * The options for the bubble menu. Those are passed to Floating UI and include options for the placement, offset, flip, shift, arrow, size, autoPlacement,
   * hide, and inline middlewares.
   * The options for the floating menu. Those are passed to Floating UI and include options for the placement, offset, flip, shift, arrow, size, autoPlacement,
   * hide, and inline middlewares.
   */
  options?: unknown;
}
```

### Slots

```ts
/**
 * Slots for the EditorToolbar component
 */
interface EditorToolbarSlots {
  item(): any;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    editorToolbar: {
      slots: {
        root: 'focus:outline-none',
        base: 'flex items-stretch gap-1.5',
        group: 'flex items-center gap-0.5',
        separator: 'w-px self-stretch bg-border'
      },
      variants: {
        layout: {
          bubble: {
            base: 'bg-default border border-default rounded-lg p-1'
          },
          floating: {
            base: 'bg-default border border-default rounded-lg p-1'
          },
          fixed: {
            base: ''
          }
        }
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/EditorToolbar.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/editor-toolbar.ts).


# Empty

## Uso

```vue
<template>
  <n-empty :actions=[{"icon":"i-lucide-plus","label":"Create new"},{"icon":"i-lucide-refresh-cw","label":"Refresh","color":"neutral","variant":"subtle"}] description=Parece que você ainda não adicionou nenhum projeto. Crie um para começar. icon=i-lucide-file title=Nenhum projeto encontrado />
</template>
```

### Título

Use a prop `title` para definir o título do estado vazio.

```vue
<template>
  <UEmpty title="No projects found" />
</template>
```

### Descrição

Use a prop `description` para definir a descrição do estado vazio.

```vue
<template>
  <UEmpty title="No projects found" description="It looks like you haven't added any projects. Create one to get started." />
</template>
```

### Ícone

Use a prop `icon` para definir o ícone do estado vazio.

```vue
<template>
  <UEmpty icon="i-lucide-file" title="No projects found" description="It looks like you haven't added any projects. Create one to get started." />
</template>
```

### Avatar

Use a prop `avatar` para definir o avatar do estado vazio.

```vue
<template>
  <UEmpty :avatar="{
  src: 'https://github.com/nuxt.png'
}" title="No projects found" description="It looks like you haven't added any projects. Create one to get started." />
</template>
```

### Ações

Use a prop `actions` para adicionar algumas ações de [Button](https://ui.nitro.news/docs/components/button) ao estado vazio.

```vue
<template>
  <UEmpty icon="i-lucide-file" title="No projects found" description="It looks like you haven't added any projects. Create one to get started." :actions="[
  {
    icon: 'i-lucide-plus',
    label: 'Create new'
  },
  {
    icon: 'i-lucide-refresh-cw',
    label: 'Refresh',
    color: 'neutral',
    variant: 'subtle'
  }
]" />
</template>
```

### Variante

Use a prop `variant` para alterar a variante do estado vazio.

```vue
<template>
  <UEmpty variant="naked" icon="i-lucide-bell" title="No notifications" description="You're all caught up. New notifications will appear here." :actions="[
  {
    icon: 'i-lucide-refresh-cw',
    label: 'Refresh',
    color: 'neutral',
    variant: 'subtle'
  }
]" />
</template>
```

### Tamanho

Use a prop `size` para alterar o tamanho do estado vazio.

```vue
<template>
  <UEmpty size="xl" icon="i-lucide-bell" title="No notifications" description="You're all caught up. New notifications will appear here." :actions="[
  {
    icon: 'i-lucide-refresh-cw',
    label: 'Refresh',
    color: 'neutral',
    variant: 'subtle'
  }
]" />
</template>
```

## Exemplos

### Com slots

Use os slots disponíveis para criar um estado vazio mais complexo.

::component-example{collapse name="empty-slots-example"}
::

## API

### Props

```ts
/**
 * Props for the Empty component
 */
interface EmptyProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  /**
   * The icon displayed above the title.
   */
  icon?: any;
  avatar?: AvatarProps | undefined;
  title?: string | undefined;
  description?: string | undefined;
  /**
   * Display a list of Button in the body.
   */
  actions?: ButtonProps[] | undefined;
  variant?: "solid" | "outline" | "soft" | "subtle" | "naked" | undefined;
  size?: "md" | "xs" | "sm" | "lg" | "xl" | undefined;
  ui?: { root?: SlotClass; header?: SlotClass; avatar?: SlotClass; title?: SlotClass; description?: SlotClass; body?: SlotClass; actions?: SlotClass; footer?: SlotClass; } | undefined;
}
```

### Slots

```ts
/**
 * Slots for the Empty component
 */
interface EmptySlots {
  header(): any;
  leading(): any;
  title(): any;
  description(): any;
  body(): any;
  actions(): any;
  footer(): any;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    empty: {
      slots: {
        root: 'relative flex flex-col items-center justify-center gap-4 rounded-lg p-4 sm:p-6 lg:p-8 min-w-0',
        header: 'flex flex-col items-center gap-2 max-w-sm text-center',
        avatar: 'shrink-0 mb-2',
        title: 'text-highlighted text-pretty font-medium',
        description: 'text-balance text-center',
        body: 'flex flex-col items-center gap-4 max-w-sm',
        actions: 'flex flex-wrap justify-center gap-2 shrink-0',
        footer: 'flex flex-col items-center gap-2 max-w-sm'
      },
      variants: {
        color: {
          primary: '',
          secondary: '',
          accent: '',
          success: '',
          info: '',
          warning: '',
          error: '',
          neutral: ''
        },
        size: {
          xs: {
            avatar: 'size-8 text-base',
            title: 'text-sm',
            description: 'text-xs'
          },
          sm: {
            avatar: 'size-9 text-lg',
            title: 'text-sm',
            description: 'text-xs'
          },
          md: {
            avatar: 'size-10 text-xl',
            title: 'text-base',
            description: 'text-sm'
          },
          lg: {
            avatar: 'size-11 text-[22px]',
            title: 'text-base',
            description: 'text-sm'
          },
          xl: {
            avatar: 'size-12 text-2xl',
            title: 'text-lg',
            description: 'text-base'
          }
        },
        variant: {
          solid: '',
          outline: '',
          soft: '',
          subtle: '',
          naked: ''
        }
      },
      compoundVariants: [
        {
          variant: 'solid',
          color: 'primary',
          class: {
            root: 'bg-primary',
            title: 'text-inverted',
            description: 'text-inverted'
          }
        },
        {
          variant: 'solid',
          color: 'secondary',
          class: {
            root: 'bg-secondary',
            title: 'text-inverted',
            description: 'text-inverted'
          }
        },
        {
          variant: 'solid',
          color: 'accent',
          class: {
            root: 'bg-accent',
            title: 'text-inverted',
            description: 'text-inverted'
          }
        },
        {
          variant: 'solid',
          color: 'success',
          class: {
            root: 'bg-success',
            title: 'text-inverted',
            description: 'text-inverted'
          }
        },
        {
          variant: 'solid',
          color: 'info',
          class: {
            root: 'bg-info',
            title: 'text-inverted',
            description: 'text-inverted'
          }
        },
        {
          variant: 'solid',
          color: 'warning',
          class: {
            root: 'bg-warning',
            title: 'text-inverted',
            description: 'text-inverted'
          }
        },
        {
          variant: 'solid',
          color: 'error',
          class: {
            root: 'bg-error',
            title: 'text-inverted',
            description: 'text-inverted'
          }
        },
        {
          variant: 'outline',
          color: 'primary',
          class: {
            root: 'bg-default ring ring-primary',
            title: 'text-primary',
            description: 'text-muted'
          }
        },
        {
          variant: 'outline',
          color: 'secondary',
          class: {
            root: 'bg-default ring ring-secondary',
            title: 'text-secondary',
            description: 'text-muted'
          }
        },
        {
          variant: 'outline',
          color: 'accent',
          class: {
            root: 'bg-default ring ring-accent',
            title: 'text-accent',
            description: 'text-muted'
          }
        },
        {
          variant: 'outline',
          color: 'success',
          class: {
            root: 'bg-default ring ring-success',
            title: 'text-success',
            description: 'text-muted'
          }
        },
        {
          variant: 'outline',
          color: 'info',
          class: {
            root: 'bg-default ring ring-info',
            title: 'text-info',
            description: 'text-muted'
          }
        },
        {
          variant: 'outline',
          color: 'warning',
          class: {
            root: 'bg-default ring ring-warning',
            title: 'text-warning',
            description: 'text-muted'
          }
        },
        {
          variant: 'outline',
          color: 'error',
          class: {
            root: 'bg-default ring ring-error',
            title: 'text-error',
            description: 'text-muted'
          }
        },
        {
          variant: 'soft',
          color: 'primary',
          class: {
            root: 'bg-primary/10',
            title: 'text-primary',
            description: 'text-muted'
          }
        },
        {
          variant: 'soft',
          color: 'secondary',
          class: {
            root: 'bg-secondary/10',
            title: 'text-secondary',
            description: 'text-muted'
          }
        },
        {
          variant: 'soft',
          color: 'accent',
          class: {
            root: 'bg-accent/10',
            title: 'text-accent',
            description: 'text-muted'
          }
        },
        {
          variant: 'soft',
          color: 'success',
          class: {
            root: 'bg-success/10',
            title: 'text-success',
            description: 'text-muted'
          }
        },
        {
          variant: 'soft',
          color: 'info',
          class: {
            root: 'bg-info/10',
            title: 'text-info',
            description: 'text-muted'
          }
        },
        {
          variant: 'soft',
          color: 'warning',
          class: {
            root: 'bg-warning/10',
            title: 'text-warning',
            description: 'text-muted'
          }
        },
        {
          variant: 'soft',
          color: 'error',
          class: {
            root: 'bg-error/10',
            title: 'text-error',
            description: 'text-muted'
          }
        },
        {
          variant: 'subtle',
          color: 'primary',
          class: {
            root: 'bg-primary/10 ring ring-primary',
            title: 'text-primary',
            description: 'text-muted'
          }
        },
        {
          variant: 'subtle',
          color: 'secondary',
          class: {
            root: 'bg-secondary/10 ring ring-secondary',
            title: 'text-secondary',
            description: 'text-muted'
          }
        },
        {
          variant: 'subtle',
          color: 'accent',
          class: {
            root: 'bg-accent/10 ring ring-accent',
            title: 'text-accent',
            description: 'text-muted'
          }
        },
        {
          variant: 'subtle',
          color: 'success',
          class: {
            root: 'bg-success/10 ring ring-success',
            title: 'text-success',
            description: 'text-muted'
          }
        },
        {
          variant: 'subtle',
          color: 'info',
          class: {
            root: 'bg-info/10 ring ring-info',
            title: 'text-info',
            description: 'text-muted'
          }
        },
        {
          variant: 'subtle',
          color: 'warning',
          class: {
            root: 'bg-warning/10 ring ring-warning',
            title: 'text-warning',
            description: 'text-muted'
          }
        },
        {
          variant: 'subtle',
          color: 'error',
          class: {
            root: 'bg-error/10 ring ring-error',
            title: 'text-error',
            description: 'text-muted'
          }
        },
        {
          variant: 'naked',
          color: 'primary',
          class: {
            root: 'bg-transparent',
            title: 'text-primary',
            description: 'text-muted'
          }
        },
        {
          variant: 'naked',
          color: 'secondary',
          class: {
            root: 'bg-transparent',
            title: 'text-secondary',
            description: 'text-muted'
          }
        },
        {
          variant: 'naked',
          color: 'accent',
          class: {
            root: 'bg-transparent',
            title: 'text-accent',
            description: 'text-muted'
          }
        },
        {
          variant: 'naked',
          color: 'success',
          class: {
            root: 'bg-transparent',
            title: 'text-success',
            description: 'text-muted'
          }
        },
        {
          variant: 'naked',
          color: 'info',
          class: {
            root: 'bg-transparent',
            title: 'text-info',
            description: 'text-muted'
          }
        },
        {
          variant: 'naked',
          color: 'warning',
          class: {
            root: 'bg-transparent',
            title: 'text-warning',
            description: 'text-muted'
          }
        },
        {
          variant: 'naked',
          color: 'error',
          class: {
            root: 'bg-transparent',
            title: 'text-error',
            description: 'text-muted'
          }
        },
        {
          variant: 'solid',
          color: 'neutral',
          class: {
            root: 'bg-inverted',
            title: 'text-inverted',
            description: 'text-dimmed'
          }
        },
        {
          variant: 'outline',
          color: 'neutral',
          class: {
            root: 'bg-default ring ring-default',
            description: 'text-muted'
          }
        },
        {
          variant: 'soft',
          color: 'neutral',
          class: {
            root: 'bg-elevated/50',
            description: 'text-toned'
          }
        },
        {
          variant: 'subtle',
          color: 'neutral',
          class: {
            root: 'bg-elevated/50 ring ring-default',
            description: 'text-toned'
          }
        },
        {
          variant: 'naked',
          color: 'neutral',
          class: {
            description: 'text-muted'
          }
        }
      ],
      defaultVariants: {
        variant: 'naked',
        size: 'md',
        color: 'neutral'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/Empty.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/empty.ts).


# Error

## Uso

O componente Error renderiza um elemento `<main>` que funciona em conjunto com o componente [Header](https://ui.nitro.news/docs/components/header) para criar um layout de altura total que se estende até a altura disponível da viewport.

> \[!TIP]
> See: /docs/getting-started/theme/css-variables#header
>
> O componente Error usa a variável CSS `--ui-header-height` para se posicionar corretamente abaixo do `Header`.

### Erro

Use a prop `error` para exibir uma mensagem de erro.

> \[!NOTE]
> See: https\://nuxt.com/docs/guide/directory-structure/error
>
> Na maioria dos casos, você receberá a prop `error` no seu arquivo `error.vue`.

```vue
<template>
  <UError :error="{
  statusCode: 404,
  statusMessage: 'Page not found',
  message: 'The page you are looking for does not exist.'
}" />
</template>
```

### Ícone `4.8+`

Use a prop `icon` para exibir um ícone acima do código de status.

```vue
<template>
  <UError icon="i-lucide-file-x" :error="{
  statusCode: 404,
  statusMessage: 'Page not found',
  message: 'The page you are looking for does not exist.'
}" />
</template>
```

Use o slot `#leading` para exibir um elemento personalizado, como um logo.

```vue
<template>
  <UError :error="{
  statusCode: 404,
  statusMessage: 'Page not found',
  message: 'The page you are looking for does not exist.'
}">
    <template #leading>
      <img src="https://github.com/nuxt.png" alt="Logo" class="size-10 rounded-full">
    </template></UError>
</template>
```

### Limpar

Use a prop `clear` para personalizar ou ocultar o botão de limpar (com o valor `false`).

Você pode passar qualquer propriedade do componente [Button](https://ui.nitro.news/docs/components/button) para personalizá-lo.

```vue
<template>
  <UError :clear="{
  color: 'neutral',
  size: 'xl',
  icon: 'i-lucide-arrow-left',
  class: 'rounded-full'
}" :error="{
  statusCode: 404,
  statusMessage: 'Page not found',
  message: 'The page you are looking for does not exist.'
}" />
</template>
```

### Redirecionamento

Use a prop `redirect` para redirecionar o usuário para uma página diferente quando o botão de limpar é clicado. O padrão é `/`.

```vue
<template>
  <UError redirect="/docs/getting-started" :error="{
  statusCode: 404,
  statusMessage: 'Page not found',
  message: 'The page you are looking for does not exist.'
}" />
</template>
```

## Exemplos

### Dentro de `error.vue`

Use o componente Error no seu `error.vue`:

```vue [error.vue] {13}
<script setup lang="ts">
import type { NuxtError } from '#app'

const props = defineProps<{
  error: NuxtError
}>()
</script>

<template>
  <NApp>
    <NHeader />

    <NError :error="error" />

    <NFooter />
  </NApp>
</template>
```

> \[!TIP]
>
> Você pode querer replicar o código do seu `app.vue` dentro do seu arquivo `error.vue` para ter o mesmo layout e recursos; aqui está um exemplo: <https://gitlab.nitro.news/nitro/ui/-/blob/main/docs/app/error.vue>{rel="&#x22;nofollow&#x22;"}

> \[!NOTE]
>
> Você pode ler mais sobre como tratar erros na [documentação do Nuxt](https://nuxt.com/docs/getting-started/error-handling#error-page){rel="&#x22;nofollow&#x22;"}, mas ao usar `nuxt generate` é recomendado adicionar `fatal: true` dentro da sua chamada de `createError` para garantir que a página de erro seja exibida:
>
> ```vue [pages/[...slug\\].vue]
> <script setup lang="ts">
> const route = useRoute()
>
> const { data: page } = await useAsyncData(route.path, () => {
>   return queryCollection('docs').path(route.path).first()
> })
> if (!page.value) {
>   throw createError({ statusCode: 404, statusMessage: 'Page not found', fatal: true })
> }
> </script>
> ```

## API

### Props

```ts
/**
 * Props for the Error component
 */
interface ErrorProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  error?: Partial<NuxtError<unknown> & { message: string; }> | undefined;
  /**
   * The URL to redirect to when the error is cleared.
   * @default "\"/\""
   */
  redirect?: string | undefined;
  /**
   * Display a button to clear the error in the links slot.
   * `{ size: 'lg', color: 'primary', variant: 'solid', label: 'Back to home' }`{lang="ts-type"}
   * @default "true"
   */
  clear?: boolean | ButtonProps | undefined;
  ui?: { root?: SlotClass; statusCode?: SlotClass; statusMessage?: SlotClass; message?: SlotClass; links?: SlotClass; } | undefined;
}
```

### Slots

```ts
/**
 * Slots for the Error component
 */
interface ErrorSlots {
  default(): any;
  statusCode(): any;
  statusMessage(): any;
  message(): any;
  links(): any;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    error: {
      slots: {
        root: 'min-h-[calc(100vh-var(--ui-header-height))] flex flex-col items-center justify-center text-center',
        statusCode: 'text-base font-semibold text-primary',
        statusMessage: 'mt-2 text-4xl sm:text-5xl font-bold text-highlighted text-balance',
        message: 'mt-4 text-lg text-muted text-balance',
        links: 'mt-8 flex items-center justify-center gap-6'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/Error.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/error.ts).


# FieldGroup

## Uso

Envolva vários [Button](https://ui.nitro.news/components/button) dentro de um FieldGroup para agrupá-los.

```vue
<template>
  <UFieldGroup>
    <NButton color="neutral" variant="subtle" label="Button" />
    <NButton color="neutral" variant="outline" icon="i-lucide-chevron-down" />
  </UFieldGroup>
</template>
```

### Tamanho

Use a prop `size` para alterar o tamanho de todos os botões.

```vue
<template>
  <UFieldGroup size="xl">
    <NButton color="neutral" variant="subtle" label="Button" />
    <NButton color="neutral" variant="outline" icon="i-lucide-chevron-down" />
  </UFieldGroup>
</template>
```

### Orientação

Use a prop `orientation` para alterar a orientação dos botões. O padrão é `horizontal`.

```vue
<template>
  <UFieldGroup orientation="vertical">
    <NButton color="neutral" variant="subtle" label="Submit" />
    <NButton color="neutral" variant="outline" label="Cancel" />
  </UFieldGroup>
</template>
```

## Exemplos

### Com input

Você pode usar componentes como [Input](https://ui.nitro.news/components/input), [InputMenu](https://ui.nitro.news/components/input-menu), [Select](https://ui.nitro.news/components/select) [SelectMenu](https://ui.nitro.news/components/select-menu), etc. dentro de um field group.

```vue
<template>
  <UFieldGroup>
    <NInput color="neutral" variant="outline" placeholder="Enter token" />

    <NButton color="neutral" variant="subtle" icon="i-lucide-clipboard" />
  </UFieldGroup>
</template>
```

### Com tooltip

Você pode usar um [Tooltip](https://ui.nitro.news/components/tooltip) dentro de um field group.

:component-example{name="field-group-tooltip-example"}

### Com dropdown menu

Você pode usar um [DropdownMenu](https://ui.nitro.news/components/dropdown-menu) dentro de um field group.

:component-example{name="field-group-dropdown-example"}

### Com badge

Você pode usar um [Badge](https://ui.nitro.news/components/badge) dentro de um field group.

:component-example{name="field-group-badge-example"}

## API

### Props

```ts
/**
 * Props for the FieldGroup component
 */
interface FieldGroupProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  size?: "md" | "xs" | "sm" | "lg" | "xl" | undefined;
  /**
   * The orientation the buttons are laid out.
   * @default "\"horizontal\""
   */
  orientation?: "horizontal" | "vertical" | undefined;
  ui?: {} | undefined;
}
```

### Slots

```ts
/**
 * Slots for the FieldGroup component
 */
interface FieldGroupSlots {
  default(): any;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    fieldGroup: {
      base: 'relative',
      variants: {
        size: {
          xs: '',
          sm: '',
          md: '',
          lg: '',
          xl: ''
        },
        orientation: {
          horizontal: 'inline-flex -space-x-px',
          vertical: 'flex flex-col -space-y-px'
        }
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/FieldGroup.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/field-group.ts).


# FileUpload

## Uso

Use a diretiva `v-model` para controlar o valor do FileUpload.

```vue
<script setup lang="ts">
const value = ref(null)
</script>

<template>
  <UFileUpload class="w-96 min-h-48" />
</template>
```

### Múltiplo

Use a prop `multiple` para permitir que vários arquivos sejam selecionados.

```vue
<template>
  <UFileUpload multiple class="w-96 min-h-48" />
</template>
```

### Zona de soltar

Use a prop `dropzone` para habilitar/desabilitar a área de soltar. O padrão é `true`.

```vue
<template>
  <UFileUpload :dropzone="false" class="w-96 min-h-48" />
</template>
```

### Interativo

Use a prop `interactive` para habilitar/desabilitar a área clicável. O padrão é `true`.

> \[!TIP]
> See: #with-files-bottom-slot
>
> Isso pode ser útil ao adicionar um componente `Button` no slot `#actions`.

```vue
<template>
  <UFileUpload :interactive="false" class="w-96 min-h-48" />
</template>
```

### Aceitar

Use a prop `accept` para especificar os tipos de arquivo permitidos no input. Forneça uma lista separada por vírgulas de [tipos MIME](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/MIME_types){rel="&#x22;nofollow&#x22;"} ou extensões de arquivo (ex.: `image/png,application/pdf,.jpg`). O padrão é `*` (todos os tipos de arquivo).

```vue
<template>
  <UFileUpload accept="image/*" class="w-96 min-h-48" />
</template>
```

### Label

Use a prop `label` para definir o rótulo do FileUpload.

```vue
<template>
  <UFileUpload label="Drop your image here" class="w-96 min-h-48" />
</template>
```

### Descrição

Use a prop `description` para definir a descrição do FileUpload.

```vue
<template>
  <UFileUpload label="Drop your image here" description="SVG, PNG, JPG or GIF (max. 2MB)" class="w-96 min-h-48" />
</template>
```

### Ícone

Use a prop `icon` para definir o ícone do FileUpload. O padrão é `i-lucide-upload`.

```vue
<template>
  <UFileUpload icon="i-lucide-image" label="Drop your image here" description="SVG, PNG, JPG or GIF (max. 2MB)" class="w-96 min-h-48" />
</template>
```

**Nuxt:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/nuxt#theme
>
> Você pode personalizar esse ícone globalmente no seu `app.config.ts` na chave `ui.icons.upload`.

**Vue:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/vue#theme
>
> Você pode personalizar esse ícone globalmente no seu `vite.config.ts` na chave `ui.icons.upload`.

### Cor

Use a prop `color` para alterar a cor do FileUpload.

```vue
<template>
  <UFileUpload color="neutral" highlight label="Drop your image here" description="SVG, PNG, JPG or GIF (max. 2MB)" class="w-96 min-h-48" />
</template>
```

> \[!NOTE]
>
> A prop `highlight` é usada aqui para mostrar o estado de foco. Ela é usada internamente quando ocorre um erro de validação.

### Variante

Use a prop `variant` para alterar a variante do FileUpload.

```vue
<template>
  <UFileUpload variant="button" />
</template>
```

### Tamanho

Use a prop `size` para alterar o tamanho do FileUpload.

```vue
<template>
  <UFileUpload size="xl" variant="area" label="Drop your image here" description="SVG, PNG, JPG or GIF (max. 2MB)" />
</template>
```

### Layout

Use a prop `layout` para alterar como os arquivos são exibidos no FileUpload. O padrão é `grid`.

> \[!WARNING]
>
> Esta prop só funciona quando `variant` é `area`.

```vue
<template>
  <UFileUpload layout="list" multiple label="Drop your images here" description="SVG, PNG, JPG or GIF (max. 2MB)" class="w-96" :ui="{
  base: 'min-h-48'
}" />
</template>
```

### Posição

Use a prop `position` para alterar a posição dos arquivos no FileUpload. O padrão é `outside`.

> \[!WARNING]
>
> Esta prop só funciona quando `variant` é `area` e quando `layout` é `list`.

```vue
<template>
  <UFileUpload position="inside" layout="list" multiple label="Drop your images here" description="SVG, PNG, JPG or GIF (max. 2MB)" class="w-96" :ui="{
  base: 'min-h-48'
}" />
</template>
```

## Exemplos

### Com validação de Form

Você pode usar o FileUpload dentro dos componentes [Form](https://ui.nitro.news/docs/components/form) e [FormField](https://ui.nitro.news/docs/components/form-field) para lidar com validação e tratamento de erros.

::component-example
---
collapse: true
prettier: true
name: file-upload-form-validation-example
---
::

### Com slot padrão

Você pode usar o slot padrão para criar o seu próprio componente FileUpload.

::component-example{collapse prettier name="file-upload-default-slot-example"}
::

### Com slot files-bottom

Você pode usar o slot `files-bottom` para adicionar um [Button](https://ui.nitro.news/docs/components/button) abaixo da lista de arquivos para remover todos os arquivos, por exemplo.

::component-example
---
collapse: true
prettier: true
name: file-upload-files-bottom-slot-example
---
::

> \[!NOTE]
> See: #interactive
>
> A prop `interactive` é definida como `false` neste exemplo para evitar a área clicável padrão.

### Com slot files-top

Você pode usar o slot `files-top` para adicionar um [Button](https://ui.nitro.news/docs/components/button) acima da lista de arquivos para adicionar novos arquivos, por exemplo.

::component-example{collapse prettier name="file-upload-files-top-slot-example"}
::

## API

### Props

```ts
/**
 * Props for the FileUpload component
 */
interface FileUploadProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  id?: string | undefined;
  name?: string | undefined;
  /**
   * The icon to display. Set to `false` to hide the icon.
   */
  icon?: any;
  label?: string | undefined;
  description?: string | undefined;
  color?: "primary" | "secondary" | "accent" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
  /**
   * The `button` variant is only available when `multiple` is `false`.
   */
  variant?: "button" | "area" | undefined;
  size?: "xs" | "sm" | "md" | "lg" | "xl" | undefined;
  /**
   * The layout of how files are displayed.
   * Only works when `variant` is `area`.
   * @default "\"grid\""
   */
  layout?: "list" | "grid" | undefined;
  /**
   * The position of the files.
   * Only works when `variant` is `area` and when `layout` is `list`.
   * @default "\"outside\""
   */
  position?: "inside" | "outside" | undefined;
  /**
   * Highlight the ring color like a focus state.
   */
  highlight?: boolean | undefined;
  /**
   * Specifies the allowed file types for the input. Provide a comma-separated list of MIME types or file extensions (e.g., "image/png,application/pdf,.jpg").
   * @default "\"*\""
   */
  accept?: string | undefined;
  /**
   * @default "false as never"
   */
  multiple?: M | undefined;
  /**
   * Reset the file input when the dialog is opened.
   * @default "false"
   */
  reset?: boolean | undefined;
  /**
   * Create a zone that allows the user to drop files onto it.
   * @default "true"
   */
  dropzone?: boolean | undefined;
  /**
   * Make the dropzone interactive when the user is clicking on it.
   * @default "true"
   */
  interactive?: boolean | undefined;
  required?: boolean | undefined;
  disabled?: boolean | undefined;
  /**
   * The icon to display for the file.
   */
  fileIcon?: any;
  /**
   * Preview the file (currently only `<img>` is rendered)
   * When set false, only `fileIcon` is displayed
   * @default "true"
   */
  fileImage?: boolean | undefined;
  /**
   * Configure the delete button for the file.
   * When `layout` is `grid`, the default is `{ color: 'neutral', variant: 'solid', size: 'xs' }`{lang="ts-type"}
   * When `layout` is `list`, the default is `{ color: 'neutral', variant: 'link' }`{lang="ts-type"}
   * @default "true"
   */
  fileDelete?: boolean | Omit<ButtonProps, LinkPropsKeys> | undefined;
  /**
   * The icon displayed to delete a file.
   */
  fileDeleteIcon?: any;
  /**
   * Show the file preview/list after upload.
   * @default "true"
   */
  preview?: boolean | undefined;
  ui?: { root?: SlotClass; base?: SlotClass; wrapper?: SlotClass; icon?: SlotClass; avatar?: SlotClass; label?: SlotClass; description?: SlotClass; actions?: SlotClass; files?: SlotClass; file?: SlotClass; fileLeadingAvatar?: SlotClass; fileWrapper?: SlotClass; fileName?: SlotClass; fileSize?: SlotClass; fileTrailingButton?: SlotClass; } | undefined;
  form?: string | undefined;
  formaction?: string | undefined;
  formenctype?: string | undefined;
  formmethod?: string | undefined;
  formnovalidate?: Booleanish | undefined;
  formtarget?: string | undefined;
  modelValue?: (M extends true ? File[] : File) | null | undefined;
}
```

> \[!NOTE]
> See: https\://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#attributes
>
> Este componente também suporta todos os atributos HTML nativos de `<input>`.

### Slots

```ts
/**
 * Slots for the FileUpload component
 */
interface FileUploadSlots {
  default(): any;
  leading(): any;
  label(): any;
  description(): any;
  actions(): any;
  files(): any;
  files-top(): any;
  files-bottom(): any;
  file(): any;
  file-leading(): any;
  file-name(): any;
  file-size(): any;
  file-trailing(): any;
}
```

### Emits

```ts
/**
 * Emitted events for the FileUpload component
 */
interface FileUploadEmits {
  change: (payload: [event: Event]) => void;
  update:modelValue: (payload: [value: (M extends true ? File[] : File) | null | undefined]) => void;
}
```

### Expose

Ao acessar o componente por meio de um template ref, você pode usar o seguinte:

| Name                                                                                                                              | Type                                                                                                                                               |
| --------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `inputRef`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"}    | `Ref<HTMLInputElement | null>`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} |
| `dropzoneRef`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | `Ref<HTMLDivElement | null>`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"}   |

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    fileUpload: {
      slots: {
        root: 'relative flex flex-col',
        base: [
          'w-full flex-1 bg-default border border-default flex flex-col gap-2 items-stretch justify-center rounded-lg focus-visible:outline-2',
          'transition-[background]'
        ],
        wrapper: 'flex flex-col items-center justify-center text-center',
        icon: 'shrink-0',
        avatar: 'shrink-0',
        label: 'font-medium text-default mt-2',
        description: 'text-muted mt-1',
        actions: 'flex flex-wrap gap-1.5 shrink-0 mt-4',
        files: '',
        file: 'relative',
        fileLeadingAvatar: 'shrink-0',
        fileWrapper: 'flex flex-col min-w-0',
        fileName: 'text-default truncate',
        fileSize: 'text-muted truncate',
        fileTrailingButton: ''
      },
      variants: {
        color: {
          primary: '',
          secondary: '',
          accent: '',
          success: '',
          info: '',
          warning: '',
          error: '',
          neutral: ''
        },
        variant: {
          area: {
            wrapper: 'px-4 py-3',
            base: 'p-4'
          },
          button: {}
        },
        size: {
          xs: {
            base: 'text-xs',
            icon: 'size-4',
            file: 'text-xs px-2 py-1 gap-1',
            fileWrapper: 'flex-row gap-1'
          },
          sm: {
            base: 'text-xs',
            icon: 'size-4',
            file: 'text-xs px-2.5 py-1.5 gap-1.5',
            fileWrapper: 'flex-row gap-1'
          },
          md: {
            base: 'text-sm',
            icon: 'size-5',
            file: 'text-xs px-2.5 py-1.5 gap-1.5'
          },
          lg: {
            base: 'text-sm',
            icon: 'size-5',
            file: 'text-sm px-3 py-2 gap-2',
            fileSize: 'text-xs'
          },
          xl: {
            base: 'text-base',
            icon: 'size-6',
            file: 'text-sm px-3 py-2 gap-2'
          }
        },
        layout: {
          list: {
            root: 'gap-2 items-start',
            files: 'flex flex-col w-full gap-2',
            file: 'min-w-0 flex items-center border border-default rounded-md w-full',
            fileTrailingButton: 'ms-auto'
          },
          grid: {
            fileWrapper: 'hidden',
            fileLeadingAvatar: 'size-full rounded-lg',
            fileTrailingButton: 'absolute -top-1.5 -end-1.5 p-0 rounded-full border-2 border-bg'
          }
        },
        position: {
          inside: '',
          outside: ''
        },
        dropzone: {
          true: 'border-dashed data-[dragging=true]:bg-elevated/25'
        },
        interactive: {
          true: ''
        },
        highlight: {
          true: ''
        },
        multiple: {
          true: ''
        },
        disabled: {
          true: 'cursor-not-allowed opacity-75'
        }
      },
      compoundVariants: [
        {
          color: 'primary',
          class: 'focus-visible:outline-primary'
        },
        {
          color: 'secondary',
          class: 'focus-visible:outline-secondary'
        },
        {
          color: 'accent',
          class: 'focus-visible:outline-accent'
        },
        {
          color: 'success',
          class: 'focus-visible:outline-success'
        },
        {
          color: 'info',
          class: 'focus-visible:outline-info'
        },
        {
          color: 'warning',
          class: 'focus-visible:outline-warning'
        },
        {
          color: 'error',
          class: 'focus-visible:outline-error'
        },
        {
          color: 'primary',
          highlight: true,
          class: 'border-primary'
        },
        {
          color: 'secondary',
          highlight: true,
          class: 'border-secondary'
        },
        {
          color: 'accent',
          highlight: true,
          class: 'border-accent'
        },
        {
          color: 'success',
          highlight: true,
          class: 'border-success'
        },
        {
          color: 'info',
          highlight: true,
          class: 'border-info'
        },
        {
          color: 'warning',
          highlight: true,
          class: 'border-warning'
        },
        {
          color: 'error',
          highlight: true,
          class: 'border-error'
        },
        {
          color: 'neutral',
          class: 'focus-visible:outline-inverted'
        },
        {
          color: 'neutral',
          highlight: true,
          class: 'border-inverted'
        },
        {
          size: 'xs',
          layout: 'list',
          class: {
            fileTrailingButton: '-me-1'
          }
        },
        {
          size: 'sm',
          layout: 'list',
          class: {
            fileTrailingButton: '-me-1.5'
          }
        },
        {
          size: 'md',
          layout: 'list',
          class: {
            fileTrailingButton: '-me-1.5'
          }
        },
        {
          size: 'lg',
          layout: 'list',
          class: {
            fileTrailingButton: '-me-2'
          }
        },
        {
          size: 'xl',
          layout: 'list',
          class: {
            fileTrailingButton: '-me-2'
          }
        },
        {
          variant: 'button',
          size: 'xs',
          class: {
            base: 'p-1'
          }
        },
        {
          variant: 'button',
          size: 'sm',
          class: {
            base: 'p-1.5'
          }
        },
        {
          variant: 'button',
          size: 'md',
          class: {
            base: 'p-1.5'
          }
        },
        {
          variant: 'button',
          size: 'lg',
          class: {
            base: 'p-2'
          }
        },
        {
          variant: 'button',
          size: 'xl',
          class: {
            base: 'p-2'
          }
        },
        {
          layout: 'grid',
          multiple: true,
          class: {
            files: 'grid grid-cols-2 md:grid-cols-3 gap-4 w-full',
            file: 'p-0 aspect-square'
          }
        },
        {
          layout: 'grid',
          multiple: false,
          class: {
            file: 'absolute inset-0 p-0'
          }
        },
        {
          interactive: true,
          disabled: false,
          class: 'hover:bg-elevated/25'
        }
      ],
      defaultVariants: {
        color: 'primary',
        variant: 'area',
        size: 'md'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/FileUpload.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/file-upload.ts).


# Footer

## Uso

O componente Footer renderiza um elemento `<footer>`.

Use os slots `left`, `default` e `right` para personalizar o footer.

::component-example
---
collapse: true
prettier: true
props:
  class: w-full
class: "!p-0"
name: footer-example
---
::

> \[!NOTE]
>
> Neste exemplo, usamos o componente [NavigationMenu](https://ui.nitro.news/docs/components/navigation-menu) para renderizar os links do footer ao centro.

> \[!TIP]
> See: /docs/components/footer-columns
>
> Você pode usar o componente `FooterColumns` para exibir uma lista de links dentro do slot `top`.

## Exemplos

### Dentro de `app.vue`

Use o componente Footer no seu `app.vue` ou em um layout:

```vue [app.vue] {32-67}
<script setup lang="ts">
import type { NavigationMenuItem } from '@nitro/ui'

const items: NavigationMenuItem[] = [{
  label: 'Figma Kit',
  to: 'https://go.nuxt.com/figma-ui',
  target: '_blank'
}, {
  label: 'Playground',
  to: 'https://stackblitz.com/edit/nuxt-ui',
  target: '_blank'
}, {
  label: 'Releases',
  to: 'https://github.com/nuxt/ui/releases',
  target: '_blank'
}]
</script>

<template>
  <NApp>
    <NHeader />

    <NMain>
      <NuxtLayout>
        <NuxtPage />
      </NuxtLayout>
    </NMain>

    <NSeparator icon="i-simple-icons-nuxtdotjs" type="dashed" class="h-px" />

    <NFooter>
      <template #left>
        <p class="text-muted text-sm">
          Copyright © {{ new Date().getFullYear() }}
        </p>
      </template>

      <NNavigationMenu :items="items" variant="link" />

      <template #right>
        <NButton
          icon="i-simple-icons-discord"
          color="neutral"
          variant="ghost"
          to="https://go.nuxt.com/discord"
          target="_blank"
          aria-label="Discord"
        />
        <NButton
          icon="i-simple-icons-x"
          color="neutral"
          variant="ghost"
          to="https://go.nuxt.com/x"
          target="_blank"
          aria-label="X"
        />
        <NButton
          icon="i-simple-icons-github"
          color="neutral"
          variant="ghost"
          to="https://github.com/nuxt/nuxt"
          target="_blank"
          aria-label="GitHub"
        />
      </template>
    </NFooter>
  </NApp>
</template>
```

> \[!NOTE]
>
> Neste exemplo, usamos o componente [Separator](https://ui.nitro.news/docs/components/separator) para adicionar uma borda acima do footer.

## API

### Props

```ts
/**
 * Props for the Footer component
 */
interface FooterProps {
  /**
   * The element or component this component should render as.
   * @default "\"footer\""
   */
  as?: any;
  ui?: { root?: SlotClass; top?: SlotClass; bottom?: SlotClass; container?: SlotClass; left?: SlotClass; center?: SlotClass; right?: SlotClass; } | undefined;
}
```

### Slots

```ts
/**
 * Slots for the Footer component
 */
interface FooterSlots {
  left(): any;
  default(): any;
  right(): any;
  top(): any;
  bottom(): any;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    footer: {
      slots: {
        root: '',
        top: 'py-8 lg:py-12',
        bottom: 'py-8 lg:py-12',
        container: 'py-8 lg:py-4 lg:flex lg:items-center lg:justify-between lg:gap-x-3',
        left: 'flex items-center justify-center lg:justify-start lg:flex-1 gap-x-1.5 mt-3 lg:mt-0 lg:order-1',
        center: 'mt-3 lg:mt-0 lg:order-2 flex items-center justify-center',
        right: 'lg:flex-1 flex items-center justify-center lg:justify-end gap-x-1.5 lg:order-3'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/Footer.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/footer.ts).


# FooterColumns

## Uso

O componente FooterColumns renderiza uma lista de colunas para exibir no seu Footer.

Use-o no slot `top` do componente [Footer](https://ui.nitro.news/docs/components/footer):

```vue {3-7}
<template>
  <NFooter>
    <template #top>
      <NContainer>
        <NFooterColumns />
      </NContainer>
    </template>
  </NFooter>
</template>
```

### Colunas

Use a prop `columns` como um array de objetos com as seguintes propriedades:

- `label: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `children?: FooterColumnLink[]`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Cada coluna contém um array `children` de objetos que definem os links. Cada link pode ter as seguintes propriedades:

- `label?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `icon?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `class?: any`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `ui?: { item?: ClassNameValue, link?: ClassNameValue, linkLabel?: ClassNameValue, linkLabelExternalIcon?: ClassNameValue, linkLeadingIcon?: ClassNameValue }`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Você pode passar qualquer propriedade do componente [Link](https://ui.nitro.news/docs/components/link#props), como `to`, `target`, etc.

::component-example
---
prettier: true
props:
  class: w-full
class: p-8
name: footer-columns-example
---
::

## API

### Props

```ts
/**
 * Props for the FooterColumns component
 */
interface FooterColumnsProps {
  /**
   * The element or component this component should render as.
   * @default "\"nav\""
   */
  as?: any;
  columns?: FooterColumn<T>[] | undefined;
  ui?: { root?: SlotClass; left?: SlotClass; center?: SlotClass; right?: SlotClass; label?: SlotClass; list?: SlotClass; item?: SlotClass; link?: SlotClass; linkLeadingIcon?: SlotClass; linkLabel?: SlotClass; linkLabelExternalIcon?: SlotClass; } | undefined;
}
```

### Slots

```ts
/**
 * Slots for the FooterColumns component
 */
interface FooterColumnsSlots {
  left(): any;
  default(): any;
  right(): any;
  column-label(): any;
  link(): any;
  link-leading(): any;
  link-label(): any;
  link-trailing(): any;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    footerColumns: {
      slots: {
        root: 'xl:grid xl:grid-cols-3 xl:gap-8',
        left: 'mb-10 xl:mb-0',
        center: 'flex flex-col lg:grid grid-flow-col auto-cols-fr gap-8 xl:col-span-2',
        right: 'mt-10 xl:mt-0',
        label: 'text-sm font-semibold',
        list: 'mt-6 space-y-4',
        item: 'relative',
        link: 'group text-sm flex items-center gap-1.5 rounded-sm outline-primary/25 focus-visible:outline-3',
        linkLeadingIcon: 'size-5 shrink-0',
        linkLabel: 'truncate',
        linkLabelExternalIcon: 'size-3 absolute top-0 text-dimmed inline-block'
      },
      variants: {
        active: {
          true: {
            link: 'text-primary font-medium'
          },
          false: {
            link: [
              'text-muted hover:text-default',
              'transition-colors'
            ]
          }
        }
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/FooterColumns.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/footer-columns.ts).


# Form

## Uso

Use o componente Form para validar os dados do formulário usando qualquer biblioteca de validação que suporte o [Standard Schema](https://github.com/standard-schema/standard-schema){rel="&#x22;nofollow&#x22;"}, como [Valibot](https://github.com/fabian-hiller/valibot){rel="&#x22;nofollow&#x22;"}, [Zod](https://github.com/colinhacks/zod){rel="&#x22;nofollow&#x22;"}, [Regle](https://github.com/victorgarciaesgi/regle){rel="&#x22;nofollow&#x22;"}, [Yup](https://github.com/jquense/yup){rel="&#x22;nofollow&#x22;"}, [Joi](https://github.com/hapijs/joi){rel="&#x22;nofollow&#x22;"} ou [Superstruct](https://github.com/ianstormtaylor/superstruct){rel="&#x22;nofollow&#x22;"}, ou a sua própria lógica de validação.

Ele funciona com o componente [FormField](https://ui.nitro.news/docs/components/form-field) para exibir mensagens de erro ao redor dos elementos do formulário automaticamente.

### Validação por schema

Ele exige duas props:

- `state` - a reactive object holding the form's state.
- `schema` - any [Standard Schema](https://github.com/standard-schema/standard-schema){rel="&#x22;nofollow&#x22;"} or [Superstruct](https://github.com/ianstormtaylor/superstruct){rel="&#x22;nofollow&#x22;"}.

> \[!WARNING]
>
> **No validation library is included** by default, ensure you **install the one you need**.

### Validação personalizada

Use a prop `validate` para aplicar a sua própria lógica de validação.

A função de validação precisa retornar uma lista de erros com os seguintes atributos:

- `message` - the error message to display.
- `name` - the `name` of the `FormField` to send the error to.

> \[!TIP]
>
> Ela pode ser usada junto com a prop `schema` para lidar com casos de uso complexos.

::component-example
---
props:
  class: w-60
name: form-example-basic
---
::

### Relato de erros

Os erros são associados ao [FormField](https://ui.nitro.news/docs/components/form-field) correspondente por meio da prop `name` dele. Um erro no campo `email` é exibido por `<FormField name="email">`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"}.

Campos aninhados são associados usando notação de ponto. Um schema como `{ user: z.object({ email: z.string() }) }`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} será aplicado a `<FormField name="user.email">`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"}.

> \[!WARNING]
>
> Os erros em itens de array incluem o índice no nome (ex.: `tags.0`, `tags.1`) e não corresponderão a `<FormField name="tags">`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="vue"} apenas pelo `name`. Use a prop `error-pattern` com uma expressão regular como `/^tags\..+/`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts"} para capturá-los. Isso é especialmente útil para componentes como o [InputTags](https://ui.nitro.news/docs/components/input-tags).

::component-example
---
props:
  class: w-60
name: form-example-error-pattern
---
::

### Eventos de input

O componente Form dispara a validação automaticamente quando um input emite um evento `input`, `change` ou `blur`.

- Validation on `input` occurs **as you type**.
- Validation on `change` occurs when you **commit to a value**.
- Validation on `blur` happens when an input **loses focus**.

Você pode controlar quando a validação acontece usando a prop `validate-on`.

> \[!TIP]
>
> O formulário sempre valida no envio.

::component-example
---
options:
  - name: validate-on
    label: validate-on
    items:
      - input
      - change
      - blur
    default:
      - input
      - change
      - blur
    multiple: true
source: false
label: Default
name: form-example-elements
---
::

> \[!TIP]
>
> Você pode usar o composable `useFormField` para implementar isso dentro dos seus próprios componentes.

### Evento de erro

Você pode escutar o evento `@error` para tratar os erros. Esse evento é disparado quando o formulário é enviado e contém um array de objetos `FormError` com os seguintes campos:

- `id` - the input's `id`.
- `name` - the `name` of the `FormField`
- `message` - the error message to display.

Aqui está um exemplo que foca o primeiro elemento de input com erro após o envio do formulário:

::component-example
---
collapse: true
props:
  class: w-60
name: form-example-on-error
---
::

### Validação HTML5 `4.5+`

Ao chamar `form.submit()` programaticamente, o componente Form dispara automaticamente a validação nativa HTML5 antes do envio.

> \[!NOTE]
>
> Isso é particularmente útil quando o botão de envio está fora do elemento de formulário, como no rodapé de um modal.

::component-example
---
props:
  class: w-60
name: form-example-html5-validation
---
::

### Formulários aninhados

Use a prop `nested` para aninhar vários componentes Form e vincular as funções de validação deles. Nesse caso, validar o formulário pai valida automaticamente todos os outros formulários dentro dele.

Formulários aninhados herdam diretamente o estado do pai, então você não precisa definir um estado separado para eles. Você pode usar a prop `name` para mirar um atributo aninhado dentro do estado do pai.

Ela pode ser usada para adicionar campos dinamicamente com base na entrada do usuário:

::component-example{collapse name="form-example-nested"}
::

Ou para validar inputs de lista:

::component-example{collapse name="form-example-nested-list"}
::

## API

### Props

```ts
/**
 * Props for the Form component
 */
interface FormProps {
  id?: string | number | undefined;
  /**
   * Schema to validate the form state. Supports Standard Schema objects, Yup, Joi, and Superstructs.
   */
  schema?: S | undefined;
  /**
   * An object representing the current state of the form.
   */
  state?: (N extends false ? Partial<InferInput<S>> : never) | undefined;
  /**
   * Custom validation function to validate the form state.
   */
  validate?: ((state: Partial<InferInput<S>>) => FormError<string>[] | Promise<FormError<string>[]>) | undefined;
  /**
   * The list of input events that trigger the form validation.
   */
  validateOn?: FormInputEvents[] | undefined;
  /**
   * Disable all inputs inside the form.
   */
  disabled?: boolean | undefined;
  /**
   * The `name` attribute of the form element.
   * For nested forms (`nested` is true), this is also used as the path of the form's state within its parent form.
   */
  name?: string | undefined;
  /**
   * Delay in milliseconds before validating the form on input events.
   * @default "300"
   */
  validateOnInputDelay?: number | undefined;
  /**
   * If true, applies schema transformations on submit.
   * @default "true as T"
   */
  transform?: T | undefined;
  /**
   * If true, this form will attach to its parent Form and validate at the same time.
   */
  nested?: N | undefined;
  /**
   * When `true`, all form elements will be disabled on `@submit` event.
   * This will cause any focused input elements to lose their focus state.
   * @default "true"
   */
  loadingAuto?: boolean | undefined;
  ui?: { base?: any; } | undefined;
  acceptcharset?: string | undefined;
  action?: string | undefined;
  autocomplete?: string | undefined;
  enctype?: string | undefined;
  method?: string | undefined;
  novalidate?: Booleanish | undefined;
  target?: string | undefined;
}
```

> \[!NOTE]
> See: https\://developer.mozilla.org/en-US/docs/Web/HTML/Element/form#attributes
>
> Este componente também suporta todos os atributos HTML nativos de `<form>`.

### Slots

```ts
/**
 * Slots for the Form component
 */
interface FormSlots {
  default(): any;
}
```

### Emits

```ts
/**
 * Emitted events for the Form component
 */
interface FormEmits {
  submit: (payload: [event: FormSubmitEvent<FormData<S, T>>]) => void;
  error: (payload: [event: FormErrorEvent]) => void;
}
```

### Expose

Você pode acessar a instância tipada do componente usando [`useTemplateRef`](https://vuejs.org/api/composition-api-helpers.html#usetemplateref){rel="&#x22;nofollow&#x22;"}.

```vue
<script setup lang="ts">
const form = useTemplateRef('form')
</script>

<template>
  <NForm ref="form" />
</template>
```

Isso dará a você acesso ao seguinte:

| Name                                                                                                                                                                                                                            | Type                                                                                                                                                                                                                                                            |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `submit()`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"}                                                                                                  | `Promise<void>`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} :br Triggers form submission with HTML5 validation.                                                                         |
| `validate(opts: { name?: keyof T | (keyof T)[], silent?: boolean, nested?: boolean, transform?: boolean })`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | `Promise<T>`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} :br Triggers form validation. Will raise any errors unless `opts.silent` is set to true.                                       |
| `clear(path?: keyof T | RegExp)`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"}                                                                            | `void` :br Clears form errors associated with a specific path. If no path is provided, clears all form errors.                                                                                                                                                  |
| `getErrors(path?: keyof T | RegExp)`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"}                                                                        | `FormErrorWithId[]`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} :br Retrieves form errors associated with a specific path. If no path is provided, returns all form errors.             |
| `setErrors(errors: FormError[], name?: keyof T | RegExp)`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"}                                                   | `void` :br Sets form errors for a given path. If no path is provided, overrides all errors.                                                                                                                                                                     |
| `errors`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"}                                                                                                    | `Ref<FormErrorWithId[]>`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} :br A reference to the array containing validation errors. Use this to access or manipulate the error information. |
| `disabled`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"}                                                                                                  | `Ref<boolean>`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"}                                                                                                                              |
| `dirty`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"}                                                                                                     | `Ref<boolean>`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} `true` if at least one form field has been updated by the user.                                                              |
| `dirtyFields`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"}                                                                                               | `ReadonlySet<DeepReadonly<keyof T>>`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} Tracks fields that have been modified by the user.                                                     |
| `touchedFields`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"}                                                                                             | `ReadonlySet<DeepReadonly<keyof T>>`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} Tracks fields that the user interacted with.                                                           |
| `blurredFields`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"}                                                                                             | `ReadonlySet<DeepReadonly<keyof T>>`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} Tracks fields blurred by the user.                                                                     |

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    form: {
      base: ''
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/Form.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/form.ts).


# FormField

## Uso

Envolva qualquer componente de formulário com um FormField. Usado em um [Form](https://ui.nitro.news/docs/components/form), ele oferece validação e tratamento de erros.

### Label

Use a prop `label` para definir o rótulo do controle de formulário.

```vue
<template>
  <UFormField label="Email">
    <NInput placeholder="Enter your email" />
  </UFormField>
</template>
```

> \[!NOTE]
>
> O atributo `for` do rótulo e o controle de formulário são associados por um `id` único, se não for fornecido.

Ao usar a prop `required`, um asterisco é adicionado ao lado do rótulo.

```vue
<template>
  <UFormField label="Email" required>
    <NInput placeholder="Enter your email" />
  </UFormField>
</template>
```

### Descrição

Use a prop `description` para fornecer informações adicionais abaixo do rótulo.

```vue
<template>
  <UFormField label="Email" description="We'll never share your email with anyone else.">
    <NInput placeholder="Enter your email" class="w-full" />
  </UFormField>
</template>
```

### Dica

Use a prop `hint` para exibir uma mensagem de dica ao lado do rótulo.

```vue
<template>
  <UFormField label="Email" hint="Optional">
    <NInput placeholder="Enter your email" />
  </UFormField>
</template>
```

### Ajuda

Use a prop `help` para exibir uma mensagem de ajuda abaixo do controle de formulário. Quando usada junto com a prop `error`, a prop `error` tem precedência.

```vue
<template>
  <UFormField label="Email" help="Please enter a valid email address.">
    <NInput placeholder="Enter your email" class="w-full" />
  </UFormField>
</template>
```

### Erro

Use a prop `error` para exibir uma mensagem de erro abaixo do controle de formulário. Quando usada junto com a prop `help`, a prop `error` tem precedência.

Quando usada dentro de um [Form](https://ui.nitro.news/docs/components/form), isso é definido automaticamente quando ocorre um erro de validação.

```vue
<template>
  <UFormField label="Email" error="Please enter a valid email address.">
    <NInput placeholder="Enter your email" class="w-full" />
  </UFormField>
</template>
```

> \[!TIP]
> See: /docs/getting-started/theme/design-system#colors
>
> Isso define a `color` como `error` no controle de formulário. Você pode alterar isso globalmente no seu `app.config.ts`.

### Padrão de erro

Use a prop `error-pattern` para associar os erros do formulário a uma expressão regular. Isso é especialmente relevante para componentes com valores de array, como o [InputTags](https://ui.nitro.news/docs/components/input-tags), em que os erros incluem os índices do array no nome (ex.: `tags.0`).

> \[!TIP]
> See: /docs/components/form#error-reporting
>
> Veja um exemplo de uso de `error-pattern` dentro de um Form.

### Tamanho

Use a prop `size` para alterar o tamanho do FormField; o `size` é repassado ao controle de formulário.

```vue
<template>
  <UFormField label="Email" description="We'll never share your email with anyone else." hint="Optional" help="Please enter a valid email address." size="xl">
    <NInput placeholder="Enter your email" class="w-full" />
  </UFormField>
</template>
```

### Orientação `4.3+`

Use a prop `orientation` para alterar o layout do FormField. O padrão é `vertical`.

```vue
<template>
  <UFormField orientation="horizontal" label="Email" help="Please enter a valid email address." class="w-72">
    <NInput placeholder="Enter your email" class="w-full" />
  </UFormField>
</template>
```

## API

### Props

```ts
/**
 * Props for the FormField component
 */
interface FormFieldProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  /**
   * The name of the FormField. Also used to match form errors.
   */
  name?: string | undefined;
  /**
   * A regular expression to match form error names. Useful for components with array values such as InputTags, where errors include array indices in their name (e.g. `tags.0`).
   */
  errorPattern?: RegExp | undefined;
  label?: string | undefined;
  description?: string | undefined;
  help?: string | undefined;
  /**
   * @default "undefined"
   */
  error?: string | boolean | undefined;
  hint?: string | undefined;
  size?: "md" | "xs" | "sm" | "lg" | "xl" | undefined;
  required?: boolean | undefined;
  /**
   * If true, validation on input will be active immediately instead of waiting for a blur event.
   */
  eagerValidation?: boolean | undefined;
  /**
   * Delay in milliseconds before validating the form on input events.
   */
  validateOnInputDelay?: number | undefined;
  /**
   * The orientation of the form field.
   * @default "\"vertical\""
   */
  orientation?: "vertical" | "horizontal" | undefined;
  ui?: { root?: SlotClass; wrapper?: SlotClass; labelWrapper?: SlotClass; label?: SlotClass; container?: SlotClass; description?: SlotClass; error?: SlotClass; hint?: SlotClass; help?: SlotClass; } | undefined;
}
```

### Slots

```ts
/**
 * Slots for the FormField component
 */
interface FormFieldSlots {
  label(): any;
  hint(): any;
  description(): any;
  help(): any;
  error(): any;
  default(): any;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    formField: {
      slots: {
        root: '',
        wrapper: '',
        labelWrapper: 'flex content-center items-center justify-between gap-1',
        label: 'block font-medium text-default',
        container: 'relative',
        description: 'text-muted',
        error: 'mt-2 text-error',
        hint: 'text-muted',
        help: 'mt-2 text-muted'
      },
      variants: {
        size: {
          xs: {
            root: 'text-xs'
          },
          sm: {
            root: 'text-xs'
          },
          md: {
            root: 'text-sm'
          },
          lg: {
            root: 'text-sm'
          },
          xl: {
            root: 'text-base'
          }
        },
        required: {
          true: {
            label: "after:content-['*'] after:ms-0.5 after:text-error"
          }
        },
        orientation: {
          vertical: {
            container: 'mt-1'
          },
          horizontal: {
            root: 'flex justify-between place-items-baseline gap-2'
          }
        }
      },
      defaultVariants: {
        size: 'md',
        orientation: 'vertical'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/FormField.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/form-field.ts).


# Header

## Uso

O componente Header renderiza um elemento `<header>`.

> \[!TIP]
> See: /docs/getting-started/theme/css-variables#header
>
> Sua altura é definida por meio de uma variável CSS `--ui-header-height`.

Use os slots `left`, `default` e `right` para personalizar o cabeçalho e os slots `body` ou `content` para personalizar o menu do cabeçalho.

::component-example
---
collapse: true
overflowHidden: true
prettier: true
props:
  class: w-full
class: "!px-0 !pt-0"
name: header-example
---
::

> \[!NOTE]
>
> Neste exemplo, usamos o componente [NavigationMenu](https://ui.nitro.news/docs/components/navigation-menu) para renderizar os links do cabeçalho ao centro.

### Título

Use a prop `title` para alterar o título do cabeçalho. O padrão é `Nitro UI`.

```vue
<template>
  <UHeader title="Nitro UI" />
</template>
```

Você também pode usar o slot `title` para adicionar o seu próprio logo.

> \[!TIP]
> See: #props
>
> Você ainda deve adicionar a prop `title` para substituir o `aria-label` padrão do link.

```vue
<template>
  <UHeader>
    <template #title>
      <Logo class="h-6 w-auto" />
    </template></UHeader>
</template>
```

### Para

Use a prop `to` para alterar o link do título. O padrão é `/`.

```vue
<template>
  <UHeader to="/docs" />
</template>
```

Você também pode usar o slot `left` para sobrescrever o link por completo.

```vue
<template>
  <UHeader>
    <template #left>
      <NuxtLink to="/docs">
        <Logo class="h-6 w-auto" />
      </NuxtLink>
    </template></UHeader>
</template>
```

### Modo

Use a prop `mode` para alterar o modo do menu do cabeçalho. O padrão é `modal`.

Use o slot `body` para preencher o corpo do menu (abaixo do cabeçalho) ou o slot `content` para preencher o menu inteiro.

> \[!TIP]
> See: #props
>
> Você pode usar a prop `menu` para personalizar o menu do cabeçalho; ele se adapta dependendo do modo que você escolher.

::component-example
---
collapse: true
iframe:
  height: 300px;
iframeMobile: true
options:
  - name: mode
    label: mode
    default: drawer
    items:
      - modal
      - slideover
      - drawer
overflowHidden: true
props:
  class: w-full
name: header-menu-example
---
::

### Alternar

Use a prop `toggle` para personalizar o botão de alternância exibido no mobile.

Você pode passar qualquer propriedade do componente [Button](https://ui.nitro.news/docs/components/button) para personalizá-lo.

::component-example
---
collapse: true
iframe:
  height: 300px;
iframeMobile: true
overflowHidden: true
props:
  class: w-full
name: header-toggle-example
---
::

### Lado do toggle

Use a prop `toggle-side` para alterar o lado do botão de toggle. O padrão é `right`.

::component-example
---
collapse: true
iframe:
  height: 300px;
iframeMobile: true
overflowHidden: true
props:
  class: w-full
name: header-toggle-side-example
---
::

## Exemplos

### Com toggle animado

Use o slot `#toggle` para substituir o botão de alternância padrão por um ícone de hambúrguer animado personalizado usando o [Motion Vue](https://motion.dev/docs/vue/motion-component){rel="&#x22;nofollow&#x22;"}.

::component-example
---
collapse: true
iframe:
  height: 300px;
iframeMobile: true
overflowHidden: true
props:
  class: w-full
name: header-toggle-animated-example
---
::

### Dentro de `app.vue`

Use o componente Header no seu `app.vue` ou em um layout:

```vue [app.vue] {28-51}
<script setup lang="ts">
import type { NavigationMenuItem } from '@nitro/ui'

const route = useRoute()

const items = computed<NavigationMenuItem[]>(() => [{
  label: 'Docs',
  to: '/docs/getting-started',
  active: route.path.startsWith('/docs/getting-started')
}, {
  label: 'Components',
  to: '/docs/components',
  active: route.path.startsWith('/docs/components')
}, {
  label: 'Figma',
  to: 'https://go.nuxt.com/figma-ui',
  target: '_blank'
}, {
  label: 'Releases',
  to: 'https://github.com/nuxt/ui/releases',
  target: '_blank'
}])
</script>

<template>
  <NApp>
    <NHeader>
      <template #title>
        <Logo class="h-6 w-auto" />
      </template>

      <NNavigationMenu :items="items" />

      <template #right>
        <NColorModeButton />

        <NButton
          color="neutral"
          variant="ghost"
          to="https://github.com/nuxt/ui"
          target="_blank"
          icon="i-simple-icons-github"
          aria-label="GitHub"
        />
      </template>

      <template #body>
        <NNavigationMenu :items="items" orientation="vertical" class="-mx-2.5" />
      </template>
    </NHeader>

    <NMain>
      <NuxtLayout>
        <NuxtPage />
      </NuxtLayout>
    </NMain>

    <NFooter />
  </NApp>
</template>
```

## API

### Props

```ts
/**
 * Props for the Header component
 */
interface HeaderProps {
  /**
   * The element or component this component should render as.
   * @default "\"header\""
   */
  as?: any;
  /**
   * @default "\"Nuxt UI\""
   */
  title?: string | undefined;
  /**
   * @default "\"/\""
   */
  to?: string | undefined;
  /**
   * The mode of the header menu.
   * @default "\"modal\" as never"
   */
  mode?: T | undefined;
  /**
   * The props for the header menu component.
   */
  menu?: HeaderMenu<T> | undefined;
  /**
   * Customize the toggle button to open the header menu displayed when the `content` slot is used.
   * `{ color: 'neutral', variant: 'ghost' }`{lang="ts-type"}
   * @default "true"
   */
  toggle?: boolean | Omit<ButtonProps, LinkPropsKeys> | undefined;
  /**
   * The side to render the toggle button on.
   * @default "\"right\""
   */
  toggleSide?: "left" | "right" | undefined;
  /**
   * Automatically close when route changes.
   * @default "true"
   */
  autoClose?: boolean | undefined;
  ui?: { root?: SlotClass; container?: SlotClass; left?: SlotClass; center?: SlotClass; right?: SlotClass; title?: SlotClass; toggle?: SlotClass; content?: SlotClass; overlay?: SlotClass; header?: SlotClass; body?: SlotClass; } | undefined;
  /**
   * @default "false"
   */
  open?: boolean | undefined;
}
```

### Slots

```ts
/**
 * Slots for the Header component
 */
interface HeaderSlots {
  title(): any;
  left(): any;
  default(): any;
  right(): any;
  toggle(): any;
  top(): any;
  bottom(): any;
  body(): any;
  content(): any;
}
```

### Emits

```ts
/**
 * Emitted events for the Header component
 */
interface HeaderEmits {
  update:open: (payload: [value: boolean]) => void;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    header: {
      slots: {
        root: 'bg-default/75 backdrop-blur border-b border-default h-(--ui-header-height) sticky top-0 z-50',
        container: 'flex items-center justify-between gap-3 h-full',
        left: 'lg:flex-1 flex items-center gap-1.5',
        center: 'hidden lg:flex',
        right: 'flex items-center justify-end lg:flex-1 gap-1.5',
        title: 'shrink-0 font-bold text-xl text-highlighted flex items-end gap-1.5',
        toggle: 'lg:hidden',
        content: 'lg:hidden',
        overlay: 'lg:hidden',
        header: 'px-4 sm:px-6 h-(--ui-header-height) shrink-0 flex items-center justify-between gap-3',
        body: 'p-4 sm:p-6 overflow-y-auto'
      },
      variants: {
        toggleSide: {
          left: {
            toggle: '-ms-1.5'
          },
          right: {
            toggle: '-me-1.5'
          }
        }
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/Header.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/header.ts).


# Icon

## Uso

Use a prop `name` para exibir um ícone:

```vue
<template>
  <UIcon name="i-lucide-lightbulb" class="size-5" />
</template>
```

> \[!NOTE]
>
> Você pode usar qualquer nome da coleção <https://iconify.design>{rel="&#x22;nofollow&#x22;"}. Navegue por eles facilmente em <https://icones.js.org>{rel="&#x22;nofollow&#x22;"} ou busque diretamente pelo seu assistente de IA usando a ferramenta MCP [`search_icons`](https://ui.nitro.news/docs/getting-started/ai/mcp#available-tools).

**Nuxt:**

> \[!CAUTION]
> See: /docs/getting-started/integrations/icons/nuxt#collections
>
> É altamente recomendado instalar as coleções de ícones que você precisa; leia mais sobre isso.

## Exemplos

### SVG

Você também pode passar um componente Vue para a prop `name`:

:component-example{name="icon-svg-example"}

Você pode definir seus próprios componentes de ícone ou usar o [`unplugin-icons`](https://github.com/unplugin/unplugin-icons){rel="&#x22;nofollow&#x22;"} para importá-los diretamente de arquivos SVG:

```vue
<script setup lang="ts">
import IconLightbulb from '~icons/lucide/lightbulb'
</script>

<template>
  <NIcon :name="IconLightbulb" class="size-5" />
</template>
```

## API

### Props

```ts
/**
 * Props for the Icon component
 */
interface IconProps {
  name: any;
  mode?: "svg" | "css" | undefined;
  size?: string | number | undefined;
  customize?: boolean | IconifyIconCustomizeCallback | null | undefined;
}
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/Icon.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/icon.ts).


# Input

## Uso

Use a diretiva `v-model` para controlar o valor do Input.

```vue
<script setup lang="ts">
const value = ref("")
</script>

<template>
  <UInput />
</template>
```

### Tipo

Use a prop `type` para alterar o tipo do input. O padrão é `text`.

Alguns tipos foram implementados em seus próprios componentes, como [Checkbox](https://ui.nitro.news/docs/components/checkbox), [Radio](https://ui.nitro.news/docs/components/radio-group), [InputNumber](https://ui.nitro.news/docs/components/input-number), etc., e outros foram estilizados, como o `file`, por exemplo.

```vue
<template>
  <UInput type="file" />
</template>
```

> \[!NOTE]
> See: https\://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#input\_types
>
> Você pode conferir todos os tipos disponíveis no MDN Web Docs.

### Placeholder

Use a prop `placeholder` para definir um texto de placeholder.

```vue
<template>
  <UInput placeholder="Search..." />
</template>
```

### Cor

Use a prop `color` para alterar a cor do ring quando o Input está em foco.

```vue
<template>
  <UInput color="neutral" highlight placeholder="Search..." />
</template>
```

> \[!NOTE]
>
> A prop `highlight` é usada aqui para mostrar o estado de foco. Ela é usada internamente quando ocorre um erro de validação.

### Variante

Use a prop `variant` para alterar a variante do Input.

```vue
<template>
  <UInput color="neutral" variant="subtle" :highlight="false" placeholder="Search..." />
</template>
```

### Tamanho

Use a prop `size` para alterar o tamanho do Input.

```vue
<template>
  <UInput size="xl" placeholder="Search..." />
</template>
```

### Ícone

Use a prop `icon` para exibir um [Icon](https://ui.nitro.news/docs/components/icon) dentro do Input.

```vue
<template>
  <UInput icon="i-lucide-search" size="md" variant="outline" placeholder="Search..." />
</template>
```

Use as props `leading` e `trailing` para definir a posição do ícone ou as props `leading-icon` e `trailing-icon` para definir um ícone diferente para cada posição.

```vue
<template>
  <UInput trailing-icon="i-lucide-at-sign" placeholder="Enter your email" size="md" />
</template>
```

### Avatar

Use a prop `avatar` para exibir um [Avatar](https://ui.nitro.news/docs/components/avatar) dentro do Input.

```vue
<template>
  <UInput :avatar="{
  src: 'https://github.com/nuxt.png',
  loading: 'lazy'
}" size="md" variant="outline" placeholder="Search..." />
</template>
```

### Carregando

Use a prop `loading` para exibir um ícone de carregamento no Input.

```vue
<template>
  <UInput loading :trailing="false" placeholder="Search..." />
</template>
```

### Ícone de carregamento

Use a prop `loading-icon` para personalizar o ícone de carregamento. O padrão é `i-lucide-loader-circle`.

```vue
<template>
  <UInput loading loading-icon="i-lucide-loader" placeholder="Search..." />
</template>
```

**Nuxt:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/nuxt#theme
>
> Você pode personalizar esse ícone globalmente no seu `app.config.ts` na chave `ui.icons.loading`.

**Vue:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/vue#theme
>
> Você pode personalizar esse ícone globalmente no seu `vite.config.ts` na chave `ui.icons.loading`.

### Desabilitado

Use a prop `disabled` para desabilitar o Input.

```vue
<template>
  <UInput disabled placeholder="Search..." />
</template>
```

## Exemplos

### Com botão de limpar

Você pode colocar um [Button](https://ui.nitro.news/docs/components/button) dentro do slot `#trailing` para limpar o Input.

:component-example{name="input-clear-button-example"}

### Com botão de copiar

Você pode colocar um [Button](https://ui.nitro.news/docs/components/button) dentro do slot `#trailing` para copiar o valor para a área de transferência.

:component-example{name="input-copy-button-example"}

### Com alternância de senha

Você pode colocar um [Button](https://ui.nitro.news/docs/components/button) dentro do slot `#trailing` para alternar a visibilidade da senha.

:component-example{name="input-password-toggle-example"}

### Com indicador de força da senha

Você pode usar o componente [Progress](https://ui.nitro.news/docs/components/progress) para exibir o indicador de força da senha.

::component-example{collapse name="input-password-strength-indicator-example"}
::

### Com limite de caracteres

Você pode usar o slot `#trailing` para adicionar um limite de caracteres ao Input.

:component-example{name="input-character-limit-example"}

### Com atalho de teclado

Você pode usar o componente [Kbd](https://ui.nitro.news/docs/components/kbd) dentro do slot `#trailing` para adicionar um atalho de teclado ao Input.

:component-example{name="input-kbd-example"}

> \[!NOTE]
> See: /composables/define-shortcuts
>
> Este exemplo usa o composable `defineShortcuts` para focar o Input quando a tecla :kbd{value="/"} é pressionada.

### Com máscara

Não há suporte embutido para máscaras, mas você pode usar bibliotecas como o [maska](https://github.com/beholdr/maska){rel="&#x22;nofollow&#x22;"} para aplicar máscara ao Input.

:component-example{name="input-mask-example"}

### Com rótulo flutuante

Você pode usar o slot `#default` para adicionar um rótulo flutuante ao Input.

:component-example{name="input-floating-label-example"}

### Dentro de um FormField

Você pode usar o Input dentro de um componente [FormField](https://ui.nitro.news/docs/components/form-field) para exibir um rótulo, texto de ajuda, indicador de obrigatório, etc.

:component-example{name="input-form-field-example"}

> \[!TIP]
> See: /docs/components/form
>
> Ele também oferece validação e tratamento de erros quando usado dentro de um componente **Form**.

### Dentro de um FieldGroup

Você pode usar o Input dentro de um componente [FieldGroup](https://ui.nitro.news/components/field-group) para agrupar vários elementos.

:component-example{name="input-field-group-example"}

### Como campo de número de telefone

Você pode usar o Input dentro de um componente [FieldGroup](https://ui.nitro.news/docs/components/field-group) junto com um [SelectMenu](https://ui.nitro.news/docs/components/select-menu) para criar um campo de número de telefone com seleção de código do país.

::component-example{collapse name="input-phone-number-example"}
::

## API

### Props

```ts
/**
 * Props for the Input component
 */
interface InputProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  id?: string | undefined;
  name?: string | undefined;
  /**
   * @default "\"text\""
   */
  type?: InputTypeHTMLAttribute | undefined;
  /**
   * The placeholder text when the input is empty.
   */
  placeholder?: string | undefined;
  color?: "primary" | "secondary" | "accent" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
  variant?: "outline" | "soft" | "subtle" | "ghost" | "none" | undefined;
  size?: "xs" | "sm" | "md" | "lg" | "xl" | undefined;
  required?: boolean | undefined;
  /**
   * @default "\"off\""
   */
  autocomplete?: (string & {}) | "on" | "off" | undefined;
  autofocus?: boolean | undefined;
  /**
   * @default "0"
   */
  autofocusDelay?: number | undefined;
  disabled?: boolean | undefined;
  /**
   * Highlight the ring color like a focus state.
   */
  highlight?: boolean | undefined;
  /**
   * Keep the mobile text size on all breakpoints.
   */
  fixed?: boolean | undefined;
  modelValue?: _Number<_Optional<_Nullable<T, Mod>, Mod>, Mod> | undefined;
  defaultValue?: _Number<_Optional<_Nullable<T, Mod>, Mod>, Mod> | undefined;
  modelModifiers?: Mod | undefined;
  ui?: { root?: SlotClass; base?: SlotClass; leading?: SlotClass; leadingIcon?: SlotClass; leadingAvatar?: SlotClass; leadingAvatarSize?: SlotClass; trailing?: SlotClass; trailingIcon?: SlotClass; } | undefined;
  /**
   * Display an icon based on the `leading` and `trailing` props.
   */
  icon?: any;
  /**
   * Display an avatar on the left side.
   */
  avatar?: AvatarProps | undefined;
  /**
   * When `true`, the icon will be displayed on the left side.
   */
  leading?: boolean | undefined;
  /**
   * Display an icon on the left side.
   */
  leadingIcon?: any;
  /**
   * When `true`, the icon will be displayed on the right side.
   */
  trailing?: boolean | undefined;
  /**
   * Display an icon on the right side.
   */
  trailingIcon?: any;
  /**
   * When `true`, the loading icon will be displayed.
   */
  loading?: boolean | undefined;
  /**
   * The icon when the `loading` prop is `true`.
   */
  loadingIcon?: any;
  enterKeyHint?: "search" | "enter" | "done" | "go" | "next" | "previous" | "send" | undefined;
  form?: string | undefined;
  formaction?: string | undefined;
  formenctype?: string | undefined;
  formmethod?: string | undefined;
  formnovalidate?: Booleanish | undefined;
  formtarget?: string | undefined;
  list?: string | undefined;
  max?: Numberish | undefined;
  maxlength?: Numberish | undefined;
  min?: Numberish | undefined;
  minlength?: Numberish | undefined;
  pattern?: string | undefined;
  readonly?: Booleanish | undefined;
  step?: Numberish | undefined;
}
```

> \[!NOTE]
> See: https\://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#attributes
>
> Este componente também suporta todos os atributos HTML nativos de `<input>`.

### Slots

```ts
/**
 * Slots for the Input component
 */
interface InputSlots {
  leading(): any;
  default(): any;
  trailing(): any;
}
```

### Emits

```ts
/**
 * Emitted events for the Input component
 */
interface InputEmits {
  update:modelValue: (payload: [value: _Number<_Optional<_Nullable<T, Mod>, Mod>, Mod>]) => void;
  blur: (payload: [event: FocusEvent]) => void;
  change: (payload: [event: Event]) => void;
}
```

### Expose

Ao acessar o componente por meio de um template ref, você pode usar o seguinte:

| Name                                                                                                                           | Type                                                                                                                                               |
| ------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `inputRef`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | `Ref<HTMLInputElement | null>`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} |

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    input: {
      slots: {
        root: 'relative inline-flex items-center',
        base: [
          'w-full rounded-md border-0 appearance-none placeholder:text-dimmed disabled:cursor-not-allowed disabled:opacity-75',
          'transition-colors'
        ],
        leading: 'absolute inset-y-0 start-0 flex items-center',
        leadingIcon: 'shrink-0 text-dimmed',
        leadingAvatar: 'shrink-0',
        leadingAvatarSize: '',
        trailing: 'absolute inset-y-0 end-0 flex items-center',
        trailingIcon: 'shrink-0 text-dimmed'
      },
      variants: {
        fieldGroup: {
          horizontal: {
            root: 'group has-focus-visible:z-[1]',
            base: 'group-not-only:group-first:rounded-e-none group-not-only:group-last:rounded-s-none group-not-last:group-not-first:rounded-none'
          },
          vertical: {
            root: 'group has-focus-visible:z-[1]',
            base: 'group-not-only:group-first:rounded-b-none group-not-only:group-last:rounded-t-none group-not-last:group-not-first:rounded-none'
          }
        },
        size: {
          xs: {
            base: 'px-2 py-1 text-sm/4 gap-1',
            leading: 'ps-2',
            trailing: 'pe-2',
            leadingIcon: 'size-4',
            leadingAvatarSize: '3xs',
            trailingIcon: 'size-4'
          },
          sm: {
            base: 'px-2.5 py-1.5 text-sm/4 gap-1.5',
            leading: 'ps-2.5',
            trailing: 'pe-2.5',
            leadingIcon: 'size-4',
            leadingAvatarSize: '3xs',
            trailingIcon: 'size-4'
          },
          md: {
            base: 'px-2.5 py-1.5 text-base/5 gap-1.5',
            leading: 'ps-2.5',
            trailing: 'pe-2.5',
            leadingIcon: 'size-5',
            leadingAvatarSize: '2xs',
            trailingIcon: 'size-5'
          },
          lg: {
            base: 'px-3 py-2 text-base/5 gap-2',
            leading: 'ps-3',
            trailing: 'pe-3',
            leadingIcon: 'size-5',
            leadingAvatarSize: '2xs',
            trailingIcon: 'size-5'
          },
          xl: {
            base: 'px-3 py-2 text-base gap-2',
            leading: 'ps-3',
            trailing: 'pe-3',
            leadingIcon: 'size-6',
            leadingAvatarSize: 'xs',
            trailingIcon: 'size-6'
          }
        },
        variant: {
          outline: 'text-highlighted bg-default ring ring-inset ring-accented',
          soft: 'text-highlighted bg-elevated/50 hover:bg-elevated focus:bg-elevated disabled:bg-elevated/50',
          subtle: 'text-highlighted bg-elevated ring ring-inset ring-accented',
          ghost: 'text-highlighted bg-transparent hover:bg-elevated focus:bg-elevated disabled:bg-transparent dark:disabled:bg-transparent',
          none: 'text-highlighted bg-transparent focus:outline-none'
        },
        color: {
          primary: '',
          secondary: '',
          accent: '',
          success: '',
          info: '',
          warning: '',
          error: '',
          neutral: ''
        },
        leading: {
          true: ''
        },
        trailing: {
          true: ''
        },
        loading: {
          true: ''
        },
        highlight: {
          true: ''
        },
        fixed: {
          false: ''
        },
        type: {
          file: 'file:me-1.5 file:font-medium file:text-muted file:outline-none'
        }
      },
      compoundVariants: [
        {
          color: 'primary',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-primary/25 focus-visible:outline-3 focus-visible:ring-primary'
        },
        {
          color: 'secondary',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-secondary/25 focus-visible:outline-3 focus-visible:ring-secondary'
        },
        {
          color: 'accent',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-accent/25 focus-visible:outline-3 focus-visible:ring-accent'
        },
        {
          color: 'success',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-success/25 focus-visible:outline-3 focus-visible:ring-success'
        },
        {
          color: 'info',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-info/25 focus-visible:outline-3 focus-visible:ring-info'
        },
        {
          color: 'warning',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-warning/25 focus-visible:outline-3 focus-visible:ring-warning'
        },
        {
          color: 'error',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-error/25 focus-visible:outline-3 focus-visible:ring-error'
        },
        {
          color: 'primary',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-primary/25 focus-visible:outline-3'
        },
        {
          color: 'secondary',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-secondary/25 focus-visible:outline-3'
        },
        {
          color: 'accent',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-accent/25 focus-visible:outline-3'
        },
        {
          color: 'success',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-success/25 focus-visible:outline-3'
        },
        {
          color: 'info',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-info/25 focus-visible:outline-3'
        },
        {
          color: 'warning',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-warning/25 focus-visible:outline-3'
        },
        {
          color: 'error',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-error/25 focus-visible:outline-3'
        },
        {
          color: 'primary',
          highlight: true,
          class: 'ring ring-inset ring-primary'
        },
        {
          color: 'secondary',
          highlight: true,
          class: 'ring ring-inset ring-secondary'
        },
        {
          color: 'accent',
          highlight: true,
          class: 'ring ring-inset ring-accent'
        },
        {
          color: 'success',
          highlight: true,
          class: 'ring ring-inset ring-success'
        },
        {
          color: 'info',
          highlight: true,
          class: 'ring ring-inset ring-info'
        },
        {
          color: 'warning',
          highlight: true,
          class: 'ring ring-inset ring-warning'
        },
        {
          color: 'error',
          highlight: true,
          class: 'ring ring-inset ring-error'
        },
        {
          color: 'neutral',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-inverted/25 focus-visible:outline-3 focus-visible:ring-inverted'
        },
        {
          color: 'neutral',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-inverted/25 focus-visible:outline-3'
        },
        {
          color: 'neutral',
          highlight: true,
          class: 'ring ring-inset ring-inverted'
        },
        {
          leading: true,
          size: 'xs',
          class: 'ps-7'
        },
        {
          leading: true,
          size: 'sm',
          class: 'ps-8'
        },
        {
          leading: true,
          size: 'md',
          class: 'ps-9'
        },
        {
          leading: true,
          size: 'lg',
          class: 'ps-10'
        },
        {
          leading: true,
          size: 'xl',
          class: 'ps-11'
        },
        {
          trailing: true,
          size: 'xs',
          class: 'pe-7'
        },
        {
          trailing: true,
          size: 'sm',
          class: 'pe-8'
        },
        {
          trailing: true,
          size: 'md',
          class: 'pe-9'
        },
        {
          trailing: true,
          size: 'lg',
          class: 'pe-10'
        },
        {
          trailing: true,
          size: 'xl',
          class: 'pe-11'
        },
        {
          loading: true,
          leading: true,
          class: {
            leadingIcon: 'animate-spin'
          }
        },
        {
          loading: true,
          leading: false,
          trailing: true,
          class: {
            trailingIcon: 'animate-spin'
          }
        },
        {
          fixed: false,
          size: 'xs',
          class: 'md:text-xs'
        },
        {
          fixed: false,
          size: 'sm',
          class: 'md:text-xs'
        },
        {
          fixed: false,
          size: 'md',
          class: 'md:text-sm'
        },
        {
          fixed: false,
          size: 'lg',
          class: 'md:text-sm'
        }
      ],
      defaultVariants: {
        size: 'md',
        color: 'accent',
        variant: 'outline'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/Input.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/input.ts).


# InputDate

## Uso

Use a diretiva `v-model` para controlar a data selecionada.

```vue
<script setup lang="ts">
import { CalendarDate } from '@internationalized/date'

const value = shallowRef(new CalendarDate(2022, 2, 3))
</script>

<template>
  <UInputDate v-model="value" />
</template>
```

Use a prop `default-value` para definir o valor inicial quando você não precisa controlar o estado.

```vue
<script setup lang="ts">
import { CalendarDate } from '@internationalized/date'

const defaultValue = shallowRef(new CalendarDate(2022, 2, 6))
</script>

<template>
  <UInputDate :default-value="defaultValue" />
</template>
```

**Nuxt:**

> \[!NOTE]
> See: /docs/getting-started/integrations/i18n/nuxt#locale
>
> Este componente usa o pacote `@internationalized/date` para formatação sensível ao locale. O formato da data é determinado pela prop `locale` do componente App.

**Vue:**

> \[!NOTE]
> See: /docs/getting-started/integrations/i18n/vue#locale
>
> Este componente usa o pacote `@internationalized/date` para formatação sensível ao locale. O formato da data é determinado pela prop `locale` do componente App.

### Intervalo

Use a prop `range` para selecionar um intervalo de datas.

```vue
<script setup lang="ts">
import { CalendarDate } from '@internationalized/date'

const value = shallowRef({ start: new CalendarDate(2022, 2, 3), end: new CalendarDate(2022, 2, 20) })
</script>

<template>
  <UInputDate range v-model="value" />
</template>
```

### Cor

Use a prop `color` para alterar a cor do InputDate.

```vue
<template>
  <UInputDate color="neutral" highlight />
</template>
```

### Variante

Use a prop `variant` para alterar a variante do InputDate.

```vue
<template>
  <UInputDate variant="subtle" />
</template>
```

### Tamanho

Use a prop `size` para alterar o tamanho do InputDate.

```vue
<template>
  <UInputDate size="xl" />
</template>
```

### Ícone

Use a prop `icon` para exibir um [Icon](https://ui.nitro.news/docs/components/icon) dentro do InputDate.

```vue
<template>
  <UInputDate icon="i-lucide-calendar" />
</template>
```

> \[!NOTE]
>
> Use as props `leading` e `trailing` para definir a posição do ícone ou as props `leading-icon` e `trailing-icon` para definir um ícone diferente para cada posição.

### Ícone de separador

Use a prop `separator-icon` para alterar o [Icon](https://ui.nitro.news/docs/components/icon) do separador de intervalo. O padrão é `i-lucide-minus`.

```vue
<template>
  <UInputDate range separator-icon="i-lucide-arrow-right" />
</template>
```

**Nuxt:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/nuxt#theme
>
> Você pode personalizar esse ícone globalmente no seu `app.config.ts` na chave `ui.icons.minus`.

**Vue:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/vue#theme
>
> Você pode personalizar esse ícone globalmente no seu `vite.config.ts` na chave `ui.icons.minus`.

### Avatar

Use a prop `avatar` para exibir um [Avatar](https://ui.nitro.news/docs/components/avatar) dentro do InputDate.

```vue
<template>
  <UInputDate :avatar="{
  src: 'https://github.com/vuejs.png',
  loading: 'lazy'
}" size="md" variant="outline" />
</template>
```

### Desabilitado

Use a prop `disabled` para desabilitar o InputDate.

```vue
<template>
  <UInputDate disabled />
</template>
```

## Exemplos

### Com datas indisponíveis

Use a prop `is-date-unavailable` com uma função para marcar datas específicas como indisponíveis.

:component-example{name="input-date-unavailable-dates-example"}

### Com datas mín/máx

Use as props `min-value` e `max-value` para limitar as datas.

:component-example{name="input-date-min-max-dates-example"}

### Como seletor de data

Use a [Calendar](https://ui.nitro.news/docs/components/calendar) and a [Popover](https://ui.nitro.news/docs/components/popover) component to create a date picker.

:component-example{name="input-date-date-picker-example"}

### Como seletor de intervalo de datas

Use a [Calendar](https://ui.nitro.news/docs/components/calendar) and a [Popover](https://ui.nitro.news/docs/components/popover) component to create a date range picker.

:component-example{name="input-date-date-range-picker-example"}

## API

### Props

```ts
/**
 * Props for the InputDate component
 */
interface InputDateProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  color?: "primary" | "secondary" | "accent" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
  variant?: "outline" | "soft" | "subtle" | "ghost" | "none" | undefined;
  size?: "xs" | "sm" | "md" | "lg" | "xl" | undefined;
  /**
   * Highlight the ring color like a focus state.
   */
  highlight?: boolean | undefined;
  /**
   * Keep the mobile text size on all breakpoints.
   */
  fixed?: boolean | undefined;
  autofocus?: boolean | undefined;
  /**
   * @default "0"
   */
  autofocusDelay?: number | undefined;
  /**
   * The icon to use as a range separator.
   */
  separatorIcon?: any;
  /**
   * Whether or not a range of dates can be selected
   */
  range?: R | undefined;
  defaultValue?: CalendarDate | CalendarDateTime | ZonedDateTime | DateRange;
  modelValue?: null | CalendarDate | CalendarDateTime | ZonedDateTime | DateRange;
  ui?: { base?: SlotClass; leading?: SlotClass; leadingIcon?: SlotClass; leadingAvatar?: SlotClass; leadingAvatarSize?: SlotClass; trailing?: SlotClass; trailingIcon?: SlotClass; segment?: SlotClass; separatorIcon?: SlotClass; } | undefined;
  /**
   * Display an icon based on the `leading` and `trailing` props.
   */
  icon?: any;
  /**
   * Display an avatar on the left side.
   */
  avatar?: AvatarProps | undefined;
  /**
   * When `true`, the icon will be displayed on the left side.
   */
  leading?: boolean | undefined;
  /**
   * Display an icon on the left side.
   */
  leadingIcon?: any;
  /**
   * When `true`, the icon will be displayed on the right side.
   */
  trailing?: boolean | undefined;
  /**
   * Display an icon on the right side.
   */
  trailingIcon?: any;
  /**
   * When `true`, the loading icon will be displayed.
   */
  loading?: boolean | undefined;
  /**
   * The icon when the `loading` prop is `true`.
   */
  loadingIcon?: any;
  defaultPlaceholder?: CalendarDate | CalendarDateTime | ZonedDateTime;
  placeholder?: CalendarDate | CalendarDateTime | ZonedDateTime;
  /**
   * The hour cycle used for formatting times. Defaults to the local preference
   */
  hourCycle?: HourCycle;
  /**
   * The stepping interval for the time fields. Defaults to `1`.
   */
  step?: DateStep | undefined;
  /**
   * Whether to enforce snapping the time value to the nearest step increment after input. Defaults to `false`.
   */
  stepSnapping?: boolean | undefined;
  /**
   * The granularity to use for formatting times. Defaults to day if a CalendarDate is provided, otherwise defaults to minute. The field will render segments for each part of the date up to and including the specified granularity
   */
  granularity?: Granularity | undefined;
  /**
   * Whether or not to hide the time zone segment of the field
   */
  hideTimeZone?: boolean | undefined;
  maxValue?: CalendarDate | CalendarDateTime | ZonedDateTime;
  minValue?: CalendarDate | CalendarDateTime | ZonedDateTime;
  /**
   * The locale to use for formatting dates
   */
  locale?: string | undefined;
  /**
   * Whether or not the date field is disabled
   */
  disabled?: boolean | undefined;
  /**
   * Whether or not the date field is readonly
   */
  readonly?: boolean | undefined;
  /**
   * A function that returns whether or not a date is unavailable
   */
  isDateUnavailable?: Matcher | undefined;
  /**
   * Id of the element
   */
  id?: string | undefined;
  /**
   * The name of the field. Submitted with its owning form as part of a name/value pair.
   */
  name?: string | undefined;
  /**
   * When `true`, indicates that the user must set the value before the owning form can be submitted.
   */
  required?: boolean | undefined;
}
```

### Slots

```ts
/**
 * Slots for the InputDate component
 */
interface InputDateSlots {
  leading(): any;
  default(): any;
  trailing(): any;
  separator(): any;
}
```

### Emits

```ts
/**
 * Emitted events for the InputDate component
 */
interface InputDateEmits {
  update:modelValue: (payload: [value: InputDateModelValue<R>]) => void;
  update:placeholder: (payload: [date: DateValue] & [date: DateValue]) => void;
  change: (payload: [event: Event]) => void;
  blur: (payload: [event: FocusEvent]) => void;
  focus: (payload: [event: FocusEvent]) => void;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    inputDate: {
      slots: {
        base: [
          'group relative inline-flex items-center rounded-md select-none',
          'transition-colors'
        ],
        leading: 'absolute inset-y-0 start-0 flex items-center',
        leadingIcon: 'shrink-0 text-dimmed',
        leadingAvatar: 'shrink-0',
        leadingAvatarSize: '',
        trailing: 'absolute inset-y-0 end-0 flex items-center',
        trailingIcon: 'shrink-0 text-dimmed',
        segment: [
          'rounded text-center outline-hidden data-placeholder:text-dimmed data-[segment=literal]:text-muted data-invalid:text-error data-disabled:cursor-not-allowed data-disabled:opacity-75',
          'transition-colors'
        ],
        separatorIcon: 'shrink-0 size-4 text-muted'
      },
      variants: {
        fieldGroup: {
          horizontal: 'not-only:first:rounded-e-none not-only:last:rounded-s-none not-last:not-first:rounded-none focus-visible:z-[1]',
          vertical: 'not-only:first:rounded-b-none not-only:last:rounded-t-none not-last:not-first:rounded-none focus-visible:z-[1]'
        },
        size: {
          xs: {
            base: [
              'px-2 py-1 text-sm/4 gap-1',
              'gap-0.25'
            ],
            leading: 'ps-2',
            trailing: 'pe-2',
            leadingIcon: 'size-4',
            leadingAvatarSize: '3xs',
            trailingIcon: 'size-4',
            segment: 'data-[segment=day]:w-8 data-[segment=month]:w-8 data-[segment=year]:w-10'
          },
          sm: {
            base: [
              'px-2.5 py-1.5 text-sm/4 gap-1.5',
              'gap-0.5'
            ],
            leading: 'ps-2.5',
            trailing: 'pe-2.5',
            leadingIcon: 'size-4',
            leadingAvatarSize: '3xs',
            trailingIcon: 'size-4',
            segment: 'data-[segment=day]:w-8 data-[segment=month]:w-8 data-[segment=year]:w-10'
          },
          md: {
            base: [
              'px-2.5 py-1.5 text-base/5 gap-1.5',
              'gap-0.5'
            ],
            leading: 'ps-2.5',
            trailing: 'pe-2.5',
            leadingIcon: 'size-5',
            leadingAvatarSize: '2xs',
            trailingIcon: 'size-5',
            segment: 'data-[segment=day]:w-9 data-[segment=month]:w-9 data-[segment=year]:w-11'
          },
          lg: {
            base: [
              'px-3 py-2 text-base/5 gap-2',
              'gap-0.75'
            ],
            leading: 'ps-3',
            trailing: 'pe-3',
            leadingIcon: 'size-5',
            leadingAvatarSize: '2xs',
            trailingIcon: 'size-5',
            segment: 'data-[segment=day]:w-9 data-[segment=month]:w-9 data-[segment=year]:w-11'
          },
          xl: {
            base: [
              'px-3 py-2 text-base gap-2',
              'gap-0.75'
            ],
            leading: 'ps-3',
            trailing: 'pe-3',
            leadingIcon: 'size-6',
            leadingAvatarSize: 'xs',
            trailingIcon: 'size-6',
            segment: 'data-[segment=day]:w-10 data-[segment=month]:w-10 data-[segment=year]:w-12'
          }
        },
        variant: {
          outline: 'text-highlighted bg-default ring ring-inset ring-accented',
          soft: 'text-highlighted bg-elevated/50 hover:bg-elevated focus:bg-elevated disabled:bg-elevated/50',
          subtle: 'text-highlighted bg-elevated ring ring-inset ring-accented',
          ghost: 'text-highlighted bg-transparent hover:bg-elevated focus:bg-elevated disabled:bg-transparent dark:disabled:bg-transparent',
          none: 'text-highlighted bg-transparent focus:outline-none'
        },
        color: {
          primary: '',
          secondary: '',
          accent: '',
          success: '',
          info: '',
          warning: '',
          error: '',
          neutral: ''
        },
        leading: {
          true: ''
        },
        trailing: {
          true: ''
        },
        loading: {
          true: ''
        },
        highlight: {
          true: ''
        },
        fixed: {
          false: ''
        },
        type: {
          file: 'file:me-1.5 file:font-medium file:text-muted file:outline-none'
        }
      },
      compoundVariants: [
        {
          variant: 'outline',
          class: {
            segment: 'focus:bg-elevated'
          }
        },
        {
          variant: 'soft',
          class: {
            segment: 'focus:bg-accented/50 group-hover:focus:bg-accented'
          }
        },
        {
          variant: 'subtle',
          class: {
            segment: 'focus:bg-accented'
          }
        },
        {
          variant: 'ghost',
          class: {
            segment: 'focus:bg-elevated group-hover:focus:bg-accented'
          }
        },
        {
          variant: 'none',
          class: {
            segment: 'focus:bg-elevated'
          }
        },
        {
          color: 'primary',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-primary/25 focus-visible:outline-3 focus-visible:ring-primary'
        },
        {
          color: 'secondary',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-secondary/25 focus-visible:outline-3 focus-visible:ring-secondary'
        },
        {
          color: 'accent',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-accent/25 focus-visible:outline-3 focus-visible:ring-accent'
        },
        {
          color: 'success',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-success/25 focus-visible:outline-3 focus-visible:ring-success'
        },
        {
          color: 'info',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-info/25 focus-visible:outline-3 focus-visible:ring-info'
        },
        {
          color: 'warning',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-warning/25 focus-visible:outline-3 focus-visible:ring-warning'
        },
        {
          color: 'error',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-error/25 focus-visible:outline-3 focus-visible:ring-error'
        },
        {
          color: 'primary',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-primary/25 focus-visible:outline-3'
        },
        {
          color: 'secondary',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-secondary/25 focus-visible:outline-3'
        },
        {
          color: 'accent',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-accent/25 focus-visible:outline-3'
        },
        {
          color: 'success',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-success/25 focus-visible:outline-3'
        },
        {
          color: 'info',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-info/25 focus-visible:outline-3'
        },
        {
          color: 'warning',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-warning/25 focus-visible:outline-3'
        },
        {
          color: 'error',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-error/25 focus-visible:outline-3'
        },
        {
          color: 'primary',
          highlight: true,
          class: 'ring ring-inset ring-primary'
        },
        {
          color: 'secondary',
          highlight: true,
          class: 'ring ring-inset ring-secondary'
        },
        {
          color: 'accent',
          highlight: true,
          class: 'ring ring-inset ring-accent'
        },
        {
          color: 'success',
          highlight: true,
          class: 'ring ring-inset ring-success'
        },
        {
          color: 'info',
          highlight: true,
          class: 'ring ring-inset ring-info'
        },
        {
          color: 'warning',
          highlight: true,
          class: 'ring ring-inset ring-warning'
        },
        {
          color: 'error',
          highlight: true,
          class: 'ring ring-inset ring-error'
        },
        {
          color: 'neutral',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-inverted/25 focus-visible:outline-3 focus-visible:ring-inverted'
        },
        {
          color: 'neutral',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-inverted/25 focus-visible:outline-3'
        },
        {
          color: 'neutral',
          highlight: true,
          class: 'ring ring-inset ring-inverted'
        },
        {
          leading: true,
          size: 'xs',
          class: 'ps-7'
        },
        {
          leading: true,
          size: 'sm',
          class: 'ps-8'
        },
        {
          leading: true,
          size: 'md',
          class: 'ps-9'
        },
        {
          leading: true,
          size: 'lg',
          class: 'ps-10'
        },
        {
          leading: true,
          size: 'xl',
          class: 'ps-11'
        },
        {
          trailing: true,
          size: 'xs',
          class: 'pe-7'
        },
        {
          trailing: true,
          size: 'sm',
          class: 'pe-8'
        },
        {
          trailing: true,
          size: 'md',
          class: 'pe-9'
        },
        {
          trailing: true,
          size: 'lg',
          class: 'pe-10'
        },
        {
          trailing: true,
          size: 'xl',
          class: 'pe-11'
        },
        {
          loading: true,
          leading: true,
          class: {
            leadingIcon: 'animate-spin'
          }
        },
        {
          loading: true,
          leading: false,
          trailing: true,
          class: {
            trailingIcon: 'animate-spin'
          }
        },
        {
          fixed: false,
          size: 'xs',
          class: 'md:text-xs'
        },
        {
          fixed: false,
          size: 'sm',
          class: 'md:text-xs'
        },
        {
          fixed: false,
          size: 'md',
          class: 'md:text-sm'
        },
        {
          fixed: false,
          size: 'lg',
          class: 'md:text-sm'
        }
      ],
      defaultVariants: {
        size: 'md',
        color: 'accent',
        variant: 'outline'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/InputDate.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/input-date.ts).


# InputMenu

## Uso

Use a diretiva `v-model` para controlar o valor do InputMenu ou a prop `default-value` para definir o valor inicial quando você não precisa controlar o estado.

```vue
<script setup lang="ts">
const items = ref([
  "Backlog",
  "Todo",
  "In Progress",
  "Done"
])
const value = ref("Backlog")
</script>

<template>
  <UInputMenu v-model="value" :items="items" />
</template>
```

> \[!TIP]
>
> Use este no lugar de um [`Input`](https://ui.nitro.news/docs/components/input) para aproveitar o componente [`Combobox`](https://reka-ui.com/docs/components/combobox){rel="&#x22;nofollow&#x22;"} do Reka UI, que oferece recursos de autocomplete.

> \[!NOTE]
>
> Este componente é semelhante ao [`SelectMenu`](https://ui.nitro.news/docs/components/select-menu), mas usa um Input em vez de um Select.

### Itens

Use a prop `items` como um array de strings, números ou booleanos:

```vue
<script setup lang="ts">
const items = ref([
  "Backlog",
  "Todo",
  "In Progress",
  "Done"
])
const value = ref("Backlog")
</script>

<template>
  <UInputMenu v-model="value" :items="items" />
</template>
```

Você também pode passar um array de objetos com as seguintes propriedades:

- `label?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- [`type?: "label" | "separator" | "item"`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}](https://ui.nitro.news/#with-items-type)
- [`icon?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}](https://ui.nitro.news/#with-icons-in-items)
- [`avatar?: AvatarProps`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}](https://ui.nitro.news/#with-avatar-in-items)
- [`chip?: ChipProps`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}](https://ui.nitro.news/#with-chip-in-items)
- `disabled?: boolean`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `onSelect?: (e: Event) => void`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `class?: any`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `ui?: { tagsItem?: ClassNameValue, tagsItemText?: ClassNameValue, tagsItemDelete?: ClassNameValue, tagsItemDeleteIcon?: ClassNameValue, label?: ClassNameValue, separator?: ClassNameValue, item?: ClassNameValue, itemLeadingIcon?: ClassNameValue, itemLeadingAvatarSize?: ClassNameValue, itemLeadingAvatar?: ClassNameValue, itemLeadingChip?: ClassNameValue, itemLeadingChipSize?: ClassNameValue, itemLabel?: ClassNameValue, itemTrailing?: ClassNameValue, itemTrailingIcon?: ClassNameValue }`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

```vue
<script setup lang="ts">
import type { InputMenuItem } from '@nitro/ui'

const items = ref<InputMenuItem[]>([
  {
    label: "Backlog"
  },
  {
    label: "Todo"
  },
  {
    label: "In Progress"
  },
  {
    label: "Done"
  }
])
const value = ref({
  label: "Todo"
})
</script>

<template>
  <UInputMenu v-model="value" :items="items" />
</template>
```

Você também pode passar um array de arrays para a prop `items` para exibir grupos separados de itens.

```vue
<script setup lang="ts">
const items = ref([
  [
    "Apple",
    "Banana",
    "Blueberry",
    "Grapes",
    "Pineapple"
  ],
  [
    "Aubergine",
    "Broccoli",
    "Carrot",
    "Courgette",
    "Leek"
  ]
])
const value = ref("Apple")
</script>

<template>
  <UInputMenu v-model="value" :items="items" />
</template>
```

### Chave de valor

Você pode optar por vincular uma única propriedade do objeto em vez do objeto inteiro usando a prop `value-key`. O padrão é `undefined`.

```vue
<script setup lang="ts">
import type { InputMenuItem } from '@nitro/ui'

const items = ref<InputMenuItem[]>([
  {
    label: "Backlog",
    id: "backlog"
  },
  {
    label: "Todo",
    id: "todo"
  },
  {
    label: "In Progress",
    id: "in_progress"
  },
  {
    label: "Done",
    id: "done"
  }
])
const value = ref("todo")
</script>

<template>
  <UInputMenu v-model="value" value-key="id" :items="items" />
</template>
```

> \[!TIP]
>
> Use a prop `by` para comparar objetos por um campo em vez de por referência quando o `model-value` for um objeto.

### Múltiplo

Use a prop `multiple` para permitir múltiplas seleções; os itens selecionados serão exibidos como tags.

```vue
<script setup lang="ts">
const items = ref([
  "Backlog",
  "Todo",
  "In Progress",
  "Done"
])
const value = ref([
  "Backlog",
  "Todo"
])
</script>

<template>
  <UInputMenu v-model="value" multiple :items="items" />
</template>
```

> \[!CAUTION]
>
> Certifique-se de passar um array para a prop `default-value` ou para a diretiva `v-model`.

### Ícone de excluir

Com `multiple`, use a prop `delete-icon` para personalizar o [Icon](https://ui.nitro.news/docs/components/icon) de exclusão nas tags. O padrão é `i-lucide-x`.

```vue
<script setup lang="ts">
const items = ref([
  "Backlog",
  "Todo",
  "In Progress",
  "Done"
])
const value = ref([
  "Backlog",
  "Todo"
])
</script>

<template>
  <UInputMenu v-model="value" multiple delete-icon="i-lucide-trash" :items="items" />
</template>
```

**Nuxt:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/nuxt#theme
>
> Você pode personalizar esse ícone globalmente no seu `app.config.ts` na chave `ui.icons.close`.

**Vue:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/vue#theme
>
> Você pode personalizar esse ícone globalmente no seu `vite.config.ts` na chave `ui.icons.close`.

### Placeholder

Use a prop `placeholder` para definir um texto de placeholder.

```vue
<script setup lang="ts">
const items = ref([
  "Backlog",
  "Todo",
  "In Progress",
  "Done"
])
</script>

<template>
  <UInputMenu placeholder="Select status" :items="items" />
</template>
```

### Modo `4.8+`

Defina a prop `mode` como `autocomplete` para transformar o InputMenu em um campo de texto livre com sugestões. O `modelValue` passa a ser o texto do input (`string`) em vez de um item selecionado.

:component-example{name="input-menu-mode-example"}

> \[!CAUTION]
>
> Quando `mode` é `autocomplete`, `multiple`, `by`, `resetSearchTermOnSelect` e `resetModelValueOnClear` não são aplicáveis.

> \[!TIP]
>
> Use a prop `content.hideWhenEmpty` para ocultar o menu quando não há sugestões correspondentes.

### Conteúdo

Use a prop `content` para controlar como o conteúdo do InputMenu é renderizado, como seu `align` ou `side`, por exemplo.

```vue
<script setup lang="ts">
const items = ref([
  "Backlog",
  "Todo",
  "In Progress",
  "Done"
])
const value = ref("Backlog")
</script>

<template>
  <UInputMenu v-model="value" :content="{
  align: 'center',
  side: 'bottom',
  sideOffset: 8
}" :items="items" />
</template>
```

### Seta

Use a prop `arrow` para exibir uma seta no InputMenu.

```vue
<script setup lang="ts">
const items = ref([
  "Backlog",
  "Todo",
  "In Progress",
  "Done"
])
const value = ref("Backlog")
</script>

<template>
  <UInputMenu v-model="value" arrow :items="items" />
</template>
```

### Cor

Use a prop `color` para alterar a cor do ring quando o InputMenu está em foco.

```vue
<script setup lang="ts">
const items = ref([
  "Backlog",
  "Todo",
  "In Progress",
  "Done"
])
const value = ref("Backlog")
</script>

<template>
  <UInputMenu v-model="value" color="neutral" highlight :items="items" />
</template>
```

> \[!NOTE]
>
> A prop `highlight` é usada aqui para mostrar o estado de foco. Ela é usada internamente quando ocorre um erro de validação.

### Variante

Use a prop `variant` para alterar a variante do InputMenu.

```vue
<script setup lang="ts">
const items = ref([
  "Backlog",
  "Todo",
  "In Progress",
  "Done"
])
const value = ref("Backlog")
</script>

<template>
  <UInputMenu v-model="value" color="neutral" variant="subtle" :highlight="false" :items="items" />
</template>
```

### Tamanho

Use a prop `size` para alterar o tamanho do InputMenu.

```vue
<script setup lang="ts">
const items = ref([
  "Backlog",
  "Todo",
  "In Progress",
  "Done"
])
const value = ref("Backlog")
</script>

<template>
  <UInputMenu v-model="value" size="xl" :items="items" />
</template>
```

### Ícone

Use a prop `icon` para exibir um [Icon](https://ui.nitro.news/docs/components/icon) dentro do InputMenu.

```vue
<script setup lang="ts">
const items = ref([
  "Backlog",
  "Todo",
  "In Progress",
  "Done"
])
const value = ref("Backlog")
</script>

<template>
  <UInputMenu v-model="value" icon="i-lucide-search" size="md" :items="items" />
</template>
```

### Ícone à direita

Use a prop `trailing-icon` para personalizar o [Icon](https://ui.nitro.news/docs/components/icon) à direita. O padrão é `i-lucide-chevron-down`.

```vue
<script setup lang="ts">
const items = ref([
  "Backlog",
  "Todo",
  "In Progress",
  "Done"
])
const value = ref("Backlog")
</script>

<template>
  <UInputMenu v-model="value" trailing-icon="i-lucide-arrow-down" size="md" :items="items" />
</template>
```

**Nuxt:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/nuxt#theme
>
> Você pode personalizar esse ícone globalmente no seu `app.config.ts` na chave `ui.icons.chevronDown`.

**Vue:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/vue#theme
>
> Você pode personalizar esse ícone globalmente no seu `vite.config.ts` na chave `ui.icons.chevronDown`.

### Ícone de selecionado

Use a prop `selected-icon` para personalizar o ícone quando um item é selecionado. O padrão é `i-lucide-check`.

```vue
<script setup lang="ts">
const items = ref([
  "Backlog",
  "Todo",
  "In Progress",
  "Done"
])
const value = ref("Backlog")
</script>

<template>
  <UInputMenu v-model="value" selected-icon="i-lucide-flame" size="md" :items="items" />
</template>
```

**Nuxt:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/nuxt#theme
>
> Você pode personalizar esse ícone globalmente no seu `app.config.ts` na chave `ui.icons.check`.

**Vue:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/vue#theme
>
> Você pode personalizar esse ícone globalmente no seu `vite.config.ts` na chave `ui.icons.check`.

### Limpar `4.4+`

Use a prop `clear` para exibir um botão de limpar quando um valor está selecionado.

```vue
<script setup lang="ts">
const items = ref([
  "Backlog",
  "Todo",
  "In Progress",
  "Done"
])
const value = ref("Backlog")
</script>

<template>
  <UInputMenu v-model="value" clear :items="items" />
</template>
```

### Ícone de limpar `4.4+`

Use a prop `clear-icon` para personalizar o [Icon](https://ui.nitro.news/docs/components/icon) do botão de limpar. O padrão é `i-lucide-x`.

```vue
<script setup lang="ts">
const items = ref([
  "Backlog",
  "Todo",
  "In Progress",
  "Done"
])
const value = ref("Backlog")
</script>

<template>
  <UInputMenu v-model="value" clear clear-icon="i-lucide-trash" :items="items" />
</template>
```

**Nuxt:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/nuxt#theme
>
> Você pode personalizar esse ícone globalmente no seu `app.config.ts` na chave `ui.icons.close`.

**Vue:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/vue#theme
>
> Você pode personalizar esse ícone globalmente no seu `vite.config.ts` na chave `ui.icons.close`.

### Avatar

Use a prop `avatar` para exibir um [Avatar](https://ui.nitro.news/docs/components/avatar) dentro do InputMenu.

```vue
<script setup lang="ts">
const items = ref([
  "Nuxt",
  "NuxtHub",
  "NuxtLabs",
  "Nuxt Modules",
  "Nuxt Community"
])
const value = ref("Nuxt")
</script>

<template>
  <UInputMenu v-model="value" :avatar="{
  src: 'https://github.com/nuxt.png',
  loading: 'lazy'
}" :items="items" />
</template>
```

### Carregando

Use a prop `loading` para exibir um ícone de carregamento no InputMenu.

```vue
<script setup lang="ts">
const items = ref([
  "Backlog",
  "Todo",
  "In Progress",
  "Done"
])
const value = ref("Backlog")
</script>

<template>
  <UInputMenu v-model="value" loading :trailing="false" :items="items" />
</template>
```

### Ícone de carregamento

Use a prop `loading-icon` para personalizar o ícone de carregamento. O padrão é `i-lucide-loader-circle`.

```vue
<script setup lang="ts">
const items = ref([
  "Backlog",
  "Todo",
  "In Progress",
  "Done"
])
const value = ref("Backlog")
</script>

<template>
  <UInputMenu v-model="value" loading loading-icon="i-lucide-loader" :items="items" />
</template>
```

**Nuxt:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/nuxt#theme
>
> Você pode personalizar esse ícone globalmente no seu `app.config.ts` na chave `ui.icons.loading`.

**Vue:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/vue#theme
>
> Você pode personalizar esse ícone globalmente no seu `vite.config.ts` na chave `ui.icons.loading`.

### Desabilitado

Use a prop `disabled` para desabilitar o InputMenu.

```vue
<script setup lang="ts">
const items = ref([
  "Backlog",
  "Todo",
  "In Progress",
  "Done"
])
</script>

<template>
  <UInputMenu disabled placeholder="Select status" :items="items" />
</template>
```

## Exemplos

### Com tipo de itens

Você pode usar a propriedade `type` com `separator` para exibir um separador entre os itens ou `label` para exibir um rótulo.

```vue
<script setup lang="ts">
import type { InputMenuItem } from '@nitro/ui'

const items = ref<InputMenuItem[]>([
  {
    type: "label",
    label: "Fruits"
  },
  "Apple",
  "Banana",
  "Blueberry",
  "Grapes",
  "Pineapple",
  {
    type: "separator"
  },
  {
    type: "label",
    label: "Vegetables"
  },
  "Aubergine",
  "Broccoli",
  "Carrot",
  "Courgette",
  "Leek"
])
const value = ref("Apple")
</script>

<template>
  <UInputMenu v-model="value" :items="items" />
</template>
```

### Com ícone nos itens

Você pode usar a propriedade `icon` para exibir um [Icon](https://ui.nitro.news/docs/components/icon) dentro dos itens.

::component-example{collapse name="input-menu-items-icon-example"}
::

> \[!TIP]
>
> Você também pode usar o slot `#leading` para exibir o ícone selecionado.

### Com avatar nos itens

Você pode usar a propriedade `avatar` para exibir um [Avatar](https://ui.nitro.news/docs/components/avatar) dentro dos itens.

::component-example{collapse name="input-menu-items-avatar-example"}
::

> \[!TIP]
>
> Você também pode usar o slot `#leading` para exibir o avatar selecionado.

### Com chip nos itens

Você pode usar a propriedade `chip` para exibir um [Chip](https://ui.nitro.news/docs/components/chip) dentro dos itens.

::component-example{collapse name="input-menu-items-chip-example"}
::

> \[!NOTE]
>
> Neste exemplo, o slot `#leading` é usado para exibir o chip selecionado.

### Controlar o estado de abertura

Você pode controlar o estado de abertura usando a prop `default-open` ou a diretiva `v-model:open`.

:component-example{name="input-menu-open-example"}

> \[!NOTE]
>
> Neste exemplo, aproveitando o [`defineShortcuts`](https://ui.nitro.news/docs/composables/define-shortcuts), você pode abrir e fechar o InputMenu pressionando :kbd{value="O"}.

### Controlar o estado de abertura no foco

Você pode usar as props `open-on-focus` ou `open-on-click` para abrir o menu quando o input é focado ou clicado.

:component-example{name="input-menu-open-focus-example"}

### Controlar o termo de busca

Use a diretiva `v-model:search-term` para controlar o termo de busca.

:component-example{name="input-menu-search-term-example"}

### Com ícone rotativo

Aqui está um exemplo com um ícone rotativo que indica o estado de abertura do InputMenu.

:component-example{name="input-menu-icon-example"}

### Com criação de item

Use a prop `create-item` para permitir que os usuários adicionem valores personalizados que não estão nas opções predefinidas.

::component-example{collapse name="input-menu-create-item-example"}
::

> \[!NOTE]
>
> A opção de criar aparece quando nenhuma correspondência é encontrada, por padrão. Defina como `always` para exibi-la mesmo quando houver valores semelhantes.

> \[!TIP]
> See: #emits
>
> Use o evento `@create` para tratar a criação do item. Você receberá o evento e o item como argumentos.

### Com itens buscados

Você pode buscar itens de uma API e usá-los no InputMenu.

::component-example{collapse name="input-menu-fetch-example"}
::

> \[!NOTE]
>
> Este exemplo usa `useLazyFetch` com `immediate: false` para buscar os dados apenas quando o menu abre, evitando chamadas de API desnecessárias no carregamento da página.

### Com filtro ignorado

Defina a prop `ignore-filter` como `true` para desabilitar a busca interna e usar sua própria lógica de busca.

::component-example{collapse name="input-menu-ignore-filter-example"}
::

> \[!NOTE]
>
> Este exemplo usa [`refDebounced`](https://vueuse.org/shared/refDebounced/#refdebounced){rel="&#x22;nofollow&#x22;"} para aplicar debounce nas chamadas de API. A busca é adiada com `immediate: false`, então nenhuma requisição é feita até o menu abrir.

### Com campos de filtro

Use a prop `filter-fields` com um array de campos para filtrar. O padrão é `[labelKey]`.

::component-example{collapse name="input-menu-filter-fields-example"}
::

> \[!NOTE]
>
> Este exemplo usa `useLazyFetch` com `immediate: false` para buscar os dados apenas quando o menu abre, evitando chamadas de API desnecessárias no carregamento da página.

### Com virtualização `4.1+`

Use a prop `virtualize` para habilitar a virtualização em listas grandes, como um booleano ou um objeto com opções como `{ estimateSize: 32, overscan: 12 }`.

> \[!WARNING]
> See: https\://github.com/unovue/reka-ui/issues/1885
>
> Quando habilitado, todos os grupos são achatados em uma única lista devido a uma limitação do Reka UI.

::component-example{prettier name="input-menu-virtualize-example"}
::

### Com rolagem infinita `4.4+`

Você pode usar o composable [`useInfiniteScroll`](https://vueuse.org/core/useInfiniteScroll/){rel="&#x22;nofollow&#x22;"} para carregar mais dados conforme o usuário rola.

::component-example
---
collapse: true
highlights:
  - 41
  - 51
overflowHidden: true
prettier: true
name: input-menu-infinite-scroll-example
---
::

> \[!NOTE]
>
> Este exemplo usa `useLazyFetch` com `immediate: false`, então os dados só são carregados conforme o usuário rola.

### Com largura total do conteúdo

Você pode expandir o conteúdo até a largura total dos seus itens adicionando a classe `min-w-fit` no slot `ui.content`.

::component-example{collapse name="input-menu-content-width-example"}
::

> \[!TIP]
>
> Você também pode alterar a largura do conteúdo globalmente no seu `app.config.ts`:
>
> ```text
> export default defineAppConfig({
>   ui: {
>     inputMenu: {
>       slots: {
>         content: 'min-w-fit'
>       }
>     }
>   }
> })
> ```

### Como seletor de país

Você pode usar o InputMenu como um seletor de país com carregamento sob demanda. Os países só são buscados quando o menu é aberto pela primeira vez.

::component-example{collapse name="input-menu-countries-example"}
::

> \[!NOTE]
>
> Este exemplo usa `useLazyFetch` com `immediate: false` para carregar os países apenas quando o menu é aberto pela primeira vez.

## API

### Props

```ts
/**
 * Props for the InputMenu component
 */
interface InputMenuProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  id?: string | undefined;
  /**
   * @default "\"text\""
   */
  type?: InputTypeHTMLAttribute | undefined;
  /**
   * The placeholder text when the input is empty.
   */
  placeholder?: string | undefined;
  color?: "primary" | "secondary" | "accent" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
  variant?: "soft" | "outline" | "subtle" | "ghost" | "none" | undefined;
  size?: "sm" | "md" | "xs" | "lg" | "xl" | undefined;
  required?: boolean | undefined;
  autofocus?: boolean | undefined;
  /**
   * @default "0"
   */
  autofocusDelay?: number | undefined;
  /**
   * The icon displayed to open the menu.
   */
  trailingIcon?: any;
  /**
   * The icon displayed when an item is selected.
   */
  selectedIcon?: any;
  /**
   * The icon displayed to delete a tag.
   * Works only when `multiple` is `true`.
   */
  deleteIcon?: any;
  /**
   * Display a clear button to reset the model value.
   * Can be an object to pass additional props to the Button.
   */
  clear?: (C & boolean) | (C & Partial<Omit<ButtonProps, LinkPropsKeys>>) | undefined;
  /**
   * The icon displayed in the clear button.
   */
  clearIcon?: any;
  /**
   * The content of the menu.
   */
  content?: (Omit<ComboboxContentProps, "as" | "asChild" | "forceMount"> & Partial<EmitsToProps<DismissableLayerEmits>>) | undefined;
  /**
   * Display an arrow alongside the menu.
   * `{ rounded: true }`{lang="ts-type"}
   */
  arrow?: boolean | Omit<ComboboxArrowProps, "as" | "asChild"> | undefined;
  /**
   * Render the menu in a portal.
   * @default "true"
   */
  portal?: string | boolean | HTMLElement | undefined;
  /**
   * Enable virtualization for large lists.
   * Note: when enabled, all groups are flattened into a single list due to a limitation of Reka UI (https://github.com/unovue/reka-ui/issues/1885).
   * @default "false"
   */
  virtualize?: boolean | { overscan?: number | undefined; estimateSize?: number | ((index: number) => number) | undefined; } | undefined;
  /**
   * When `items` is an array of objects, select the field to use as the value instead of the object itself.
   */
  valueKey?: VK | undefined;
  /**
   * When `items` is an array of objects, select the field to use as the label.
   * @default "\"label\""
   */
  labelKey?: GetItemKeys<T> | undefined;
  /**
   * When `items` is an array of objects, select the field to use as the description.
   * @default "\"description\""
   */
  descriptionKey?: GetItemKeys<T> | undefined;
  items?: T | undefined;
  /**
   * The value of the InputMenu when initially rendered. Use when you do not need to control the state of the InputMenu.
   */
  defaultValue?: _Number<_Optional<_Nullable<GetModelValue<T, VK, M, ExcludeItem>, Mod>, Mod>, Mod> | IsClearUsed<M, C> | undefined;
  /**
   * The controlled value of the InputMenu. Can be binded-with with `v-model`.
   */
  modelValue?: _Number<_Optional<_Nullable<GetModelValue<T, VK, M, ExcludeItem>, Mod>, Mod>, Mod> | IsClearUsed<M, C> | undefined;
  modelModifiers?: Mod | undefined;
  /**
   * Whether multiple options can be selected or not.
   */
  multiple?: M | undefined;
  /**
   * Highlight the ring color like a focus state.
   */
  highlight?: boolean | undefined;
  /**
   * Keep the mobile text size on all breakpoints.
   */
  fixed?: boolean | undefined;
  /**
   * The behavior of the InputMenu.
   * - `combobox`: select one (or many) items from a list of suggestions.
   * - `autocomplete`: free-form text input with optional suggestions. The `modelValue` becomes the input text (`string`) instead of a selected item.
   * @default "\"combobox\""
   */
  mode?: "autocomplete" | "combobox" | undefined;
  /**
   * Determines if custom user input that does not exist in options can be added.
   */
  createItem?: boolean | "always" | { position?: "bottom" | "top" | undefined; when?: "empty" | "always" | undefined; } | undefined;
  /**
   * Fields to filter items by.
   */
  filterFields?: string[] | undefined;
  /**
   * When `true`, disable the default filters, useful for custom filtering (useAsyncData, useFetch, etc.).
   */
  ignoreFilter?: boolean | undefined;
  ui?: { root?: SlotClass; base?: SlotClass; leading?: SlotClass; leadingIcon?: SlotClass; leadingAvatar?: SlotClass; leadingAvatarSize?: SlotClass; trailing?: SlotClass; trailingIcon?: SlotClass; trailingClear?: SlotClass; arrow?: SlotClass; content?: SlotClass; viewport?: SlotClass; group?: SlotClass; empty?: SlotClass; label?: SlotClass; separator?: SlotClass; item?: SlotClass; itemLeadingIcon?: SlotClass; itemLeadingAvatar?: SlotClass; itemLeadingAvatarSize?: SlotClass; itemLeadingChip?: SlotClass; itemLeadingChipSize?: SlotClass; itemTrailing?: SlotClass; itemTrailingIcon?: SlotClass; itemWrapper?: SlotClass; itemLabel?: SlotClass; itemDescription?: SlotClass; tagsItem?: SlotClass; tagsItemText?: SlotClass; tagsItemDelete?: SlotClass; tagsItemDeleteIcon?: SlotClass; tagsInput?: SlotClass; } | undefined;
  /**
   * When `true`, prevents the user from interacting with listbox
   */
  disabled?: boolean | undefined;
  /**
   * The controlled open state of the Combobox. Can be binded with `v-model:open`.
   */
  open?: boolean | undefined;
  /**
   * The open state of the combobox when it is initially rendered. <br> Use when you do not need to control its open state.
   */
  defaultOpen?: boolean | undefined;
  /**
   * The name of the field. Submitted with its owning form as part of a name/value pair.
   */
  name?: string | undefined;
  /**
   * Whether to reset the searchTerm when the Combobox input blurred
   * @default "true"
   */
  resetSearchTermOnBlur?: boolean | undefined;
  /**
   * Whether to reset the searchTerm when the Combobox value is selected
   * @default "true"
   */
  resetSearchTermOnSelect?: boolean | undefined;
  /**
   * When `true` the `modelValue` will be reset to `null` (or `[]` if `multiple`)
   * @default "true"
   */
  resetModelValueOnClear?: boolean | undefined;
  /**
   * When `true`, hover over item will trigger highlight
   */
  highlightOnHover?: boolean | undefined;
  /**
   * Whether to open the combobox when the input is clicked
   */
  openOnClick?: boolean | undefined;
  /**
   * Whether to open the combobox when the input is focused
   */
  openOnFocus?: boolean | undefined;
  /**
   * Use this to compare objects by a particular field, or pass your own comparison function for complete control over how objects are compared.
   */
  by?: string | ((a: T, b: T) => boolean) | undefined;
  /**
   * Display an icon based on the `leading` and `trailing` props.
   */
  icon?: any;
  /**
   * Display an avatar on the left side.
   */
  avatar?: AvatarProps | undefined;
  /**
   * When `true`, the icon will be displayed on the left side.
   */
  leading?: boolean | undefined;
  /**
   * Display an icon on the left side.
   */
  leadingIcon?: any;
  /**
   * When `true`, the icon will be displayed on the right side.
   */
  trailing?: boolean | undefined;
  /**
   * When `true`, the loading icon will be displayed.
   */
  loading?: boolean | undefined;
  /**
   * The icon when the `loading` prop is `true`.
   */
  loadingIcon?: any;
  enterKeyHint?: "search" | "enter" | "done" | "go" | "next" | "previous" | "send" | undefined;
  form?: string | undefined;
  formaction?: string | undefined;
  formenctype?: string | undefined;
  formmethod?: string | undefined;
  formnovalidate?: Booleanish | undefined;
  formtarget?: string | undefined;
  list?: string | undefined;
  readonly?: Booleanish | undefined;
  autocomplete?: (string & {}) | "on" | "off" | undefined;
  /**
   * @default "\"\""
   */
  searchTerm?: string | undefined;
}
```

> \[!NOTE]
> See: https\://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#attributes
>
> Este componente também suporta todos os atributos HTML nativos de `<input>`.

### Slots

```ts
/**
 * Slots for the InputMenu component
 */
interface InputMenuSlots {
  leading(): any;
  trailing(): any;
  empty(): any;
  item(): any;
  item-leading(): any;
  item-label(): any;
  item-description(): any;
  item-trailing(): any;
  tags-item-text(): any;
  tags-item-delete(): any;
  content-top(): any;
  content-bottom(): any;
  create-item-label(): any;
}
```

### Emits

```ts
/**
 * Emitted events for the InputMenu component
 */
interface InputMenuEmits {
  update:open: (payload: [value: boolean]) => void;
  change: (payload: [event: Event]) => void;
  blur: (payload: [event: FocusEvent]) => void;
  focus: (payload: [event: FocusEvent]) => void;
  create: (payload: [item: string]) => void;
  clear: (payload: []) => void;
  highlight: (payload: [payload: { ref: HTMLElement; value: _Number<_Optional<_Nullable<GetModelValue<T, VK, M, ExcludeItem>, Mod>, Mod>, Mod> | IsClearUsed<M, C>; } | undefined]) => void;
  remove-tag: (payload: [item: _Number<_Optional<_Nullable<GetModelValue<T, VK, M, ExcludeItem>, Mod>, Mod>, Mod> | IsClearUsed<M, C>]) => void;
  update:modelValue: (payload: [value: _Number<_Optional<_Nullable<GetModelValue<T, VK, M, ExcludeItem>, Mod>, Mod>, Mod> | IsClearUsed<M, C>]) => void;
  update:searchTerm: (payload: [value: string]) => void;
}
```

### Expose

Ao acessar o componente por meio de um template ref, você pode usar o seguinte:

| Name                                                                                                                              | Type                                                                                                                                               |
| --------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `inputRef`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"}    | `Ref<HTMLInputElement | null>`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} |
| `viewportRef`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | `Ref<HTMLDivElement | null>`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"}   |

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    inputMenu: {
      slots: {
        root: 'relative inline-flex items-center',
        base: [
          'rounded-md',
          'transition-colors'
        ],
        leading: 'absolute inset-y-0 start-0 flex items-center',
        leadingIcon: 'shrink-0 text-dimmed',
        leadingAvatar: 'shrink-0',
        leadingAvatarSize: '',
        trailing: 'group absolute inset-y-0 end-0 flex items-center disabled:cursor-not-allowed disabled:opacity-75 focus:outline-none',
        trailingIcon: 'shrink-0 text-dimmed',
        trailingClear: 'p-0',
        arrow: 'fill-bg stroke-default',
        content: 'max-h-[min(15rem,var(--reka-combobox-content-available-height,15rem))] w-(--reka-combobox-trigger-width) bg-default shadow-lg rounded-md ring ring-default overflow-hidden data-[state=open]:animate-[scale-in_100ms_ease-out] data-[state=closed]:animate-[scale-out_100ms_ease-in] origin-(--reka-combobox-content-transform-origin) pointer-events-auto flex flex-col',
        viewport: 'relative scroll-py-1 overflow-y-auto flex-1',
        group: 'p-1 isolate',
        empty: 'text-center text-muted',
        label: 'font-semibold text-highlighted',
        separator: '-mx-1 my-1 h-px bg-border',
        item: [
          'group relative w-full flex items-start gap-1.5 p-1.5 text-sm select-none outline-none before:absolute before:z-[-1] before:inset-px before:rounded-md data-disabled:cursor-not-allowed data-disabled:opacity-75 text-default data-highlighted:not-data-disabled:text-highlighted data-highlighted:not-data-disabled:before:bg-elevated/50',
          'transition-colors before:transition-colors'
        ],
        itemLeadingIcon: [
          'shrink-0 text-dimmed group-data-highlighted:not-group-data-disabled:text-default',
          'transition-colors'
        ],
        itemLeadingAvatar: 'shrink-0',
        itemLeadingAvatarSize: '',
        itemLeadingChip: 'shrink-0',
        itemLeadingChipSize: '',
        itemTrailing: 'ms-auto inline-flex gap-1.5 items-center',
        itemTrailingIcon: 'shrink-0',
        itemWrapper: 'flex-1 flex flex-col min-w-0',
        itemLabel: 'truncate',
        itemDescription: 'truncate text-muted',
        tagsItem: 'px-1.5 py-0.5 rounded-sm font-medium inline-flex items-center gap-0.5 ring ring-inset ring-accented bg-elevated text-default data-disabled:cursor-not-allowed data-disabled:opacity-75',
        tagsItemText: 'truncate',
        tagsItemDelete: [
          'inline-flex items-center rounded-xs text-dimmed hover:text-default hover:bg-accented/75 disabled:pointer-events-none',
          'transition-colors'
        ],
        tagsItemDeleteIcon: 'shrink-0',
        tagsInput: 'flex-1 border-0 bg-transparent placeholder:text-dimmed focus:outline-none disabled:cursor-not-allowed disabled:opacity-75'
      },
      variants: {
        fieldGroup: {
          horizontal: {
            root: 'group has-focus-visible:z-[1]',
            base: 'group-not-only:group-first:rounded-e-none group-not-only:group-last:rounded-s-none group-not-last:group-not-first:rounded-none'
          },
          vertical: {
            root: 'group has-focus-visible:z-[1]',
            base: 'group-not-only:group-first:rounded-b-none group-not-only:group-last:rounded-t-none group-not-last:group-not-first:rounded-none'
          }
        },
        size: {
          xs: {
            base: 'px-2 py-1 text-sm/4 gap-1',
            leading: 'ps-2',
            trailing: 'pe-2',
            leadingIcon: 'size-4',
            leadingAvatarSize: '3xs',
            trailingIcon: 'size-4',
            label: 'p-1 text-[10px]/3 gap-1',
            item: 'p-1 text-xs gap-1',
            itemLeadingIcon: 'size-4',
            itemLeadingAvatarSize: '3xs',
            itemLeadingChip: 'size-4',
            itemLeadingChipSize: 'sm',
            itemTrailingIcon: 'size-4',
            tagsItem: 'text-[10px]/3',
            tagsItemDeleteIcon: 'size-3',
            empty: 'p-2 text-xs'
          },
          sm: {
            base: 'px-2.5 py-1.5 text-sm/4 gap-1.5',
            leading: 'ps-2.5',
            trailing: 'pe-2.5',
            leadingIcon: 'size-4',
            leadingAvatarSize: '3xs',
            trailingIcon: 'size-4',
            label: 'p-1.5 text-[10px]/3 gap-1.5',
            item: 'p-1.5 text-xs gap-1.5',
            itemLeadingIcon: 'size-4',
            itemLeadingAvatarSize: '3xs',
            itemLeadingChip: 'size-4',
            itemLeadingChipSize: 'sm',
            itemTrailingIcon: 'size-4',
            tagsItem: 'text-[10px]/3',
            tagsItemDeleteIcon: 'size-3',
            empty: 'p-2.5 text-xs'
          },
          md: {
            base: 'px-2.5 py-1.5 text-base/5 gap-1.5',
            leading: 'ps-2.5',
            trailing: 'pe-2.5',
            leadingIcon: 'size-5',
            leadingAvatarSize: '2xs',
            trailingIcon: 'size-5',
            label: 'p-1.5 text-xs gap-1.5',
            item: 'p-1.5 text-sm gap-1.5',
            itemLeadingIcon: 'size-5',
            itemLeadingAvatarSize: '2xs',
            itemLeadingChip: 'size-5',
            itemLeadingChipSize: 'md',
            itemTrailingIcon: 'size-5',
            tagsItem: 'text-xs',
            tagsItemDeleteIcon: 'size-3.5',
            empty: 'p-2.5 text-sm'
          },
          lg: {
            base: 'px-3 py-2 text-base/5 gap-2',
            leading: 'ps-3',
            trailing: 'pe-3',
            leadingIcon: 'size-5',
            leadingAvatarSize: '2xs',
            trailingIcon: 'size-5',
            label: 'p-2 text-xs gap-2',
            item: 'p-2 text-sm gap-2',
            itemLeadingIcon: 'size-5',
            itemLeadingAvatarSize: '2xs',
            itemLeadingChip: 'size-5',
            itemLeadingChipSize: 'md',
            itemTrailingIcon: 'size-5',
            tagsItem: 'text-xs',
            tagsItemDeleteIcon: 'size-3.5',
            empty: 'p-3 text-sm'
          },
          xl: {
            base: 'px-3 py-2 text-base gap-2',
            leading: 'ps-3',
            trailing: 'pe-3',
            leadingIcon: 'size-6',
            leadingAvatarSize: 'xs',
            trailingIcon: 'size-6',
            label: 'p-2 text-sm gap-2',
            item: 'p-2 text-base gap-2',
            itemLeadingIcon: 'size-6',
            itemLeadingAvatarSize: 'xs',
            itemLeadingChip: 'size-6',
            itemLeadingChipSize: 'lg',
            itemTrailingIcon: 'size-6',
            tagsItem: 'text-sm',
            tagsItemDeleteIcon: 'size-4',
            empty: 'p-3 text-base'
          }
        },
        variant: {
          outline: 'text-highlighted bg-default ring ring-inset ring-accented',
          soft: 'text-highlighted bg-elevated/50 hover:bg-elevated focus:bg-elevated disabled:bg-elevated/50',
          subtle: 'text-highlighted bg-elevated ring ring-inset ring-accented',
          ghost: 'text-highlighted bg-transparent hover:bg-elevated focus:bg-elevated disabled:bg-transparent dark:disabled:bg-transparent',
          none: 'text-highlighted bg-transparent focus:outline-none'
        },
        color: {
          primary: '',
          secondary: '',
          accent: '',
          success: '',
          info: '',
          warning: '',
          error: '',
          neutral: ''
        },
        leading: {
          true: ''
        },
        trailing: {
          true: ''
        },
        loading: {
          true: ''
        },
        highlight: {
          true: ''
        },
        fixed: {
          false: ''
        },
        type: {
          file: 'file:me-1.5 file:font-medium file:text-muted file:outline-none'
        },
        virtualize: {
          true: {
            viewport: 'p-1 isolate'
          },
          false: {
            viewport: 'divide-y divide-default'
          }
        },
        multiple: {
          true: {
            root: 'flex-wrap'
          },
          false: {
            base: 'w-full border-0 placeholder:text-dimmed disabled:cursor-not-allowed disabled:opacity-75'
          }
        }
      },
      compoundVariants: [
        {
          variant: 'soft',
          multiple: true,
          class: 'has-focus:bg-elevated has-focus-visible:outline-3'
        },
        {
          variant: 'ghost',
          multiple: true,
          class: 'has-focus:bg-elevated has-focus-visible:outline-3'
        },
        {
          color: 'primary',
          multiple: true,
          variant: [
            'outline',
            'subtle'
          ],
          class: 'has-focus-visible:outline-3 has-focus-visible:ring-primary'
        },
        {
          color: 'secondary',
          multiple: true,
          variant: [
            'outline',
            'subtle'
          ],
          class: 'has-focus-visible:outline-3 has-focus-visible:ring-secondary'
        },
        {
          color: 'accent',
          multiple: true,
          variant: [
            'outline',
            'subtle'
          ],
          class: 'has-focus-visible:outline-3 has-focus-visible:ring-accent'
        },
        {
          color: 'success',
          multiple: true,
          variant: [
            'outline',
            'subtle'
          ],
          class: 'has-focus-visible:outline-3 has-focus-visible:ring-success'
        },
        {
          color: 'info',
          multiple: true,
          variant: [
            'outline',
            'subtle'
          ],
          class: 'has-focus-visible:outline-3 has-focus-visible:ring-info'
        },
        {
          color: 'warning',
          multiple: true,
          variant: [
            'outline',
            'subtle'
          ],
          class: 'has-focus-visible:outline-3 has-focus-visible:ring-warning'
        },
        {
          color: 'error',
          multiple: true,
          variant: [
            'outline',
            'subtle'
          ],
          class: 'has-focus-visible:outline-3 has-focus-visible:ring-error'
        },
        {
          color: 'neutral',
          multiple: true,
          variant: [
            'outline',
            'subtle'
          ],
          class: 'has-focus-visible:outline-3 has-focus-visible:ring-inverted'
        },
        {
          color: 'primary',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-primary/25 focus-visible:outline-3 focus-visible:ring-primary'
        },
        {
          color: 'secondary',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-secondary/25 focus-visible:outline-3 focus-visible:ring-secondary'
        },
        {
          color: 'accent',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-accent/25 focus-visible:outline-3 focus-visible:ring-accent'
        },
        {
          color: 'success',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-success/25 focus-visible:outline-3 focus-visible:ring-success'
        },
        {
          color: 'info',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-info/25 focus-visible:outline-3 focus-visible:ring-info'
        },
        {
          color: 'warning',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-warning/25 focus-visible:outline-3 focus-visible:ring-warning'
        },
        {
          color: 'error',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-error/25 focus-visible:outline-3 focus-visible:ring-error'
        },
        {
          color: 'primary',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-primary/25 focus-visible:outline-3'
        },
        {
          color: 'secondary',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-secondary/25 focus-visible:outline-3'
        },
        {
          color: 'accent',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-accent/25 focus-visible:outline-3'
        },
        {
          color: 'success',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-success/25 focus-visible:outline-3'
        },
        {
          color: 'info',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-info/25 focus-visible:outline-3'
        },
        {
          color: 'warning',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-warning/25 focus-visible:outline-3'
        },
        {
          color: 'error',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-error/25 focus-visible:outline-3'
        },
        {
          color: 'primary',
          highlight: true,
          class: 'ring ring-inset ring-primary'
        },
        {
          color: 'secondary',
          highlight: true,
          class: 'ring ring-inset ring-secondary'
        },
        {
          color: 'accent',
          highlight: true,
          class: 'ring ring-inset ring-accent'
        },
        {
          color: 'success',
          highlight: true,
          class: 'ring ring-inset ring-success'
        },
        {
          color: 'info',
          highlight: true,
          class: 'ring ring-inset ring-info'
        },
        {
          color: 'warning',
          highlight: true,
          class: 'ring ring-inset ring-warning'
        },
        {
          color: 'error',
          highlight: true,
          class: 'ring ring-inset ring-error'
        },
        {
          color: 'neutral',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-inverted/25 focus-visible:outline-3 focus-visible:ring-inverted'
        },
        {
          color: 'neutral',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-inverted/25 focus-visible:outline-3'
        },
        {
          color: 'neutral',
          highlight: true,
          class: 'ring ring-inset ring-inverted'
        },
        {
          leading: true,
          size: 'xs',
          class: 'ps-7'
        },
        {
          leading: true,
          size: 'sm',
          class: 'ps-8'
        },
        {
          leading: true,
          size: 'md',
          class: 'ps-9'
        },
        {
          leading: true,
          size: 'lg',
          class: 'ps-10'
        },
        {
          leading: true,
          size: 'xl',
          class: 'ps-11'
        },
        {
          trailing: true,
          size: 'xs',
          class: 'pe-7'
        },
        {
          trailing: true,
          size: 'sm',
          class: 'pe-8'
        },
        {
          trailing: true,
          size: 'md',
          class: 'pe-9'
        },
        {
          trailing: true,
          size: 'lg',
          class: 'pe-10'
        },
        {
          trailing: true,
          size: 'xl',
          class: 'pe-11'
        },
        {
          loading: true,
          leading: true,
          class: {
            leadingIcon: 'animate-spin'
          }
        },
        {
          loading: true,
          leading: false,
          trailing: true,
          class: {
            trailingIcon: 'animate-spin'
          }
        },
        {
          fixed: false,
          size: 'xs',
          class: 'md:text-xs'
        },
        {
          fixed: false,
          size: 'sm',
          class: 'md:text-xs'
        },
        {
          fixed: false,
          size: 'md',
          class: 'md:text-sm'
        },
        {
          fixed: false,
          size: 'lg',
          class: 'md:text-sm'
        }
      ],
      defaultVariants: {
        size: 'md',
        color: 'accent',
        variant: 'outline'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/InputMenu.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/input-menu.ts).


# InputNumber

## Uso

Use a diretiva `v-model` para controlar o valor do InputNumber.

```vue
<script setup lang="ts">
const value = ref(5)
</script>

<template>
  <UInputNumber v-model="value" />
</template>
```

Use a prop `default-value` para definir o valor inicial quando você não precisa controlar o estado.

```vue
<template>
  <UInputNumber :default-value="5" />
</template>
```

> \[!NOTE]
>
> Este componente depende do pacote [`@internationalized/number`](https://react-spectrum.adobe.com/internationalized/number/index.html){rel="&#x22;nofollow&#x22;"}, que fornece utilitários para formatar e interpretar números entre locales e sistemas de numeração.

### Mín / Máx

Use as props `min` e `max` para definir os valores mínimo e máximo do InputNumber.

```vue
<script setup lang="ts">
const value = ref(5)
</script>

<template>
  <UInputNumber v-model="value" :min="0" :max="10" />
</template>
```

### Etapa

Use a prop `step` para definir o valor do passo do InputNumber.

```vue
<script setup lang="ts">
const value = ref(5)
</script>

<template>
  <UInputNumber v-model="value" :step="2" />
</template>
```

### Orientação

Use a prop `orientation` para alterar a orientação do InputNumber.

```vue
<script setup lang="ts">
const value = ref(5)
</script>

<template>
  <UInputNumber v-model="value" orientation="vertical" />
</template>
```

### Placeholder

Use a prop `placeholder` para definir um texto de placeholder.

```vue
<template>
  <UInputNumber placeholder="Enter a number" />
</template>
```

### Cor

Use a prop `color` para alterar a cor do ring quando o InputNumber está em foco.

```vue
<script setup lang="ts">
const value = ref(5)
</script>

<template>
  <UInputNumber v-model="value" color="neutral" highlight />
</template>
```

### Variante

Use a prop `variant` para alterar a variante do InputNumber.

```vue
<script setup lang="ts">
const value = ref(5)
</script>

<template>
  <UInputNumber v-model="value" variant="subtle" color="neutral" :highlight="false" />
</template>
```

### Tamanho

Use a prop `size` para alterar o tamanho do InputNumber.

```vue
<script setup lang="ts">
const value = ref(5)
</script>

<template>
  <UInputNumber v-model="value" size="xl" />
</template>
```

### Desabilitado

Use a prop `disabled` para desabilitar o InputNumber.

```vue
<script setup lang="ts">
const value = ref(5)
</script>

<template>
  <UInputNumber v-model="value" disabled />
</template>
```

### Incrementar / Decrementar

Use as props `increment` e `decrement` para personalizar os botões de incremento e decremento com quaisquer props do [Button](https://ui.nitro.news/docs/components/button). O padrão é `{ variant: 'link' }`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}.

```vue
<script setup lang="ts">
const value = ref(5)
</script>

<template>
  <UInputNumber v-model="value" :increment="{
  color: 'neutral',
  variant: 'solid',
  size: 'xs'
}" :decrement="{
  color: 'neutral',
  variant: 'solid',
  size: 'xs'
}" />
</template>
```

### Ícones de incrementar / decrementar

Use as props `increment-icon` e `decrement-icon` para personalizar o [Icon](https://ui.nitro.news/docs/components/icon) dos botões. O padrão é `i-lucide-plus` / `i-lucide-minus`.

```vue
<script setup lang="ts">
const value = ref(5)
</script>

<template>
  <UInputNumber v-model="value" increment-icon="i-lucide-arrow-right" decrement-icon="i-lucide-arrow-left" />
</template>
```

## Exemplos

### Com formato decimal

Use a prop `format-options` para personalizar o formato do valor.

:component-example{name="input-number-decimal-example"}

### Com formato de porcentagem

Use a prop `format-options` com `style: 'percent'` para personalizar o formato do valor.

:component-example{name="input-number-percentage-example"}

### Com formato de moeda

Use a prop `format-options` com `style: 'currency'` para personalizar o formato do valor.

:component-example{name="input-number-currency-example"}

### Sem botões

Você pode usar as props `increment` e `decrement` para controlar a visibilidade dos botões.

:component-example{name="input-number-without-buttons-example"}

### Dentro de um FormField

Você pode usar o InputNumber dentro de um componente [FormField](https://ui.nitro.news/docs/components/form-field) para exibir um rótulo, texto de ajuda, indicador de obrigatório, etc.

:component-example{name="input-number-form-field-example"}

### Com slots

Use os slots `#increment` e `#decrement` para personalizar os botões.

:component-example{name="input-number-slots-example"}

## API

### Props

```ts
/**
 * Props for the InputNumber component
 */
interface InputNumberProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  /**
   * The placeholder text when the input is empty.
   */
  placeholder?: string | undefined;
  color?: "primary" | "secondary" | "accent" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
  variant?: "outline" | "soft" | "subtle" | "ghost" | "none" | undefined;
  size?: "xs" | "sm" | "md" | "lg" | "xl" | undefined;
  /**
   * Highlight the ring color like a focus state.
   */
  highlight?: boolean | undefined;
  /**
   * Keep the mobile text size on all breakpoints.
   */
  fixed?: boolean | undefined;
  /**
   * The orientation of the input number.
   * @default "\"horizontal\""
   */
  orientation?: "horizontal" | "vertical" | undefined;
  /**
   * Configure the increment button. The `color` and `size` are inherited.
   * @default "true"
   */
  increment?: boolean | Omit<ButtonProps, LinkPropsKeys> | undefined;
  /**
   * The icon displayed to increment the value.
   */
  incrementIcon?: any;
  /**
   * Disable the increment button.
   */
  incrementDisabled?: boolean | undefined;
  /**
   * Configure the decrement button. The `color` and `size` are inherited.
   * @default "true"
   */
  decrement?: boolean | Omit<ButtonProps, LinkPropsKeys> | undefined;
  /**
   * The icon displayed to decrement the value.
   */
  decrementIcon?: any;
  /**
   * Disable the decrement button.
   */
  decrementDisabled?: boolean | undefined;
  autofocus?: boolean | undefined;
  autofocusDelay?: number | undefined;
  defaultValue?: NonNullable<T> | undefined;
  modelValue?: ApplyModifiers<T, Mod> | undefined;
  modelModifiers?: Mod | undefined;
  ui?: { root?: SlotClass; base?: SlotClass; increment?: SlotClass; decrement?: SlotClass; } | undefined;
  /**
   * The smallest value allowed for the input.
   */
  min?: number | undefined;
  /**
   * The largest value allowed for the input.
   */
  max?: number | undefined;
  /**
   * The amount that the input value changes with each increment or decrement "tick".
   */
  step?: number | undefined;
  /**
   * When `false`, prevents the value from snapping to the nearest increment of the step value
   */
  stepSnapping?: boolean | undefined;
  /**
   * When `true`, prevents the user from interacting with the Number Field.
   */
  disabled?: boolean | undefined;
  /**
   * When `true`, indicates that the user must set the value before the owning form can be submitted.
   */
  required?: boolean | undefined;
  /**
   * Id of the element
   */
  id?: string | undefined;
  /**
   * The name of the field. Submitted with its owning form as part of a name/value pair.
   */
  name?: string | undefined;
  /**
   * Formatting options for the value displayed in the number field. This also affects what characters are allowed to be typed by the user.
   */
  formatOptions?: Intl.NumberFormatOptions | undefined;
  /**
   * When `true`, prevents the value from changing on wheel scroll.
   */
  disableWheelChange?: boolean | undefined;
  /**
   * When `true`, inverts the direction of the wheel change.
   */
  invertWheelChange?: boolean | undefined;
  /**
   * When `true`, the Number Field is read-only.
   */
  readonly?: boolean | undefined;
  /**
   * When `true`, the input will be focused when the value changes.
   */
  focusOnChange?: boolean | undefined;
  /**
   * The locale to use for formatting and currencies
   */
  locale?: string | undefined;
  enterKeyHint?: "enter" | "done" | "go" | "next" | "previous" | "search" | "send" | undefined;
  form?: string | undefined;
  formaction?: string | undefined;
  formenctype?: string | undefined;
  formmethod?: string | undefined;
  formnovalidate?: Booleanish | undefined;
  formtarget?: string | undefined;
  list?: string | undefined;
  autocomplete?: "on" | "off" | (string & {}) | undefined;
}
```

> \[!NOTE]
> See: https\://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#attributes
>
> Este componente também suporta todos os atributos HTML nativos de `<input>`.

### Slots

```ts
/**
 * Slots for the InputNumber component
 */
interface InputNumberSlots {
  increment(): any;
  decrement(): any;
}
```

### Emits

```ts
/**
 * Emitted events for the InputNumber component
 */
interface InputNumberEmits {
  update:modelValue: (payload: [value: ApplyModifiers<T, Mod>]) => void;
  blur: (payload: [event: FocusEvent]) => void;
  change: (payload: [event: Event]) => void;
}
```

### Expose

Ao acessar o componente por meio de um template ref, você pode usar o seguinte:

| Name                                                                                                                           | Type                                                                                                                                               |
| ------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `inputRef`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | `Ref<HTMLInputElement | null>`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} |

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    inputNumber: {
      slots: {
        root: 'relative inline-flex items-center',
        base: [
          'w-full rounded-md border-0 placeholder:text-dimmed disabled:cursor-not-allowed disabled:opacity-75',
          'transition-colors'
        ],
        increment: 'absolute flex items-center',
        decrement: 'absolute flex items-center'
      },
      variants: {
        fieldGroup: {
          horizontal: {
            root: 'group has-focus-visible:z-[1]',
            base: 'group-not-only:group-first:rounded-e-none group-not-only:group-last:rounded-s-none group-not-last:group-not-first:rounded-none'
          },
          vertical: {
            root: 'group has-focus-visible:z-[1]',
            base: 'group-not-only:group-first:rounded-b-none group-not-only:group-last:rounded-t-none group-not-last:group-not-first:rounded-none'
          }
        },
        color: {
          primary: '',
          secondary: '',
          accent: '',
          success: '',
          info: '',
          warning: '',
          error: '',
          neutral: ''
        },
        size: {
          xs: 'px-2 py-1 text-sm/4 gap-1',
          sm: 'px-2.5 py-1.5 text-sm/4 gap-1.5',
          md: 'px-2.5 py-1.5 text-base/5 gap-1.5',
          lg: 'px-3 py-2 text-base/5 gap-2',
          xl: 'px-3 py-2 text-base gap-2'
        },
        variant: {
          outline: 'text-highlighted bg-default ring ring-inset ring-accented',
          soft: 'text-highlighted bg-elevated/50 hover:bg-elevated focus:bg-elevated disabled:bg-elevated/50',
          subtle: 'text-highlighted bg-elevated ring ring-inset ring-accented',
          ghost: 'text-highlighted bg-transparent hover:bg-elevated focus:bg-elevated disabled:bg-transparent dark:disabled:bg-transparent',
          none: 'text-highlighted bg-transparent focus:outline-none'
        },
        disabled: {
          true: {
            increment: 'opacity-75 cursor-not-allowed',
            decrement: 'opacity-75 cursor-not-allowed'
          }
        },
        orientation: {
          horizontal: {
            base: 'text-center',
            increment: 'inset-y-0 end-0 pe-1',
            decrement: 'inset-y-0 start-0 ps-1'
          },
          vertical: {
            increment: 'top-0 end-0 pe-1 [&>button]:py-0 scale-80',
            decrement: 'bottom-0 end-0 pe-1 [&>button]:py-0 scale-80'
          }
        },
        highlight: {
          true: ''
        },
        fixed: {
          false: ''
        },
        increment: {
          false: ''
        },
        decrement: {
          false: ''
        }
      },
      compoundVariants: [
        {
          color: 'primary',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-primary/25 focus-visible:outline-3 focus-visible:ring-primary'
        },
        {
          color: 'secondary',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-secondary/25 focus-visible:outline-3 focus-visible:ring-secondary'
        },
        {
          color: 'accent',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-accent/25 focus-visible:outline-3 focus-visible:ring-accent'
        },
        {
          color: 'success',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-success/25 focus-visible:outline-3 focus-visible:ring-success'
        },
        {
          color: 'info',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-info/25 focus-visible:outline-3 focus-visible:ring-info'
        },
        {
          color: 'warning',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-warning/25 focus-visible:outline-3 focus-visible:ring-warning'
        },
        {
          color: 'error',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-error/25 focus-visible:outline-3 focus-visible:ring-error'
        },
        {
          color: 'primary',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-primary/25 focus-visible:outline-3'
        },
        {
          color: 'secondary',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-secondary/25 focus-visible:outline-3'
        },
        {
          color: 'accent',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-accent/25 focus-visible:outline-3'
        },
        {
          color: 'success',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-success/25 focus-visible:outline-3'
        },
        {
          color: 'info',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-info/25 focus-visible:outline-3'
        },
        {
          color: 'warning',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-warning/25 focus-visible:outline-3'
        },
        {
          color: 'error',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-error/25 focus-visible:outline-3'
        },
        {
          color: 'primary',
          highlight: true,
          class: 'ring ring-inset ring-primary'
        },
        {
          color: 'secondary',
          highlight: true,
          class: 'ring ring-inset ring-secondary'
        },
        {
          color: 'accent',
          highlight: true,
          class: 'ring ring-inset ring-accent'
        },
        {
          color: 'success',
          highlight: true,
          class: 'ring ring-inset ring-success'
        },
        {
          color: 'info',
          highlight: true,
          class: 'ring ring-inset ring-info'
        },
        {
          color: 'warning',
          highlight: true,
          class: 'ring ring-inset ring-warning'
        },
        {
          color: 'error',
          highlight: true,
          class: 'ring ring-inset ring-error'
        },
        {
          color: 'neutral',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-inverted/25 focus-visible:outline-3 focus-visible:ring-inverted'
        },
        {
          color: 'neutral',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-inverted/25 focus-visible:outline-3'
        },
        {
          color: 'neutral',
          highlight: true,
          class: 'ring ring-inset ring-inverted'
        },
        {
          orientation: 'horizontal',
          decrement: false,
          class: 'text-start'
        },
        {
          decrement: true,
          size: 'xs',
          class: 'ps-7'
        },
        {
          decrement: true,
          size: 'sm',
          class: 'ps-8'
        },
        {
          decrement: true,
          size: 'md',
          class: 'ps-9'
        },
        {
          decrement: true,
          size: 'lg',
          class: 'ps-10'
        },
        {
          decrement: true,
          size: 'xl',
          class: 'ps-11'
        },
        {
          increment: true,
          size: 'xs',
          class: 'pe-7'
        },
        {
          increment: true,
          size: 'sm',
          class: 'pe-8'
        },
        {
          increment: true,
          size: 'md',
          class: 'pe-9'
        },
        {
          increment: true,
          size: 'lg',
          class: 'pe-10'
        },
        {
          increment: true,
          size: 'xl',
          class: 'pe-11'
        },
        {
          fixed: false,
          size: 'xs',
          class: 'md:text-xs'
        },
        {
          fixed: false,
          size: 'sm',
          class: 'md:text-xs'
        },
        {
          fixed: false,
          size: 'md',
          class: 'md:text-sm'
        },
        {
          fixed: false,
          size: 'lg',
          class: 'md:text-sm'
        }
      ],
      defaultVariants: {
        size: 'md',
        color: 'primary',
        variant: 'outline'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/InputNumber.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/input-number.ts).


# InputRating

## Uso

Use a diretiva `v-model` para controlar o valor de avaliação do componente InputRating.

```vue
<script setup lang="ts">
const value = ref(3)
</script>

<template>
  <UInputRating v-model="value" />
</template>
```

Use a prop `default-value` para definir o valor inicial quando você não precisa controlar o estado.

```vue
<template>
  <UInputRating :default-value="3" />
</template>
```

### Etapa

Use a prop `step` para controlar a granularidade de cada estrela. Defina-a como `0.5` para permitir avaliações de meia estrela.

```vue
<template>
  <UInputRating :step="0.5" :default-value="3.5" />
</template>
```

### Comprimento

Use a prop `length` para definir o número de estrelas. O padrão é `5`.

```vue
<template>
  <UInputRating :length="10" :step="0.5" :default-value="7.5" />
</template>
```

### Limpável

Use a prop `clearable` para permitir que os usuários limpem a avaliação clicando no valor atualmente selecionado. O padrão é `false`.

```vue
<template>
  <UInputRating clearable :default-value="3" />
</template>
```

### Com hover

Use a prop `hoverable` para controlar se a avaliação mostra uma prévia do valor ao passar o mouse sobre as estrelas. O padrão é `false`.

```vue
<template>
  <UInputRating hoverable :default-value="3" />
</template>
```

### Ícone

Use a prop `icon` para personalizar o ícone usado para as estrelas. O padrão é `i-lucide-star`.

```vue
<template>
  <UInputRating icon="i-lucide-heart" :default-value="4" />
</template>
```

**Nuxt:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/nuxt#theme
>
> Você pode personalizar o ícone de estrela padrão globalmente no seu `app.config.ts` na chave `ui.icons.star`.

**Vue:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/vue#theme
>
> Você pode personalizar o ícone de estrela padrão globalmente no seu `vite.config.ts` na chave `ui.icons.star`.

### Ícone de vazio

Use a prop `empty-icon` para personalizar o ícone usado para as estrelas vazias. Se não for fornecido, usa o mesmo ícone de `icon`.

```vue
<template>
  <UInputRating empty-icon="i-ph-star" icon="i-ph-star-fill" :default-value="3" />
</template>
```

### Cor

Use a prop `color` para alterar a cor das estrelas preenchidas.

```vue
<template>
  <UInputRating color="neutral" :default-value="4" />
</template>
```

### Tamanho

Use a prop `size` para alterar o tamanho das estrelas.

```vue
<template>
  <UInputRating size="xl" :default-value="4" />
</template>
```

### Orientação

Use a prop `orientation` para alterar a orientação da avaliação. O padrão é `horizontal`.

```vue
<template>
  <UInputRating orientation="vertical" :default-value="4" />
</template>
```

### Desabilitado

Use a prop `disabled` para desabilitar o componente InputRating. Quando desabilitado, o componente tem opacidade reduzida (75%) e exibe um cursor `not-allowed` para indicar que não é interativo.

```vue
<template>
  <UInputRating disabled :default-value="3" />
</template>
```

### Somente leitura

Use a prop `readonly` para exibir uma avaliação sem permitir interação do usuário. Diferentemente de `disabled`, ela mantém a aparência normal (opacidade total, cursor padrão). Use quando você quiser exibir uma avaliação que não pode ser alterada, mas deve parecer normal.

```vue
<template>
  <UInputRating readonly :default-value="4.5" />
</template>
```

## API

### Props

```ts
/**
 * Props for the InputRating component
 */
interface InputRatingProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  /**
   * The id of the rating.
   */
  id?: string | undefined;
  /**
   * Make the rating readonly (non-interactive).
   * @default "false"
   */
  readonly?: boolean | undefined;
  /**
   * The icon displayed for each rating value.
   */
  icon?: any;
  /**
   * The icon displayed for empty rating values. Defaults to `icon` when not provided.
   */
  emptyIcon?: any;
  color?: "primary" | "secondary" | "accent" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
  size?: "xs" | "sm" | "md" | "lg" | "xl" | undefined;
  /**
   * The orientation of the rating.
   * @default "\"horizontal\""
   */
  orientation?: "horizontal" | "vertical" | undefined;
  ui?: { root?: SlotClass; item?: SlotClass; indicator?: SlotClass; icon?: SlotClass; emptyIcon?: SlotClass; } | undefined;
  /**
   * The granularity each rating item is divided into.
   * @default "1"
   */
  step?: 1 | 0.5 | 0.25 | 0.1 | undefined;
  /**
   * When `true`, prevents the user from interacting with radio items.
   */
  disabled?: boolean | undefined;
  /**
   * When `true`, indicates that the user must set the value before the owning form can be submitted.
   */
  required?: boolean | undefined;
  /**
   * The name of the field. Submitted with its owning form as part of a name/value pair.
   */
  name?: string | undefined;
  /**
   * The controlled rating value. Can be bound with `v-model`.
   */
  modelValue?: number | undefined;
  /**
   * The rating value when initially rendered. Use when you do not need to control the state of the rating.
   * @default "0"
   */
  defaultValue?: number | undefined;
  /**
   * The number of rating items to render.
   * @default "5"
   */
  length?: number | undefined;
  /**
   * When `true`, clicking the currently selected rating resets the value to `0`.
   * @default "false"
   */
  clearable?: boolean | undefined;
  /**
   * When `true`, the rating previews the value under the pointer on hover.
   * @default "false"
   */
  hoverable?: boolean | undefined;
}
```

### Slots

```ts
/**
 * Slots for the InputRating component
 */
interface InputRatingSlots {
  /**
   * Rendered for each item. `filled` is `false` for the empty background layer and `true` for the highlighted overlay.
   */
  item(): any;
}
```

### Emits

```ts
/**
 * Emitted events for the InputRating component
 */
interface InputRatingEmits {
  update:modelValue: (payload: [payload: number]) => void;
  change: (payload: [event: Event]) => void;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    inputRating: {
      slots: {
        root: '',
        item: [
          'relative inline-block cursor-pointer select-none rounded-sm has-focus-visible:outline-3',
          'transition'
        ],
        indicator: 'absolute inset-0 overflow-hidden outline-none text-transparent w-(--reka-rating-item-step-width) opacity-(--reka-rating-item-step-opacity) z-(--reka-rating-item-step-z-index)',
        icon: 'block',
        emptyIcon: 'block w-full h-full text-muted pointer-events-none'
      },
      variants: {
        orientation: {
          horizontal: {
            root: 'inline-flex items-center gap-0.5'
          },
          vertical: {
            root: 'inline-flex flex-col items-center gap-0.5'
          }
        },
        size: {
          xs: {
            item: 'size-3',
            icon: 'size-3'
          },
          sm: {
            item: 'size-4',
            icon: 'size-4'
          },
          md: {
            item: 'size-5',
            icon: 'size-5'
          },
          lg: {
            item: 'size-6',
            icon: 'size-6'
          },
          xl: {
            item: 'size-7',
            icon: 'size-7'
          }
        },
        color: {
          primary: {
            indicator: 'data-[state=active]:text-primary',
            item: 'outline-primary/25'
          },
          secondary: {
            indicator: 'data-[state=active]:text-secondary',
            item: 'outline-secondary/25'
          },
          accent: {
            indicator: 'data-[state=active]:text-accent',
            item: 'outline-accent/25'
          },
          success: {
            indicator: 'data-[state=active]:text-success',
            item: 'outline-success/25'
          },
          info: {
            indicator: 'data-[state=active]:text-info',
            item: 'outline-info/25'
          },
          warning: {
            indicator: 'data-[state=active]:text-warning',
            item: 'outline-warning/25'
          },
          error: {
            indicator: 'data-[state=active]:text-error',
            item: 'outline-error/25'
          },
          neutral: {
            indicator: 'data-[state=active]:text-highlighted',
            item: 'outline-inverted/25'
          }
        },
        readonly: {
          true: {
            root: 'cursor-default',
            item: 'cursor-default'
          },
          false: {}
        },
        disabled: {
          true: {
            root: 'opacity-75 cursor-not-allowed',
            item: 'cursor-not-allowed pointer-events-none'
          },
          false: {}
        }
      },
      compoundVariants: [
        {
          readonly: false,
          disabled: false,
          class: {
            item: 'hover:scale-110'
          }
        }
      ],
      defaultVariants: {
        color: 'primary',
        size: 'md'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/InputRating.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/input-rating.ts).


# InputTags

## Uso

Use a diretiva `v-model` para controlar o valor do InputTags.

```vue
<script setup lang="ts">
const value = ref([
  "Vue"
])
</script>

<template>
  <UInputTags v-model="value" />
</template>
```

Use a prop `default-value` para definir o valor inicial quando você não precisa controlar o estado.

```vue
<template>
  <UInputTags :default-value="[
  'Vue'
]" />
</template>
```

### Placeholder

Use a prop `placeholder` para definir um texto de placeholder.

```vue
<template>
  <UInputTags placeholder="Enter tags..." />
</template>
```

### Comprimento máximo

Use a prop `max-length` para definir o número máximo de caracteres permitidos em uma tag.

```vue
<template>
  <UInputTags :max-length="4" />
</template>
```

### Cor

Use a prop `color` para alterar a cor do ring quando o InputTags está em foco.

```vue
<script setup lang="ts">
const value = ref([
  "Vue"
])
</script>

<template>
  <UInputTags v-model="value" color="neutral" highlight />
</template>
```

> \[!NOTE]
>
> A prop `highlight` é usada aqui para mostrar o estado de foco. Ela é usada internamente quando ocorre um erro de validação.

### Variantes

Use a prop `variant` para alterar a aparência do InputTags.

```vue
<script setup lang="ts">
const value = ref([
  "Vue"
])
</script>

<template>
  <UInputTags v-model="value" variant="subtle" color="neutral" :highlight="false" />
</template>
```

### Tamanhos

Use a prop `size` para ajustar o tamanho do InputTags.

```vue
<script setup lang="ts">
const value = ref([
  "Vue"
])
</script>

<template>
  <UInputTags v-model="value" size="xl" />
</template>
```

### Ícone

Use a prop `icon` para exibir um [Icon](https://ui.nitro.news/docs/components/icon) dentro do InputTags.

```vue
<script setup lang="ts">
const value = ref([
  "Vue"
])
</script>

<template>
  <UInputTags v-model="value" icon="i-lucide-search" size="md" variant="outline" />
</template>
```

> \[!NOTE]
>
> Use as props `leading` e `trailing` para definir a posição do ícone ou as props `leading-icon` e `trailing-icon` para definir um ícone diferente para cada posição.

### Avatar

Use a prop `avatar` para exibir um [Avatar](https://ui.nitro.news/docs/components/avatar) dentro do InputTags.

```vue
<script setup lang="ts">
const value = ref([
  "Vue"
])
</script>

<template>
  <UInputTags v-model="value" :avatar="{
  src: 'https://github.com/vuejs.png',
  loading: 'lazy'
}" size="md" variant="outline" />
</template>
```

### Ícone de excluir

Use a prop `delete-icon` para personalizar o [Icon](https://ui.nitro.news/docs/components/icon) de exclusão nas tags. O padrão é `i-lucide-x`.

```vue
<script setup lang="ts">
const value = ref([
  "Vue"
])
</script>

<template>
  <UInputTags v-model="value" delete-icon="i-lucide-trash" />
</template>
```

**Nuxt:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/nuxt#theme
>
> Você pode personalizar esse ícone globalmente no seu `app.config.ts` na chave `ui.icons.close`.

**Vue:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/vue#theme
>
> Você pode personalizar esse ícone globalmente no seu `vite.config.ts` na chave `ui.icons.close`.

### Carregando

Use a prop `loading` para exibir um ícone de carregamento no InputTags.

```vue
<script setup lang="ts">
const value = ref([
  "Vue"
])
</script>

<template>
  <UInputTags v-model="value" loading :trailing="false" />
</template>
```

### Ícone de carregamento

Use a prop `loading-icon` para personalizar o ícone de carregamento. O padrão é `i-lucide-loader-circle`.

```vue
<script setup lang="ts">
const value = ref([
  "Vue"
])
</script>

<template>
  <UInputTags v-model="value" loading loading-icon="i-lucide-loader" />
</template>
```

**Nuxt:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/nuxt#theme
>
> Você pode personalizar esse ícone globalmente no seu `app.config.ts` na chave `ui.icons.loading`.

**Vue:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/vue#theme
>
> Você pode personalizar esse ícone globalmente no seu `vite.config.ts` na chave `ui.icons.loading`.

### Desabilitado

Use a prop `disabled` para desabilitar o InputTags.

```vue
<script setup lang="ts">
const value = ref([
  "Vue"
])
</script>

<template>
  <UInputTags v-model="value" disabled />
</template>
```

## Exemplos

### Dentro de um FormField

Você pode usar o InputTags dentro de um componente [FormField](https://ui.nitro.news/docs/components/form-field) para exibir um rótulo, texto de ajuda, indicador de obrigatório, etc.

:component-example{name="input-tags-form-field-example"}

## API

### Props

```ts
/**
 * Props for the InputTags component
 */
interface InputTagsProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  /**
   * The placeholder text when the input is empty.
   */
  placeholder?: string | undefined;
  /**
   * The maximum number of character allowed.
   */
  maxLength?: number | undefined;
  color?: "primary" | "secondary" | "accent" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
  variant?: "outline" | "soft" | "subtle" | "ghost" | "none" | undefined;
  size?: "xs" | "sm" | "md" | "lg" | "xl" | undefined;
  autofocus?: boolean | undefined;
  /**
   * @default "0"
   */
  autofocusDelay?: number | undefined;
  /**
   * The icon displayed to delete a tag.
   */
  deleteIcon?: any;
  /**
   * Highlight the ring color like a focus state.
   */
  highlight?: boolean | undefined;
  /**
   * Keep the mobile text size on all breakpoints.
   */
  fixed?: boolean | undefined;
  ui?: { root?: SlotClass; base?: SlotClass; leading?: SlotClass; leadingIcon?: SlotClass; leadingAvatar?: SlotClass; leadingAvatarSize?: SlotClass; trailing?: SlotClass; trailingIcon?: SlotClass; item?: SlotClass; itemText?: SlotClass; itemDelete?: SlotClass; itemDeleteIcon?: SlotClass; input?: SlotClass; } | undefined;
  /**
   * The controlled value of the tags input. Can be bind as `v-model`.
   */
  modelValue?: T[] | null | undefined;
  /**
   * The value of the tags that should be added. Use when you do not need to control the state of the tags input
   */
  defaultValue?: T[] | undefined;
  /**
   * When `true`, allow adding tags on paste. Work in conjunction with delimiter prop.
   */
  addOnPaste?: boolean | undefined;
  /**
   * When `true` allow adding tags on tab keydown
   */
  addOnTab?: boolean | undefined;
  /**
   * When `true` allow adding tags blur input
   */
  addOnBlur?: boolean | undefined;
  /**
   * When `true`, allow duplicated tags.
   */
  duplicate?: boolean | undefined;
  /**
   * When `true`, prevents the user from interacting with the tags input.
   */
  disabled?: boolean | undefined;
  /**
   * The character or regular expression to trigger the addition of a new tag. Also used to split tags for `@paste` event
   */
  delimiter?: string | RegExp | undefined;
  /**
   * Maximum number of tags.
   */
  max?: number | undefined;
  id?: string | undefined;
  /**
   * Convert the input value to the desired type. Mandatory when using objects as values and using `TagsInputInput`
   */
  convertValue?: ((value: string) => T) | undefined;
  /**
   * Display the value of the tag. Useful when you want to apply modifications to the value like adding a suffix or when using object as values
   */
  displayValue?: ((value: T) => string) | undefined;
  /**
   * The name of the field. Submitted with its owning form as part of a name/value pair.
   */
  name?: string | undefined;
  /**
   * When `true`, indicates that the user must set the value before the owning form can be submitted.
   */
  required?: boolean | undefined;
  /**
   * Display an icon based on the `leading` and `trailing` props.
   */
  icon?: any;
  /**
   * Display an avatar on the left side.
   */
  avatar?: AvatarProps | undefined;
  /**
   * When `true`, the icon will be displayed on the left side.
   */
  leading?: boolean | undefined;
  /**
   * Display an icon on the left side.
   */
  leadingIcon?: any;
  /**
   * When `true`, the icon will be displayed on the right side.
   */
  trailing?: boolean | undefined;
  /**
   * Display an icon on the right side.
   */
  trailingIcon?: any;
  /**
   * When `true`, the loading icon will be displayed.
   */
  loading?: boolean | undefined;
  /**
   * The icon when the `loading` prop is `true`.
   */
  loadingIcon?: any;
  enterKeyHint?: "enter" | "done" | "go" | "next" | "previous" | "search" | "send" | undefined;
  form?: string | undefined;
  formaction?: string | undefined;
  formenctype?: string | undefined;
  formmethod?: string | undefined;
  formnovalidate?: Booleanish | undefined;
  formtarget?: string | undefined;
  list?: string | undefined;
  readonly?: Booleanish | undefined;
  autocomplete?: "on" | "off" | (string & {}) | undefined;
}
```

> \[!NOTE]
> See: https\://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#attributes
>
> Este componente também suporta todos os atributos HTML nativos de `<input>`.

### Slots

```ts
/**
 * Slots for the InputTags component
 */
interface InputTagsSlots {
  leading(): any;
  default(): any;
  trailing(): any;
  item-text(): any;
  item-delete(): any;
}
```

### Emits

```ts
/**
 * Emitted events for the InputTags component
 */
interface InputTagsEmits {
  change: (payload: [event: Event]) => void;
  blur: (payload: [event: FocusEvent]) => void;
  focus: (payload: [event: FocusEvent]) => void;
  update:modelValue: (payload: [payload: T[]]) => void;
  invalid: (payload: [payload: T]) => void;
  addTag: (payload: [payload: T]) => void;
  removeTag: (payload: [payload: T]) => void;
}
```

### Expose

Ao acessar o componente por meio de um template ref, você pode usar o seguinte:

| Name                                                                                                                           | Type                                                                                                                                               |
| ------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `inputRef`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | `Ref<HTMLInputElement | null>`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} |

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    inputTags: {
      slots: {
        root: [
          'relative inline-flex items-center',
          'flex-wrap'
        ],
        base: [
          'rounded-md',
          'transition-colors'
        ],
        leading: 'absolute inset-y-0 start-0 flex items-center',
        leadingIcon: 'shrink-0 text-dimmed',
        leadingAvatar: 'shrink-0',
        leadingAvatarSize: '',
        trailing: 'absolute inset-y-0 end-0 flex items-center',
        trailingIcon: 'shrink-0 text-dimmed',
        item: 'px-1.5 py-0.5 rounded-sm font-medium inline-flex items-center gap-0.5 ring ring-inset ring-accented bg-elevated text-default data-disabled:cursor-not-allowed data-disabled:opacity-75 wrap-anywhere data-[state="active"]:bg-accented',
        itemText: '',
        itemDelete: [
          'inline-flex items-center rounded-xs text-dimmed hover:text-default hover:bg-accented/75 disabled:pointer-events-none',
          'transition-colors'
        ],
        itemDeleteIcon: 'shrink-0',
        input: 'flex-1 border-0 bg-transparent placeholder:text-dimmed focus:outline-none disabled:cursor-not-allowed disabled:opacity-75'
      },
      variants: {
        fieldGroup: {
          horizontal: 'not-only:first:rounded-e-none not-only:last:rounded-s-none not-last:not-first:rounded-none focus-visible:z-[1]',
          vertical: 'not-only:first:rounded-b-none not-only:last:rounded-t-none not-last:not-first:rounded-none focus-visible:z-[1]'
        },
        size: {
          xs: {
            base: 'px-2 py-1 text-sm/4 gap-1',
            leading: 'ps-2',
            trailing: 'pe-2',
            leadingIcon: 'size-4',
            leadingAvatarSize: '3xs',
            trailingIcon: 'size-4',
            item: 'text-[10px]/3',
            itemDeleteIcon: 'size-3'
          },
          sm: {
            base: 'px-2.5 py-1.5 text-sm/4 gap-1.5',
            leading: 'ps-2.5',
            trailing: 'pe-2.5',
            leadingIcon: 'size-4',
            leadingAvatarSize: '3xs',
            trailingIcon: 'size-4',
            item: 'text-[10px]/3',
            itemDeleteIcon: 'size-3'
          },
          md: {
            base: 'px-2.5 py-1.5 text-base/5 gap-1.5',
            leading: 'ps-2.5',
            trailing: 'pe-2.5',
            leadingIcon: 'size-5',
            leadingAvatarSize: '2xs',
            trailingIcon: 'size-5',
            item: 'text-xs',
            itemDeleteIcon: 'size-3.5'
          },
          lg: {
            base: 'px-3 py-2 text-base/5 gap-2',
            leading: 'ps-3',
            trailing: 'pe-3',
            leadingIcon: 'size-5',
            leadingAvatarSize: '2xs',
            trailingIcon: 'size-5',
            item: 'text-xs',
            itemDeleteIcon: 'size-3.5'
          },
          xl: {
            base: 'px-3 py-2 text-base gap-2',
            leading: 'ps-3',
            trailing: 'pe-3',
            leadingIcon: 'size-6',
            leadingAvatarSize: 'xs',
            trailingIcon: 'size-6',
            item: 'text-sm',
            itemDeleteIcon: 'size-4'
          }
        },
        variant: {
          outline: 'text-highlighted bg-default ring ring-inset ring-accented',
          soft: 'text-highlighted bg-elevated/50 hover:bg-elevated has-focus:bg-elevated disabled:bg-elevated/50',
          subtle: 'text-highlighted bg-elevated ring ring-inset ring-accented',
          ghost: 'text-highlighted bg-transparent hover:bg-elevated has-focus:bg-elevated disabled:bg-transparent dark:disabled:bg-transparent',
          none: 'text-highlighted bg-transparent has-focus:outline-none'
        },
        color: {
          primary: '',
          secondary: '',
          accent: '',
          success: '',
          info: '',
          warning: '',
          error: '',
          neutral: ''
        },
        leading: {
          true: ''
        },
        trailing: {
          true: ''
        },
        loading: {
          true: ''
        },
        highlight: {
          true: ''
        },
        fixed: {
          false: ''
        },
        type: {
          file: 'file:me-1.5 file:font-medium file:text-muted file:outline-none'
        }
      },
      compoundVariants: [
        {
          color: 'primary',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-primary/25 has-focus-visible:outline-3 has-focus-visible:ring-primary'
        },
        {
          color: 'secondary',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-secondary/25 has-focus-visible:outline-3 has-focus-visible:ring-secondary'
        },
        {
          color: 'accent',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-accent/25 has-focus-visible:outline-3 has-focus-visible:ring-accent'
        },
        {
          color: 'success',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-success/25 has-focus-visible:outline-3 has-focus-visible:ring-success'
        },
        {
          color: 'info',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-info/25 has-focus-visible:outline-3 has-focus-visible:ring-info'
        },
        {
          color: 'warning',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-warning/25 has-focus-visible:outline-3 has-focus-visible:ring-warning'
        },
        {
          color: 'error',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-error/25 has-focus-visible:outline-3 has-focus-visible:ring-error'
        },
        {
          color: 'primary',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-primary/25 has-focus-visible:outline-3'
        },
        {
          color: 'secondary',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-secondary/25 has-focus-visible:outline-3'
        },
        {
          color: 'accent',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-accent/25 has-focus-visible:outline-3'
        },
        {
          color: 'success',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-success/25 has-focus-visible:outline-3'
        },
        {
          color: 'info',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-info/25 has-focus-visible:outline-3'
        },
        {
          color: 'warning',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-warning/25 has-focus-visible:outline-3'
        },
        {
          color: 'error',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-error/25 has-focus-visible:outline-3'
        },
        {
          color: 'primary',
          highlight: true,
          class: 'ring ring-inset ring-primary'
        },
        {
          color: 'secondary',
          highlight: true,
          class: 'ring ring-inset ring-secondary'
        },
        {
          color: 'accent',
          highlight: true,
          class: 'ring ring-inset ring-accent'
        },
        {
          color: 'success',
          highlight: true,
          class: 'ring ring-inset ring-success'
        },
        {
          color: 'info',
          highlight: true,
          class: 'ring ring-inset ring-info'
        },
        {
          color: 'warning',
          highlight: true,
          class: 'ring ring-inset ring-warning'
        },
        {
          color: 'error',
          highlight: true,
          class: 'ring ring-inset ring-error'
        },
        {
          color: 'neutral',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-inverted/25 has-focus-visible:outline-3 has-focus-visible:ring-inverted'
        },
        {
          color: 'neutral',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-inverted/25 has-focus-visible:outline-3'
        },
        {
          color: 'neutral',
          highlight: true,
          class: 'ring ring-inset ring-inverted'
        },
        {
          leading: true,
          size: 'xs',
          class: 'ps-7'
        },
        {
          leading: true,
          size: 'sm',
          class: 'ps-8'
        },
        {
          leading: true,
          size: 'md',
          class: 'ps-9'
        },
        {
          leading: true,
          size: 'lg',
          class: 'ps-10'
        },
        {
          leading: true,
          size: 'xl',
          class: 'ps-11'
        },
        {
          trailing: true,
          size: 'xs',
          class: 'pe-7'
        },
        {
          trailing: true,
          size: 'sm',
          class: 'pe-8'
        },
        {
          trailing: true,
          size: 'md',
          class: 'pe-9'
        },
        {
          trailing: true,
          size: 'lg',
          class: 'pe-10'
        },
        {
          trailing: true,
          size: 'xl',
          class: 'pe-11'
        },
        {
          loading: true,
          leading: true,
          class: {
            leadingIcon: 'animate-spin'
          }
        },
        {
          loading: true,
          leading: false,
          trailing: true,
          class: {
            trailingIcon: 'animate-spin'
          }
        },
        {
          fixed: false,
          size: 'xs',
          class: 'md:text-xs'
        },
        {
          fixed: false,
          size: 'sm',
          class: 'md:text-xs'
        },
        {
          fixed: false,
          size: 'md',
          class: 'md:text-sm'
        },
        {
          fixed: false,
          size: 'lg',
          class: 'md:text-sm'
        }
      ],
      defaultVariants: {
        size: 'md',
        color: 'accent',
        variant: 'outline'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/InputTags.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/input-tags.ts).


# InputTime

## Uso

Use a diretiva `v-model` para controlar o horário selecionado.

```vue
<script setup lang="ts">
import { Time } from '@internationalized/date'

const value = shallowRef(new Time(12, 30, 0))
</script>

<template>
  <UInputTime v-model="value" />
</template>
```

Use a prop `default-value` para definir o valor inicial quando você não precisa controlar o estado.

```vue
<script setup lang="ts">
import { Time } from '@internationalized/date'

const defaultValue = shallowRef(new Time(9, 45, 0))
</script>

<template>
  <UInputTime :default-value="defaultValue" />
</template>
```

**Nuxt:**

> \[!NOTE]
> See: /docs/getting-started/integrations/i18n/nuxt#locale
>
> Este componente usa o pacote `@internationalized/date` para formatação sensível ao locale. O formato da hora é determinado pela prop `locale` do componente App.

**Vue:**

> \[!NOTE]
> See: /docs/getting-started/integrations/i18n/vue#locale
>
> Este componente usa o pacote `@internationalized/date` para formatação sensível ao locale. O formato da hora é determinado pela prop `locale` do componente App.

### Intervalo

Use a prop `range` para habilitar a seleção de intervalo de horários, com horário inicial e final.

```vue
<script setup lang="ts">
import { Time } from '@internationalized/date'

const value = shallowRef({ start: new Time(9, 0, 0), end: new Time(17, 30, 0) })
</script>

<template>
  <UInputTime range v-model="value" />
</template>
```

### Ciclo de horas

Use a prop `hour-cycle` para alterar o ciclo de horas do InputTime. O padrão é `12`.

```vue
<script setup lang="ts">
import { Time } from '@internationalized/date'

const defaultValue = shallowRef(new Time(16, 30, 0))
</script>

<template>
  <UInputTime :hour-cycle="24" :default-value="defaultValue" />
</template>
```

### Cor

Use a prop `color` para alterar a cor do InputTime.

```vue
<template>
  <UInputTime color="neutral" highlight />
</template>
```

> \[!NOTE]
>
> A prop `highlight` é usada aqui para mostrar o estado de foco. Ela é usada internamente quando ocorre um erro de validação.

### Variante

Use a prop `variant` para alterar a variante do InputTime.

```vue
<template>
  <UInputTime variant="subtle" />
</template>
```

### Tamanho

Use a prop `size` para alterar o tamanho do InputTime.

```vue
<template>
  <UInputTime size="xl" />
</template>
```

### Ícone

Use a prop `icon` para exibir um [Icon](https://ui.nitro.news/docs/components/icon) dentro do InputTime.

```vue
<template>
  <UInputTime icon="i-lucide-clock" />
</template>
```

> \[!NOTE]
>
> Use as props `leading` e `trailing` para definir a posição do ícone ou as props `leading-icon` e `trailing-icon` para definir um ícone diferente para cada posição.

### Ícone de separador

Use a prop `separator-icon` para alterar o [Icon](https://ui.nitro.news/docs/components/icon) do separador de intervalo. O padrão é `i-lucide-minus`.

```vue
<template>
  <UInputTime range separator-icon="i-lucide-arrow-right" />
</template>
```

**Nuxt:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/nuxt#theme
>
> Você pode personalizar esse ícone globalmente no seu `app.config.ts` na chave `ui.icons.minus`.

**Vue:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/vue#theme
>
> Você pode personalizar esse ícone globalmente no seu `vite.config.ts` na chave `ui.icons.minus`.

### Avatar

Use a prop `avatar` para exibir um [Avatar](https://ui.nitro.news/docs/components/avatar) dentro do InputTime.

```vue
<template>
  <UInputTime :avatar="{
  src: 'https://github.com/vuejs.png',
  loading: 'lazy'
}" size="md" variant="outline" />
</template>
```

### Desabilitado

Use a prop `disabled` para desabilitar o InputTime.

```vue
<template>
  <UInputTime disabled />
</template>
```

## Exemplos

### Dentro de um FormField

Você pode usar o InputTime dentro de um componente [FormField](https://ui.nitro.news/docs/components/form-field) para exibir um rótulo, texto de ajuda, indicador de obrigatório, etc.

:component-example{name="input-time-form-field-example"}

## API

### Props

```ts
/**
 * Props for the InputTime component
 */
interface InputTimeProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  color?: "primary" | "secondary" | "accent" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
  variant?: "outline" | "soft" | "subtle" | "ghost" | "none" | undefined;
  size?: "xs" | "sm" | "md" | "lg" | "xl" | undefined;
  /**
   * Highlight the ring color like a focus state.
   */
  highlight?: boolean | undefined;
  /**
   * Keep the mobile text size on all breakpoints.
   */
  fixed?: boolean | undefined;
  autofocus?: boolean | undefined;
  /**
   * @default "0"
   */
  autofocusDelay?: number | undefined;
  /**
   * The icon to use as a range separator.
   */
  separatorIcon?: any;
  /**
   * Enable time range selection.
   */
  range?: R | undefined;
  defaultValue?: Time | CalendarDateTime | ZonedDateTime;
  modelValue?: null | Time | CalendarDateTime | ZonedDateTime;
  ui?: { base?: SlotClass; leading?: SlotClass; leadingIcon?: SlotClass; leadingAvatar?: SlotClass; leadingAvatarSize?: SlotClass; trailing?: SlotClass; trailingIcon?: SlotClass; segment?: SlotClass; separatorIcon?: SlotClass; } | undefined;
  /**
   * Display an icon based on the `leading` and `trailing` props.
   */
  icon?: any;
  /**
   * Display an avatar on the left side.
   */
  avatar?: AvatarProps | undefined;
  /**
   * When `true`, the icon will be displayed on the left side.
   */
  leading?: boolean | undefined;
  /**
   * Display an icon on the left side.
   */
  leadingIcon?: any;
  /**
   * When `true`, the icon will be displayed on the right side.
   */
  trailing?: boolean | undefined;
  /**
   * Display an icon on the right side.
   */
  trailingIcon?: any;
  /**
   * When `true`, the loading icon will be displayed.
   */
  loading?: boolean | undefined;
  /**
   * The icon when the `loading` prop is `true`.
   */
  loadingIcon?: any;
  defaultPlaceholder?: Time | CalendarDateTime | ZonedDateTime;
  placeholder?: Time | CalendarDateTime | ZonedDateTime;
  /**
   * The hour cycle used for formatting times. Defaults to the local preference
   */
  hourCycle?: HourCycle;
  /**
   * The stepping interval for the time fields. Defaults to `1`.
   */
  step?: DateStep | undefined;
  /**
   * Whether to enforce snapping the value to the nearest step increment after input. Defaults to `false`.
   */
  stepSnapping?: boolean | undefined;
  /**
   * The granularity to use for formatting times. Defaults to minute if a Time is provided, otherwise defaults to minute. The field will render segments for each part of the date up to and including the specified granularity
   */
  granularity?: "hour" | "minute" | "second" | undefined;
  /**
   * Whether or not to hide the time zone segment of the field
   */
  hideTimeZone?: boolean | undefined;
  maxValue?: Time | CalendarDateTime | ZonedDateTime;
  minValue?: Time | CalendarDateTime | ZonedDateTime;
  /**
   * The locale to use for formatting dates
   */
  locale?: string | undefined;
  /**
   * Whether or not the time field is disabled
   */
  disabled?: boolean | undefined;
  /**
   * Whether or not the time field is readonly
   */
  readonly?: boolean | undefined;
  /**
   * Id of the element
   */
  id?: string | undefined;
  /**
   * The name of the field. Submitted with its owning form as part of a name/value pair.
   */
  name?: string | undefined;
  /**
   * When `true`, indicates that the user must set the value before the owning form can be submitted.
   */
  required?: boolean | undefined;
  /**
   * A function that returns whether or not a time is unavailable
   */
  isTimeUnavailable?: Matcher | undefined;
}
```

### Slots

```ts
/**
 * Slots for the InputTime component
 */
interface InputTimeSlots {
  leading(): any;
  default(): any;
  trailing(): any;
  separator(): any;
}
```

### Emits

```ts
/**
 * Emitted events for the InputTime component
 */
interface InputTimeEmits {
  update:modelValue: (payload: [value: InputTimeModelValue<R>]) => void;
  update:placeholder: (payload: [date: TimeValue] & [date: TimeValue]) => void;
  change: (payload: [event: Event]) => void;
  blur: (payload: [event: FocusEvent]) => void;
  focus: (payload: [event: FocusEvent]) => void;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    inputTime: {
      slots: {
        base: [
          'group relative inline-flex items-center rounded-md select-none',
          'transition-colors'
        ],
        leading: 'absolute inset-y-0 start-0 flex items-center',
        leadingIcon: 'shrink-0 text-dimmed',
        leadingAvatar: 'shrink-0',
        leadingAvatarSize: '',
        trailing: 'absolute inset-y-0 end-0 flex items-center',
        trailingIcon: 'shrink-0 text-dimmed',
        segment: [
          'rounded text-center outline-hidden data-placeholder:text-dimmed data-[segment=literal]:text-muted data-invalid:text-error data-disabled:cursor-not-allowed data-disabled:opacity-75',
          'transition-colors'
        ],
        separatorIcon: 'shrink-0 size-4 text-muted'
      },
      variants: {
        fieldGroup: {
          horizontal: 'not-only:first:rounded-e-none not-only:last:rounded-s-none not-last:not-first:rounded-none focus-visible:z-[1]',
          vertical: 'not-only:first:rounded-b-none not-only:last:rounded-t-none not-last:not-first:rounded-none focus-visible:z-[1]'
        },
        size: {
          xs: {
            base: [
              'px-2 py-1 text-sm/4 gap-1',
              'gap-0.25'
            ],
            leading: 'ps-2',
            trailing: 'pe-2',
            leadingIcon: 'size-4',
            leadingAvatarSize: '3xs',
            trailingIcon: 'size-4',
            segment: 'not-data-[segment=literal]:w-8'
          },
          sm: {
            base: [
              'px-2.5 py-1.5 text-sm/4 gap-1.5',
              'gap-0.5'
            ],
            leading: 'ps-2.5',
            trailing: 'pe-2.5',
            leadingIcon: 'size-4',
            leadingAvatarSize: '3xs',
            trailingIcon: 'size-4',
            segment: 'not-data-[segment=literal]:w-8'
          },
          md: {
            base: [
              'px-2.5 py-1.5 text-base/5 gap-1.5',
              'gap-0.5'
            ],
            leading: 'ps-2.5',
            trailing: 'pe-2.5',
            leadingIcon: 'size-5',
            leadingAvatarSize: '2xs',
            trailingIcon: 'size-5',
            segment: 'not-data-[segment=literal]:w-9'
          },
          lg: {
            base: [
              'px-3 py-2 text-base/5 gap-2',
              'gap-0.75'
            ],
            leading: 'ps-3',
            trailing: 'pe-3',
            leadingIcon: 'size-5',
            leadingAvatarSize: '2xs',
            trailingIcon: 'size-5',
            segment: 'not-data-[segment=literal]:w-9'
          },
          xl: {
            base: [
              'px-3 py-2 text-base gap-2',
              'gap-0.75'
            ],
            leading: 'ps-3',
            trailing: 'pe-3',
            leadingIcon: 'size-6',
            leadingAvatarSize: 'xs',
            trailingIcon: 'size-6',
            segment: 'not-data-[segment=literal]:w-10'
          }
        },
        variant: {
          outline: 'text-highlighted bg-default ring ring-inset ring-accented',
          soft: 'text-highlighted bg-elevated/50 hover:bg-elevated has-focus:bg-elevated disabled:bg-elevated/50',
          subtle: 'text-highlighted bg-elevated ring ring-inset ring-accented',
          ghost: 'text-highlighted bg-transparent hover:bg-elevated has-focus:bg-elevated disabled:bg-transparent dark:disabled:bg-transparent',
          none: 'text-highlighted bg-transparent has-focus:outline-none'
        },
        color: {
          primary: '',
          secondary: '',
          accent: '',
          success: '',
          info: '',
          warning: '',
          error: '',
          neutral: ''
        },
        leading: {
          true: ''
        },
        trailing: {
          true: ''
        },
        loading: {
          true: ''
        },
        highlight: {
          true: ''
        },
        fixed: {
          false: ''
        },
        type: {
          file: 'file:me-1.5 file:font-medium file:text-muted file:outline-none'
        }
      },
      compoundVariants: [
        {
          color: 'primary',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-primary/25 has-focus-visible:outline-3 has-focus-visible:ring-primary'
        },
        {
          color: 'secondary',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-secondary/25 has-focus-visible:outline-3 has-focus-visible:ring-secondary'
        },
        {
          color: 'accent',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-accent/25 has-focus-visible:outline-3 has-focus-visible:ring-accent'
        },
        {
          color: 'success',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-success/25 has-focus-visible:outline-3 has-focus-visible:ring-success'
        },
        {
          color: 'info',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-info/25 has-focus-visible:outline-3 has-focus-visible:ring-info'
        },
        {
          color: 'warning',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-warning/25 has-focus-visible:outline-3 has-focus-visible:ring-warning'
        },
        {
          color: 'error',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-error/25 has-focus-visible:outline-3 has-focus-visible:ring-error'
        },
        {
          color: 'primary',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-primary/25 has-focus-visible:outline-3'
        },
        {
          color: 'secondary',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-secondary/25 has-focus-visible:outline-3'
        },
        {
          color: 'accent',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-accent/25 has-focus-visible:outline-3'
        },
        {
          color: 'success',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-success/25 has-focus-visible:outline-3'
        },
        {
          color: 'info',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-info/25 has-focus-visible:outline-3'
        },
        {
          color: 'warning',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-warning/25 has-focus-visible:outline-3'
        },
        {
          color: 'error',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-error/25 has-focus-visible:outline-3'
        },
        {
          color: 'primary',
          highlight: true,
          class: 'ring ring-inset ring-primary'
        },
        {
          color: 'secondary',
          highlight: true,
          class: 'ring ring-inset ring-secondary'
        },
        {
          color: 'accent',
          highlight: true,
          class: 'ring ring-inset ring-accent'
        },
        {
          color: 'success',
          highlight: true,
          class: 'ring ring-inset ring-success'
        },
        {
          color: 'info',
          highlight: true,
          class: 'ring ring-inset ring-info'
        },
        {
          color: 'warning',
          highlight: true,
          class: 'ring ring-inset ring-warning'
        },
        {
          color: 'error',
          highlight: true,
          class: 'ring ring-inset ring-error'
        },
        {
          color: 'neutral',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-inverted/25 has-focus-visible:outline-3 has-focus-visible:ring-inverted'
        },
        {
          color: 'neutral',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-inverted/25 has-focus-visible:outline-3'
        },
        {
          color: 'neutral',
          highlight: true,
          class: 'ring ring-inset ring-inverted'
        },
        {
          leading: true,
          size: 'xs',
          class: 'ps-7'
        },
        {
          leading: true,
          size: 'sm',
          class: 'ps-8'
        },
        {
          leading: true,
          size: 'md',
          class: 'ps-9'
        },
        {
          leading: true,
          size: 'lg',
          class: 'ps-10'
        },
        {
          leading: true,
          size: 'xl',
          class: 'ps-11'
        },
        {
          trailing: true,
          size: 'xs',
          class: 'pe-7'
        },
        {
          trailing: true,
          size: 'sm',
          class: 'pe-8'
        },
        {
          trailing: true,
          size: 'md',
          class: 'pe-9'
        },
        {
          trailing: true,
          size: 'lg',
          class: 'pe-10'
        },
        {
          trailing: true,
          size: 'xl',
          class: 'pe-11'
        },
        {
          loading: true,
          leading: true,
          class: {
            leadingIcon: 'animate-spin'
          }
        },
        {
          loading: true,
          leading: false,
          trailing: true,
          class: {
            trailingIcon: 'animate-spin'
          }
        },
        {
          fixed: false,
          size: 'xs',
          class: 'md:text-xs'
        },
        {
          fixed: false,
          size: 'sm',
          class: 'md:text-xs'
        },
        {
          fixed: false,
          size: 'md',
          class: 'md:text-sm'
        },
        {
          fixed: false,
          size: 'lg',
          class: 'md:text-sm'
        },
        {
          variant: 'outline',
          class: {
            segment: 'focus:bg-elevated'
          }
        },
        {
          variant: 'soft',
          class: {
            segment: 'focus:bg-accented/50 group-hover:focus:bg-accented'
          }
        },
        {
          variant: 'subtle',
          class: {
            segment: 'focus:bg-accented'
          }
        },
        {
          variant: 'ghost',
          class: {
            segment: 'focus:bg-elevated group-hover:focus:bg-accented'
          }
        },
        {
          variant: 'none',
          class: {
            segment: 'focus:bg-elevated'
          }
        }
      ],
      defaultVariants: {
        size: 'md',
        color: 'accent',
        variant: 'outline'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/InputTime.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/input-time.ts).


# Kbd

## Uso

Use o slot padrão para definir o valor do Kbd.

```vue
<template>
  <UKbd>
    K
  </UKbd>
</template>
```

### Valor

Use a prop `value` para definir o valor do Kbd.

```vue
<template>
  <UKbd value="K" />
</template>
```

Você pode passar teclas especiais para a prop `value`, que passam pelo composable [`useKbd`](https://gitlab.nitro.news/nitro/ui/-/blob/main/src/runtime/composables/useKbd.ts){rel="&#x22;nofollow&#x22;"}. Por exemplo, a tecla `meta` é exibida como `⌘` no macOS e `Ctrl` em outras plataformas.

```vue
<template>
  <UKbd value="meta" />
</template>
```

### Cor

Use a prop `color` para alterar a cor do Kbd.

```vue
<template>
  <UKbd color="neutral">
    K
  </UKbd>
</template>
```

### Variante

Use a prop `variant` para alterar a variante do Kbd.

```vue
<template>
  <UKbd color="neutral" variant="solid">
    K
  </UKbd>
</template>
```

### Tamanho

Use a prop `size` para alterar o tamanho do Kbd.

```vue
<template>
  <UKbd size="lg">
    K
  </UKbd>
</template>
```

## Exemplos

### `class` prop

Use a prop `class` para sobrescrever os estilos base do Badge.

```vue
<template>
  <UKbd class="font-bold rounded-full" variant="subtle">
    K
  </UKbd>
</template>
```

## API

### Props

```ts
/**
 * Props for the Kbd component
 */
interface KbdProps {
  /**
   * The element or component this component should render as.
   * @default "\"kbd\""
   */
  as?: any;
  value?: string | undefined;
  color?: "neutral" | undefined;
  variant?: "outline" | "soft" | "subtle" | "solid" | undefined;
  size?: "sm" | "md" | "lg" | undefined;
}
```

### Slots

```ts
/**
 * Slots for the Kbd component
 */
interface KbdSlots {
  default(): any;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    kbd: {
      base: 'inline-flex items-center justify-center px-1 rounded-sm font-medium font-sans uppercase',
      variants: {
        color: {
          neutral: ''
        },
        variant: {
          solid: '',
          outline: '',
          soft: '',
          subtle: ''
        },
        size: {
          sm: 'h-4 min-w-[16px] text-[10px]',
          md: 'h-5 min-w-[20px] text-[11px]',
          lg: 'h-6 min-w-[24px] text-[12px]'
        }
      },
      compoundVariants: [
        {
          color: 'neutral',
          variant: 'solid',
          class: 'text-inverted bg-inverted'
        },
        {
          color: 'neutral',
          variant: 'outline',
          class: 'ring ring-inset ring-accented text-default bg-default'
        },
        {
          color: 'neutral',
          variant: 'soft',
          class: 'text-default bg-elevated'
        },
        {
          color: 'neutral',
          variant: 'subtle',
          class: 'ring ring-inset ring-accented text-default bg-elevated'
        }
      ],
      defaultVariants: {
        variant: 'outline',
        color: 'neutral',
        size: 'md'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/Kbd.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/kbd.ts).


# Link

## Uso

O componente Link é um wrapper em torno do [`<NuxtLink>`](https://nuxt.com/docs/api/components/nuxt-link){rel="&#x22;nofollow&#x22;"} usando a prop [`custom`](https://router.vuejs.org/api/interfaces/RouterLinkProps.html#Properties-custom){rel="&#x22;nofollow&#x22;"}. Ele fornece algumas props extras:

- `inactive-class` prop to set a class when the link is inactive, `active-class` is used when active.
- `exact` prop to style with `active-class` when the link is active and the route is exactly the same as the current route.
- `exact-query` and `exact-hash` props to style with `active-class`when the link is active and the query or hash is exactly the same as the current query or hash.
  - use `exact-query="partial"` to style with `active-class` when the link is active and the query partially match the current query.

A motivação por trás disso é oferecer a mesma API do NuxtLink dos tempos do Nuxt 2 / Vue 2. Você pode ler mais sobre isso no guia de [migração do Vue 2](https://router.vuejs.org/guide/migration/#removal-of-the-exact-prop-in-router-link){rel="&#x22;nofollow&#x22;"} do Vue Router.

> \[!NOTE]
>
> Ele é usado pelos componentes [`Breadcrumb`](https://ui.nitro.news/docs/components/breadcrumb), [`Button`](https://ui.nitro.news/docs/components/button), [`ContextMenu`](https://ui.nitro.news/docs/components/context-menu), [`DropdownMenu`](https://ui.nitro.news/docs/components/dropdown-menu) e [`NavigationMenu`](https://ui.nitro.news/docs/components/navigation-menu).

### Tag

O componente `Link` renderiza uma tag `<a>` quando uma prop `to` é fornecida; caso contrário, renderiza uma tag `<button>`. Você pode usar a prop `as` para alterar a tag de fallback.

```vue
<template>
  <ULink as="button">
    Link
  </ULink>
</template>
```

> \[!NOTE]
>
> Você pode inspecionar o HTML renderizado alterando a prop `to`.

### Estilo

Por padrão, o link tem estilos de ativo e inativo padrão; confira a seção [#theme](https://ui.nitro.news/#theme).

```vue
<template>
  <ULink to="/docs/components/link">
    Link
  </ULink>
</template>
```

> \[!NOTE]
>
> Tente alterar a prop `to` para ver os estados ativo e inativo.

Você pode sobrescrever esse comportamento usando a prop `raw` e fornecer seus próprios estilos usando `class`, `active-class` e `inactive-class`.

```vue
<template>
  <ULink raw to="/docs/components/link" active-class="font-bold" inactive-class="text-muted">
    Link
  </ULink>
</template>
```

> \[!NOTE]
>
> Se você está usando a extensão [Tailwind CSS IntelliSense](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss){rel="&#x22;nofollow&#x22;"} para o VSCode e quer ter autocompletar para as props `active-class` e `inactive-class`, você pode adicionar as seguintes configurações ao seu `.vscode/settings.json`:
>
> ```json [.vscode/settings.json]
> {
>   "tailwindCSS.classAttributes": [
>     "active-class",
>     "inactive-class"
>   ]
> }
> ```

### Locale `4.7+`

O componente Link se integra automaticamente ao [`@nuxtjs/i18n`](https://i18n.nuxtjs.org/){rel="&#x22;nofollow&#x22;"} quando instalado. Os links internos são localizados automaticamente usando o helper `$localePath`, sem exigir envolvimento manual.

```vue
<template>
  <!-- Automatically becomes /en/about or /fr/about based on current locale -->
  <NLink to="/about">About</NLink>
</template>
```

> \[!TIP]
>
> Você ainda pode usar `localePath()` ou `localeRoute()` manualmente se necessário.

> \[!NOTE]
> See: /docs/getting-started/integrations/i18n/nuxt#dynamic-locale
>
> Learn more about Internationalization in Nitro UI.

## API

### Props

```ts
/**
 * Props for the Link component
 */
interface LinkProps {
  /**
   * The element or component this component should render as when not a link.
   * @default "\"button\""
   */
  as?: any;
  /**
   * The type of the button when not a link.
   * @default "\"button\""
   */
  type?: "reset" | "submit" | "button" | undefined;
  disabled?: boolean | undefined;
  /**
   * Force the link to be active independent of the current route.
   * @default "undefined"
   */
  active?: boolean | undefined;
  /**
   * Will only be active if the current route is an exact match.
   */
  exact?: boolean | undefined;
  /**
   * Allows controlling how the current route query sets the link as active.
   */
  exactQuery?: boolean | "partial" | undefined;
  /**
   * Will only be active if the current route hash is an exact match.
   */
  exactHash?: boolean | undefined;
  /**
   * The class to apply when the link is inactive.
   */
  inactiveClass?: string | undefined;
  /**
   * Whether RouterLink should not wrap its content in an `a` tag. Useful when
   * using `v-slot` to create a custom RouterLink
   */
  custom?: boolean | undefined;
  /**
   * When `true`, only styles from `class`, `activeClass`, and `inactiveClass` will be applied.
   */
  raw?: boolean | undefined;
  /**
   * Control i18n auto-localization when `@nuxtjs/i18n` is installed.
   * - `undefined` / `true` (default): auto-localizes to the current locale using `$localePath`.
   *   Paths already carrying a locale prefix (from e.g. `switchLocalePath()`) are detected
   *   and left untouched to prevent double-prefixing.
   * - `false`: explicitly disables auto-localization.
   * - `string`: localizes to a specific locale (e.g. `'fr'`).
   * @default "undefined"
   */
  locale?: string | boolean | undefined;
  /**
   * Route Location the link should navigate to when clicked on.
   */
  to?: string | it | et | undefined;
  /**
   * An alias for `to`. If used with `to`, `href` will be ignored
   */
  href?: string | it | et | undefined;
  /**
   * Forces the link to be considered as external (true) or internal (false). This is helpful to handle edge-cases
   */
  external?: boolean | undefined;
  /**
   * Where to display the linked URL, as the name for a browsing context.
   */
  target?: (string & {}) | "_blank" | "_parent" | "_self" | "_top" | null | undefined;
  /**
   * A rel attribute value to apply on the link. Defaults to "noopener noreferrer" for external links.
   */
  rel?: "noopener" | "noreferrer" | "nofollow" | "sponsored" | "ugc" | (string & {}) | null | undefined;
  /**
   * If set to true, no rel attribute will be added to the link
   */
  noRel?: boolean | undefined;
  /**
   * A class to apply to links that have been prefetched.
   */
  prefetchedClass?: string | undefined;
  /**
   * When enabled will prefetch middleware, layouts and payloads of links in the viewport.
   */
  prefetch?: boolean | undefined;
  /**
   * Allows controlling when to prefetch links. By default, prefetch is triggered only on visibility.
   */
  prefetchOn?: "visibility" | "interaction" | Partial<{ visibility: boolean; interaction: boolean; }> | undefined;
  /**
   * Escape hatch to disable `prefetch` attribute.
   */
  noPrefetch?: boolean | undefined;
  /**
   * An option to either add or remove trailing slashes in the `href` for this specific link.
   * Overrides the global `trailingSlash` option if provided.
   */
  trailingSlash?: "remove" | "append" | undefined;
  /**
   * Class to apply when the link is active
   */
  activeClass?: string | undefined;
  /**
   * Class to apply when the link is exact active
   */
  exactActiveClass?: string | undefined;
  /**
   * Value passed to the attribute `aria-current` when the link is exact active.
   * @default "\"page\""
   */
  ariaCurrentValue?: "step" | "page" | "true" | "false" | "location" | "date" | "time" | undefined;
  /**
   * Pass the returned promise of `router.push()` to `document.startViewTransition()` if supported.
   */
  viewTransition?: boolean | undefined;
  /**
   * Calls `router.replace` instead of `router.push`.
   */
  replace?: boolean | undefined;
  name?: string | undefined;
  autofocus?: Booleanish | undefined;
  form?: string | undefined;
  formaction?: string | undefined;
  formenctype?: string | undefined;
  formmethod?: string | undefined;
  formnovalidate?: Booleanish | undefined;
  formtarget?: string | undefined;
  referrerpolicy?: HTMLAttributeReferrerPolicy | undefined;
  download?: any;
  hreflang?: string | undefined;
  media?: string | undefined;
  ping?: string | undefined;
}
```

> \[!NOTE]
> See: https\://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attributes
>
> Este componente também suporta todos os atributos HTML nativos de `<a>`.

### Slots

```ts
/**
 * Slots for the Link component
 */
interface LinkSlots {
  default(): any;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    link: {
      base: 'focus-visible:outline-accent underline underline-offset-2',
      variants: {
        active: {
          true: 'text-accent',
          false: ''
        },
        disabled: {
          true: 'cursor-not-allowed opacity-75'
        }
      },
      compoundVariants: [
        {
          active: false,
          disabled: false,
          class: 'hover:text-accent transition-colors'
        }
      ]
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/Link.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/link.ts).


# Listbox

## Uso

Use a diretiva `v-model` para controlar o valor do Listbox ou a prop `default-value` para definir o valor inicial quando você não precisa controlar o estado.

```vue
<script setup lang="ts">
import type { ListboxItem } from '@nitro/ui'

const items = ref<ListboxItem[]>([
  {
    label: "France",
    icon: "i-lucide-map-pin",
    value: "FR"
  },
  {
    label: "Germany",
    icon: "i-lucide-map-pin",
    value: "DE"
  },
  {
    label: "Italy",
    icon: "i-lucide-map-pin",
    value: "IT"
  },
  {
    label: "Spain",
    icon: "i-lucide-map-pin",
    value: "ES"
  },
  {
    label: "Netherlands",
    icon: "i-lucide-map-pin",
    value: "NL"
  },
  {
    label: "Poland",
    icon: "i-lucide-map-pin",
    value: "PL"
  },
  {
    label: "Belgium",
    icon: "i-lucide-map-pin",
    value: "BE"
  },
  {
    label: "Portugal",
    icon: "i-lucide-map-pin",
    value: "PT"
  },
  {
    label: "Austria",
    icon: "i-lucide-map-pin",
    value: "AT"
  },
  {
    label: "Sweden",
    icon: "i-lucide-map-pin",
    value: "SE"
  }
])
const value = ref({
  label: "France",
  icon: "i-lucide-map-pin",
  value: "FR"
})
</script>

<template>
  <UListbox v-model="value" :items="items" />
</template>
```

### Itens

Use a prop `items` como um array de objetos com as seguintes propriedades:

- `label?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- [`description?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}](https://ui.nitro.news/#with-description-in-items)
- [`type?: "label" | "separator" | "item"`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}](https://ui.nitro.news/#with-items-type)
- [`icon?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}](https://ui.nitro.news/#with-icon-in-items)
- [`avatar?: AvatarProps`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}](https://ui.nitro.news/#with-avatar-in-items)
- [`chip?: ChipProps`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}](https://ui.nitro.news/#with-chip-in-items)
- `disabled?: boolean`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `onSelect?: (e: Event) => void`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `class?: any`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `ui?: { label?: ClassNameValue, separator?: ClassNameValue, item?: ClassNameValue, itemLeadingIcon?: ClassNameValue, ... }`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

```vue
<script setup lang="ts">
import type { ListboxItem } from '@nitro/ui'

const items = ref<ListboxItem[]>([
  {
    label: "France",
    description: "The Hexagon",
    icon: "i-lucide-map-pin",
    value: "FR"
  },
  {
    label: "Germany",
    description: "The Federal Republic",
    icon: "i-lucide-map-pin",
    value: "DE"
  },
  {
    label: "Italy",
    description: "The Boot",
    icon: "i-lucide-map-pin",
    value: "IT"
  },
  {
    label: "Spain",
    description: "The Bull Skin",
    icon: "i-lucide-map-pin",
    value: "ES"
  }
])
</script>

<template>
  <UListbox :items="items" />
</template>
```

Você também pode passar um array de arrays para a prop `items` para exibir grupos separados de itens.

```vue
<script setup lang="ts">
import type { ListboxItem } from '@nitro/ui'

const items = ref<ListboxItem[][]>([
  [
    {
      label: "France",
      icon: "i-lucide-map-pin",
      value: "FR"
    },
    {
      label: "Germany",
      icon: "i-lucide-map-pin",
      value: "DE"
    },
    {
      label: "Italy",
      icon: "i-lucide-map-pin",
      value: "IT"
    }
  ],
  [
    {
      label: "Brazil",
      icon: "i-lucide-map-pin",
      value: "BR"
    },
    {
      label: "Argentina",
      icon: "i-lucide-map-pin",
      value: "AR"
    }
  ]
])
</script>

<template>
  <UListbox :items="items" />
</template>
```

### Múltiplo

Use a prop `multiple` para permitir a seleção de vários itens. Quando habilitada, o `v-model` será um array.

```vue
<script setup lang="ts">
import type { ListboxItem } from '@nitro/ui'

const items = ref<ListboxItem[]>([
  {
    label: "France",
    icon: "i-lucide-map-pin",
    value: "FR"
  },
  {
    label: "Germany",
    icon: "i-lucide-map-pin",
    value: "DE"
  },
  {
    label: "Italy",
    icon: "i-lucide-map-pin",
    value: "IT"
  },
  {
    label: "Spain",
    icon: "i-lucide-map-pin",
    value: "ES"
  }
])
</script>

<template>
  <UListbox multiple :items="items" />
</template>
```

### Chave de valor

Você pode optar por vincular uma única propriedade do objeto em vez do objeto inteiro usando a prop `value-key`. O padrão é `undefined`.

```vue
<script setup lang="ts">
import type { ListboxItem } from '@nitro/ui'

const items = ref<ListboxItem[]>([
  {
    label: "France",
    icon: "i-lucide-map-pin",
    value: "FR"
  },
  {
    label: "Germany",
    icon: "i-lucide-map-pin",
    value: "DE"
  },
  {
    label: "Italy",
    icon: "i-lucide-map-pin",
    value: "IT"
  },
  {
    label: "Spain",
    icon: "i-lucide-map-pin",
    value: "ES"
  }
])
const value = ref("FR")
</script>

<template>
  <UListbox v-model="value" value-key="value" :items="items" class="w-full" />
</template>
```

### Filtro

Use a prop `filter` para exibir um campo de filtro ou passe um objeto para personalizar o componente [Input](https://ui.nitro.news/docs/components/input). O padrão é `false`.

```vue
<script setup lang="ts">
import type { ListboxItem } from '@nitro/ui'

const items = ref<ListboxItem[]>([
  {
    label: "France",
    icon: "i-lucide-map-pin",
    value: "FR"
  },
  {
    label: "Germany",
    icon: "i-lucide-map-pin",
    value: "DE"
  },
  {
    label: "Italy",
    icon: "i-lucide-map-pin",
    value: "IT"
  },
  {
    label: "Spain",
    icon: "i-lucide-map-pin",
    value: "ES"
  },
  {
    label: "Netherlands",
    icon: "i-lucide-map-pin",
    value: "NL"
  },
  {
    label: "Poland",
    icon: "i-lucide-map-pin",
    value: "PL"
  }
])
</script>

<template>
  <UListbox :filter="{
  placeholder: 'Filter...',
  icon: 'i-lucide-search'
}" :items="items" />
</template>
```

### Ícone de selecionado

Use a prop `selected-icon` para personalizar o ícone quando um item é selecionado. O padrão é `i-lucide-check`.

```vue
<script setup lang="ts">
import type { ListboxItem } from '@nitro/ui'

const items = ref<ListboxItem[]>([
  {
    label: "France",
    icon: "i-lucide-map-pin",
    value: "FR"
  },
  {
    label: "Germany",
    icon: "i-lucide-map-pin",
    value: "DE"
  },
  {
    label: "Italy",
    icon: "i-lucide-map-pin",
    value: "IT"
  },
  {
    label: "Spain",
    icon: "i-lucide-map-pin",
    value: "ES"
  }
])
const value = ref("FR")
</script>

<template>
  <UListbox v-model="value" selected-icon="i-lucide-flame" value-key="value" :items="items" class="w-full" />
</template>
```

### Tamanho

Use a prop `size` para alterar o tamanho do Listbox.

```vue
<script setup lang="ts">
import type { ListboxItem } from '@nitro/ui'

const items = ref<ListboxItem[]>([
  {
    label: "France",
    icon: "i-lucide-map-pin",
    value: "FR"
  },
  {
    label: "Germany",
    icon: "i-lucide-map-pin",
    value: "DE"
  },
  {
    label: "Italy",
    icon: "i-lucide-map-pin",
    value: "IT"
  },
  {
    label: "Spain",
    icon: "i-lucide-map-pin",
    value: "ES"
  }
])
</script>

<template>
  <UListbox size="xl" :items="items" />
</template>
```

### Carregando

Use a prop `loading` para exibir um indicador de carregamento. Use a prop `loading-icon` para personalizar o ícone.

```vue
<script setup lang="ts">
import type { ListboxItem } from '@nitro/ui'

const items = ref<ListboxItem[]>([
  {
    label: "France",
    icon: "i-lucide-map-pin",
    value: "FR"
  },
  {
    label: "Germany",
    icon: "i-lucide-map-pin",
    value: "DE"
  }
])
</script>

<template>
  <UListbox loading :items="items" />
</template>
```

### Desabilitado

Use a prop `disabled` para impedir qualquer interação do usuário com o Listbox.

```vue
<script setup lang="ts">
import type { ListboxItem } from '@nitro/ui'

const items = ref<ListboxItem[]>([
  {
    label: "France",
    icon: "i-lucide-map-pin",
    value: "FR"
  },
  {
    label: "Germany",
    icon: "i-lucide-map-pin",
    value: "DE"
  },
  {
    label: "Italy",
    icon: "i-lucide-map-pin",
    value: "IT"
  },
  {
    label: "Spain",
    icon: "i-lucide-map-pin",
    value: "ES"
  }
])
</script>

<template>
  <UListbox disabled :items="items" />
</template>
```

## Exemplos

### Com tipo de itens

Você pode usar a propriedade `type` com `separator` para exibir um separador entre os itens ou `label` para exibir um rótulo.

```vue
<script setup lang="ts">
import type { ListboxItem } from '@nitro/ui'

const items = ref<ListboxItem[][]>([
  [
    {
      type: "label",
      label: "Fruits"
    },
    {
      label: "Apple"
    },
    {
      label: "Banana"
    },
    {
      label: "Blueberry"
    },
    {
      label: "Grapes"
    },
    {
      label: "Pineapple"
    }
  ],
  [
    {
      type: "label",
      label: "Vegetables"
    },
    {
      label: "Aubergine"
    },
    {
      label: "Broccoli"
    },
    {
      label: "Carrot"
    },
    {
      label: "Courgette"
    },
    {
      label: "Leek"
    }
  ]
])
</script>

<template>
  <UListbox :items="items" />
</template>
```

> \[!NOTE]
>
> Ao usar itens `label` como cabeçalhos de grupo, passe um array de arrays para que um rótulo seja filtrado junto com o grupo dele durante a busca.

### Com ícone nos itens

Você pode usar a propriedade `icon` para exibir um [Icon](https://ui.nitro.news/docs/components/icon) dentro dos itens.

```vue
<script setup lang="ts">
import type { ListboxItem } from '@nitro/ui'

const items = ref<ListboxItem[]>([
  {
    label: "Backlog",
    icon: "i-lucide-circle-help",
    value: "backlog"
  },
  {
    label: "Todo",
    icon: "i-lucide-circle-plus",
    value: "todo"
  },
  {
    label: "In Progress",
    icon: "i-lucide-circle-arrow-up",
    value: "in_progress"
  },
  {
    label: "Done",
    icon: "i-lucide-circle-check",
    value: "done"
  }
])
</script>

<template>
  <UListbox :items="items" />
</template>
```

### Com avatar nos itens

Você pode usar a propriedade `avatar` para exibir um [Avatar](https://ui.nitro.news/docs/components/avatar) dentro dos itens.

```vue
<script setup lang="ts">
import type { ListboxItem } from '@nitro/ui'

const items = ref<ListboxItem[]>([
  {
    label: "benjamincanac",
    avatar: {
      src: "https://github.com/benjamincanac.png"
    }
  },
  {
    label: "romhml",
    avatar: {
      src: "https://github.com/romhml.png"
    }
  },
  {
    label: "atinux",
    avatar: {
      src: "https://github.com/atinux.png"
    }
  },
  {
    label: "HugoRCD",
    avatar: {
      src: "https://github.com/HugoRCD.png"
    }
  }
])
</script>

<template>
  <UListbox :items="items" />
</template>
```

### Com chip nos itens

Você pode usar a propriedade `chip` para exibir um [Chip](https://ui.nitro.news/docs/components/chip) dentro dos itens.

```vue
<script setup lang="ts">
import type { ListboxItem } from '@nitro/ui'

const items = ref<ListboxItem[]>([
  {
    label: "bug",
    chip: {
      color: "error"
    }
  },
  {
    label: "feature",
    chip: {
      color: "success"
    }
  },
  {
    label: "enhancement",
    chip: {
      color: "info"
    }
  }
])
</script>

<template>
  <UListbox :items="items" />
</template>
```

### Com descrição nos itens

Você pode usar a propriedade `description` para exibir um texto adicional abaixo do rótulo.

```vue
<script setup lang="ts">
import type { ListboxItem } from '@nitro/ui'

const items = ref<ListboxItem[]>([
  {
    label: "France",
    description: "The Hexagon",
    icon: "i-lucide-map-pin",
    value: "FR"
  },
  {
    label: "Germany",
    description: "The Federal Republic",
    icon: "i-lucide-map-pin",
    value: "DE"
  },
  {
    label: "Italy",
    description: "The Boot",
    icon: "i-lucide-map-pin",
    value: "IT"
  },
  {
    label: "Spain",
    description: "The Bull Skin",
    icon: "i-lucide-map-pin",
    value: "ES"
  }
])
</script>

<template>
  <UListbox :items="items" />
</template>
```

### Controlar os itens selecionados

Você pode controlar o item selecionado usando a prop `default-value` ou a diretiva `v-model`.

::component-example{collapse name="listbox-model-value-example"}
::

### Controlar o termo de busca

Use a diretiva `v-model:search-term` para controlar o termo de busca.

:component-example{name="listbox-search-term-example"}

### Com filtro ignorado

Defina a prop `ignore-filter` como `true` para desabilitar a busca interna e usar sua própria lógica de busca.

::component-example{collapse name="listbox-ignore-filter-example"}
::

> \[!NOTE]
>
> Este exemplo usa [`refDebounced`](https://vueuse.org/shared/refDebounced/#refdebounced){rel="&#x22;nofollow&#x22;"} para aplicar debounce nas chamadas de API.

### Com campos de filtro

Use a prop `filter-fields` com um array de campos para filtrar. O padrão é `[labelKey]`.

::component-example{collapse name="listbox-filter-fields-example"}
::

### Com virtualização

Use a prop `virtualize` para habilitar a virtualização em listas grandes, como um booleano ou um objeto com opções como `{ estimateSize: 32, overscan: 12 }`.

::component-example{collapse name="listbox-virtualize-example"}
::

### Como lista de transferência

Você pode compor dois componentes Listbox com controles de [Button](https://ui.nitro.news/docs/components/button) para construir um padrão de lista de transferência.

::component-example{collapse name="listbox-transfer-list-example"}
::

## API

### Props

```ts
/**
 * Props for the Listbox component
 */
interface ListboxProps {
  id?: string | undefined;
  /**
   * The element or component this component should render as.
   */
  as?: any;
  color?: "primary" | "secondary" | "accent" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
  size?: "sm" | "md" | "xs" | "lg" | "xl" | undefined;
  /**
   * The items to display in the list.
   */
  items?: T | undefined;
  /**
   * The controlled value of the Listbox. Can be bound with `v-model`.
   */
  modelValue?: _Number<_Optional<_Nullable<GetModelValue<T, VK, M, undefined>, Mod>, Mod>, Mod> | undefined;
  modelModifiers?: Mod | undefined;
  /**
   * The default value when not controlled.
   */
  defaultValue?: _Number<_Optional<_Nullable<GetModelValue<T, VK, M, undefined>, Mod>, Mod>, Mod> | undefined;
  /**
   * Whether multiple items can be selected.
   */
  multiple?: M | undefined;
  /**
   * When `items` is an array of objects, select the field to use as the value instead of the object itself.
   */
  valueKey?: VK | undefined;
  /**
   * The key used to get the label from the item.
   * @default "\"label\""
   */
  labelKey?: GetItemKeys<T> | undefined;
  /**
   * The key used to get the description from the item.
   * @default "\"description\""
   */
  descriptionKey?: GetItemKeys<T> | undefined;
  /**
   * Whether the list is in a loading state.
   */
  loading?: boolean | undefined;
  /**
   * The icon displayed when loading.
   */
  loadingIcon?: any;
  /**
   * Whether to display a filter input or not.
   * Can be an object to pass additional props to the input.
   * `{ placeholder: 'Search...', variant: 'none' }`{lang="ts-type"}
   * @default "false"
   */
  filter?: boolean | Omit<InputProps<AcceptableValue, ModelModifiers>, "modelValue" | "defaultValue"> | undefined;
  /**
   * The fields to filter by.
   */
  filterFields?: string[] | undefined;
  /**
   * When `true`, disable the default filters, useful for custom filtering (useAsyncData, useFetch, etc.).
   */
  ignoreFilter?: boolean | undefined;
  /**
   * The icon displayed when an item is selected.
   */
  selectedIcon?: any;
  /**
   * Enable virtualization for large lists.
   * @default "false"
   */
  virtualize?: boolean | { overscan?: number | undefined; estimateSize?: number | ((index: number) => number) | undefined; } | undefined;
  /**
   * Highlight the ring color like a focus state.
   */
  highlight?: boolean | undefined;
  autofocus?: boolean | undefined;
  /**
   * @default "0"
   */
  autofocusDelay?: number | undefined;
  ui?: { root?: SlotClass; input?: SlotClass; content?: SlotClass; group?: SlotClass; label?: SlotClass; separator?: SlotClass; empty?: SlotClass; loading?: SlotClass; loadingIcon?: SlotClass; item?: SlotClass; itemLeadingIcon?: SlotClass; itemLeadingAvatar?: SlotClass; itemLeadingAvatarSize?: SlotClass; itemLeadingChip?: SlotClass; itemLeadingChipSize?: SlotClass; itemWrapper?: SlotClass; itemLabel?: SlotClass; itemDescription?: SlotClass; itemTrailing?: SlotClass; itemTrailingIcon?: SlotClass; } | undefined;
  /**
   * Use this to compare objects by a particular field, or pass your own comparison function for complete control over how objects are compared.
   */
  by?: string | ((a: AcceptableValue, b: AcceptableValue) => boolean) | undefined;
  /**
   * When `true`, prevents the user from interacting with listbox
   */
  disabled?: boolean | undefined;
  /**
   * When `true`, hover over item will trigger highlight
   * @default "true"
   */
  highlightOnHover?: boolean | undefined;
  /**
   * The name of the field. Submitted with its owning form as part of a name/value pair.
   */
  name?: string | undefined;
  /**
   * The orientation of the listbox. <br>Mainly so arrow navigation is done accordingly (left & right vs. up & down)
   */
  orientation?: DataOrientation | undefined;
  /**
   * When `true`, indicates that the user must set the value before the owning form can be submitted.
   */
  required?: boolean | undefined;
  /**
   * How multiple selection should behave in the collection.
   */
  selectionBehavior?: "replace" | "toggle" | undefined;
  /**
   * @default "\"\""
   */
  searchTerm?: string | undefined;
}
```

### Slots

```ts
/**
 * Slots for the Listbox component
 */
interface ListboxSlots {
  loading(): any;
  empty(): any;
  item(): any;
  item-leading(): any;
  item-label(): any;
  item-description(): any;
  item-trailing(): any;
}
```

### Emits

```ts
/**
 * Emitted events for the Listbox component
 */
interface ListboxEmits {
  entryFocus: (payload: [event: CustomEvent<any>]) => void;
  highlight: (payload: [payload: { ref: HTMLElement; value: AcceptableValue; } | undefined]) => void;
  leave: (payload: [event: Event]) => void;
  change: (payload: [event: Event]) => void;
  update:modelValue: (payload: [value: _Number<_Optional<_Nullable<GetModelValue<T, VK, M, undefined>, Mod>, Mod>, Mod>]) => void;
  update:searchTerm: (payload: [value: string]) => void;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    listbox: {
      slots: {
        root: 'flex flex-col min-h-0 min-w-0 ring ring-inset ring-default rounded-lg overflow-hidden',
        input: 'border-b border-default',
        content: 'relative overflow-y-auto flex-1 max-h-60 scroll-py-1 focus:outline-none',
        group: 'p-1 isolate',
        label: 'font-semibold text-highlighted',
        separator: '-mx-1 my-1 h-px bg-border',
        empty: 'text-center text-muted',
        loading: 'flex items-center justify-center text-muted',
        loadingIcon: 'animate-spin shrink-0',
        item: [
          'group relative w-full flex items-start select-none outline-none before:absolute before:z-[-1] before:inset-px before:rounded-md data-disabled:cursor-not-allowed data-disabled:opacity-75 text-default data-highlighted:not-data-disabled:text-highlighted data-highlighted:not-data-disabled:before:bg-elevated/50',
          'transition-colors before:transition-colors'
        ],
        itemLeadingIcon: [
          'shrink-0 text-dimmed group-data-highlighted:not-group-data-disabled:text-default',
          'transition-colors'
        ],
        itemLeadingAvatar: 'shrink-0',
        itemLeadingAvatarSize: '',
        itemLeadingChip: 'shrink-0',
        itemLeadingChipSize: '',
        itemWrapper: 'flex-1 flex flex-col min-w-0',
        itemLabel: 'truncate',
        itemDescription: 'truncate text-muted',
        itemTrailing: 'ms-auto inline-flex gap-1.5 items-center',
        itemTrailingIcon: 'shrink-0'
      },
      variants: {
        size: {
          xs: {
            label: 'p-1 text-[10px]/3 gap-1',
            empty: 'py-3 text-xs',
            loading: 'py-3',
            loadingIcon: 'size-4',
            item: 'p-1 text-xs gap-1',
            itemLeadingIcon: 'size-4',
            itemLeadingAvatarSize: '3xs',
            itemLeadingChip: 'size-4',
            itemLeadingChipSize: 'sm',
            itemTrailingIcon: 'size-4'
          },
          sm: {
            label: 'p-1.5 text-[10px]/3 gap-1.5',
            empty: 'py-4 text-xs',
            loading: 'py-4',
            loadingIcon: 'size-4',
            item: 'p-1.5 text-xs gap-1.5',
            itemLeadingIcon: 'size-4',
            itemLeadingAvatarSize: '3xs',
            itemLeadingChip: 'size-4',
            itemLeadingChipSize: 'sm',
            itemTrailingIcon: 'size-4'
          },
          md: {
            label: 'p-1.5 text-xs gap-1.5',
            empty: 'py-6 text-sm',
            loading: 'py-6',
            loadingIcon: 'size-5',
            item: 'p-1.5 text-sm gap-1.5',
            itemLeadingIcon: 'size-5',
            itemLeadingAvatarSize: '2xs',
            itemLeadingChip: 'size-5',
            itemLeadingChipSize: 'md',
            itemTrailingIcon: 'size-5'
          },
          lg: {
            label: 'p-2 text-xs gap-2',
            empty: 'py-7 text-sm',
            loading: 'py-7',
            loadingIcon: 'size-5',
            item: 'p-2 text-sm gap-2',
            itemLeadingIcon: 'size-5',
            itemLeadingAvatarSize: '2xs',
            itemLeadingChip: 'size-5',
            itemLeadingChipSize: 'md',
            itemTrailingIcon: 'size-5'
          },
          xl: {
            label: 'p-2 text-sm gap-2',
            empty: 'py-8 text-base',
            loading: 'py-8',
            loadingIcon: 'size-6',
            item: 'p-2 text-base gap-2',
            itemLeadingIcon: 'size-6',
            itemLeadingAvatarSize: 'xs',
            itemLeadingChip: 'size-6',
            itemLeadingChipSize: 'lg',
            itemTrailingIcon: 'size-6',
            itemDescription: 'text-sm'
          }
        },
        color: {
          primary: {
            root: 'outline-primary/25 has-focus-visible:outline-3 has-focus-visible:ring-primary'
          },
          secondary: {
            root: 'outline-secondary/25 has-focus-visible:outline-3 has-focus-visible:ring-secondary'
          },
          accent: {
            root: 'outline-accent/25 has-focus-visible:outline-3 has-focus-visible:ring-accent'
          },
          success: {
            root: 'outline-success/25 has-focus-visible:outline-3 has-focus-visible:ring-success'
          },
          info: {
            root: 'outline-info/25 has-focus-visible:outline-3 has-focus-visible:ring-info'
          },
          warning: {
            root: 'outline-warning/25 has-focus-visible:outline-3 has-focus-visible:ring-warning'
          },
          error: {
            root: 'outline-error/25 has-focus-visible:outline-3 has-focus-visible:ring-error'
          },
          neutral: {
            root: 'outline-inverted/25 has-focus-visible:outline-3 has-focus-visible:ring-inverted'
          }
        },
        virtualize: {
          true: {
            content: 'p-1 isolate'
          },
          false: {
            content: 'divide-y divide-default'
          }
        },
        disabled: {
          true: {
            root: 'opacity-75 cursor-not-allowed'
          }
        },
        highlight: {
          true: ''
        }
      },
      compoundVariants: [
        {
          color: 'primary',
          highlight: true,
          class: {
            root: 'ring ring-inset ring-primary'
          }
        },
        {
          color: 'secondary',
          highlight: true,
          class: {
            root: 'ring ring-inset ring-secondary'
          }
        },
        {
          color: 'accent',
          highlight: true,
          class: {
            root: 'ring ring-inset ring-accent'
          }
        },
        {
          color: 'success',
          highlight: true,
          class: {
            root: 'ring ring-inset ring-success'
          }
        },
        {
          color: 'info',
          highlight: true,
          class: {
            root: 'ring ring-inset ring-info'
          }
        },
        {
          color: 'warning',
          highlight: true,
          class: {
            root: 'ring ring-inset ring-warning'
          }
        },
        {
          color: 'error',
          highlight: true,
          class: {
            root: 'ring ring-inset ring-error'
          }
        },
        {
          color: 'neutral',
          highlight: true,
          class: {
            root: 'ring ring-inset ring-inverted'
          }
        }
      ],
      defaultVariants: {
        color: 'primary',
        size: 'md'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/Listbox.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/listbox.ts).


# LocaleSelect

## Uso

O componente LocaleSelect estende o componente [SelectMenu](https://ui.nitro.news/docs/components/select-menu), então você pode passar qualquer propriedade como `color`, `variant`, `size`, etc.

**Nuxt:**

> \[!NOTE]
> See: /docs/getting-started/integrations/i18n/nuxt
>
> Este componente foi feito para ser usado com o sistema de **i18n**. Saiba mais sobre ele no guia.

**Vue:**

> \[!NOTE]
> See: /docs/getting-started/integrations/i18n/vue
>
> Este componente foi feito para ser usado com o sistema de **i18n**. Saiba mais sobre ele no guia.

> \[!WARNING]
>
> As bandeiras são exibidas usando caracteres Unicode. Isso pode resultar em uma exibição diferente; por exemplo, o Microsoft Edge no Windows exibe o código ISO 3166-1 alpha-2 no lugar, já que nenhum ícone de bandeira acompanha as fontes do sistema operacional.

### Locales

Use a prop `locales` com um array de locales de `@nitro/ui/locale`.

:component-example{name="locale-select-example"}

Você pode passar apenas os locales que precisa na sua aplicação:

```vue
<script setup lang="ts">
import { en, es, fr } from '@nitro/ui/locale'

const locale = ref('en')
</script>

<template>
  <NLocaleSelect v-model="locale" :locales="[en, es, fr]" />
</template>
```

### Locale dinâmico

**Nuxt:**

Você pode usá-lo com o Nuxt i18n:

```vue
<script setup lang="ts">
import * as locales from '@nitro/ui/locale'

const { locale, setLocale } = useI18n()
</script>

<template>
  <NLocaleSelect
    :model-value="locale"
    :locales="Object.values(locales)"
    @update:model-value="setLocale($event)"
  />
</template>
```

**Vue:**

Você pode usá-lo com o Vue i18n:

```vue
<script setup lang="ts">
import { useI18n } from 'vue-i18n'
import * as locales from '@nitro/ui/locale'

const { locale, setLocale } = useI18n()
</script>

<template>
  <NLocaleSelect
    :model-value="locale"
    :locales="Object.values(locales)"
    @update:model-value="setLocale($event)"
  />
</template>
```

## API

### Props

```ts
/**
 * Props for the LocaleSelect component
 */
interface LocaleSelectProps {
  modelValue: string;
  locales?: Locale<any>[] | undefined;
  /**
   * The name of the field. Submitted with its owning form as part of a name/value pair.
   */
  name?: string | undefined;
  /**
   * Display an avatar on the left side.
   */
  avatar?: AvatarProps | undefined;
  size?: "md" | "xs" | "sm" | "lg" | "xl" | undefined;
  ui?: { base?: SlotClass; leading?: SlotClass; leadingIcon?: SlotClass; leadingAvatar?: SlotClass; leadingAvatarSize?: SlotClass; trailing?: SlotClass; trailingIcon?: SlotClass; value?: SlotClass; placeholder?: SlotClass; arrow?: SlotClass; content?: SlotClass; viewport?: SlotClass; group?: SlotClass; empty?: SlotClass; label?: SlotClass; separator?: SlotClass; item?: SlotClass; itemLeadingIcon?: SlotClass; itemLeadingAvatar?: SlotClass; itemLeadingAvatarSize?: SlotClass; itemLeadingChip?: SlotClass; itemLeadingChipSize?: SlotClass; itemTrailing?: SlotClass; itemTrailingIcon?: SlotClass; itemWrapper?: SlotClass; itemLabel?: SlotClass; itemDescription?: SlotClass; input?: SlotClass; focusScope?: SlotClass; trailingClear?: SlotClass; } | undefined;
  /**
   * When `true`, the loading icon will be displayed.
   */
  loading?: boolean | undefined;
  /**
   * Display an icon based on the `leading` and `trailing` props.
   */
  icon?: any;
  color?: "error" | "neutral" | "primary" | "secondary" | "accent" | "success" | "info" | "warning" | undefined;
  autofocus?: boolean | undefined;
  /**
   * When `true`, prevents the user from interacting with listbox
   */
  disabled?: boolean | undefined;
  form?: string | undefined;
  formaction?: string | undefined;
  formenctype?: string | undefined;
  formmethod?: string | undefined;
  formnovalidate?: Booleanish | undefined;
  formtarget?: string | undefined;
  /**
   * The controlled open state of the Combobox. Can be binded with `v-model:open`.
   */
  open?: boolean | undefined;
  /**
   * The open state of the combobox when it is initially rendered. <br> Use when you do not need to control its open state.
   */
  defaultOpen?: boolean | undefined;
  /**
   * Whether to reset the searchTerm when the Combobox input blurred
   */
  resetSearchTermOnBlur?: boolean | undefined;
  /**
   * Whether to reset the searchTerm when the Combobox value is selected
   */
  resetSearchTermOnSelect?: boolean | undefined;
  /**
   * When `true` the `modelValue` will be reset to `null` (or `[]` if `multiple`)
   */
  resetModelValueOnClear?: boolean | undefined;
  /**
   * When `true`, hover over item will trigger highlight
   */
  highlightOnHover?: boolean | undefined;
  /**
   * Use this to compare objects by a particular field, or pass your own comparison function for complete control over how objects are compared.
   */
  by?: string | ((a: Locale<any>[], b: Locale<any>[]) => boolean) | undefined;
  /**
   * The value of the SelectMenu when initially rendered. Use when you do not need to control the state of the SelectMenu.
   */
  defaultValue?: string | undefined;
  /**
   * Whether multiple options can be selected or not.
   */
  multiple?: false | undefined;
  required?: boolean | undefined;
  id?: string | undefined;
  /**
   * The placeholder text when the select is empty.
   */
  placeholder?: string | undefined;
  /**
   * Whether to display the search input or not.
   * Can be an object to pass additional props to the input.
   * `{ placeholder: 'Search...', variant: 'none' }`{lang="ts-type"}
   * @default "false"
   */
  searchInput?: boolean | Omit<InputProps<AcceptableValue, ModelModifiers>, "modelValue" | "defaultValue"> | undefined;
  variant?: "outline" | "soft" | "subtle" | "ghost" | "none" | undefined;
  /**
   * The icon displayed to open the menu.
   */
  trailingIcon?: any;
  /**
   * The icon displayed when an item is selected.
   */
  selectedIcon?: any;
  /**
   * Display a clear button to reset the model value.
   * Can be an object to pass additional props to the Button.
   */
  clear?: false | (false & Partial<Omit<ButtonProps, LinkPropsKeys>>) | undefined;
  /**
   * The icon displayed in the clear button.
   */
  clearIcon?: any;
  /**
   * The content of the menu.
   */
  content?: (Omit<ComboboxContentProps, "as" | "asChild" | "forceMount"> & Partial<EmitsToProps<DismissableLayerEmits>>) | undefined;
  /**
   * Display an arrow alongside the menu.
   * `{ rounded: true }`{lang="ts-type"}
   */
  arrow?: boolean | Omit<ComboboxArrowProps, "as" | "asChild"> | undefined;
  /**
   * Render the menu in a portal.
   */
  portal?: string | boolean | HTMLElement | undefined;
  /**
   * Enable virtualization for large lists.
   * Note: when enabled, all groups are flattened into a single list due to a limitation of Reka UI (https://github.com/unovue/reka-ui/issues/1885).
   */
  virtualize?: boolean | { overscan?: number | undefined; estimateSize?: number | ((index: number) => number) | undefined; } | undefined;
  /**
   * When `items` is an array of objects, select the field to use as the value instead of the object itself.
   * @default "\"code\""
   */
  valueKey?: "code" | undefined;
  /**
   * When `items` is an array of objects, select the field to use as the label.
   * @default "\"name\""
   */
  labelKey?: GetItemKeys<Locale<any>[]> | undefined;
  /**
   * When `items` is an array of objects, select the field to use as the description.
   */
  descriptionKey?: GetItemKeys<Locale<any>[]> | undefined;
  modelModifiers?: Omit<ModelModifiers, "lazy"> | undefined;
  /**
   * Highlight the ring color like a focus state.
   */
  highlight?: boolean | undefined;
  /**
   * Determines if custom user input that does not exist in options can be added.
   */
  createItem?: boolean | "always" | { position?: "top" | "bottom" | undefined; when?: "empty" | "always" | undefined; } | undefined;
  /**
   * Fields to filter items by.
   */
  filterFields?: string[] | undefined;
  /**
   * When `true`, disable the default filters, useful for custom filtering (useAsyncData, useFetch, etc.).
   */
  ignoreFilter?: boolean | undefined;
  autofocusDelay?: number | undefined;
  /**
   * When `true`, the icon will be displayed on the left side.
   */
  leading?: boolean | undefined;
  /**
   * Display an icon on the left side.
   */
  leadingIcon?: any;
  /**
   * When `true`, the icon will be displayed on the right side.
   */
  trailing?: boolean | undefined;
  /**
   * The icon when the `loading` prop is `true`.
   */
  loadingIcon?: any;
}
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/locale/LocaleSelect.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/locale/locale-select.ts).


# Main

## Uso

O componente Main renderiza um elemento `<main>` que funciona em conjunto com o componente [Header](https://ui.nitro.news/docs/components/header) para criar um layout de altura total que se estende até a altura disponível da viewport.

> \[!TIP]
> See: /docs/getting-started/theme/css-variables#header
>
> O componente Main usa a variável CSS `--ui-header-height` para se posicionar corretamente abaixo do `Header`.

## Exemplos

### Dentro de `app.vue`

Use o componente Main no seu `app.vue` ou em um layout:

```vue [app.vue] {5-9}
<template>
  <NApp>
    <NHeader />

    <NMain>
      <NuxtLayout>
        <NuxtPage />
      </NuxtLayout>
    </NMain>

    <NFooter />
  </NApp>
</template>
```

## API

### Props

```ts
/**
 * Props for the Main component
 */
interface MainProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
}
```

### Slots

```ts
/**
 * Slots for the Main component
 */
interface MainSlots {
  default(): any;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    main: {
      base: 'min-h-[calc(100vh-var(--ui-header-height))]'
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/Main.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/main.ts).


# Marquee

## Uso

Use o slot padrão com o seu conteúdo para criar uma animação de rolagem infinita.

```vue
<template>
  <UMarquee>
    <NIcon name="i-simple-icons-github" class="size-10 shrink-0" />
    <NIcon name="i-simple-icons-discord" class="size-10 shrink-0" />
    <NIcon name="i-simple-icons-x" class="size-10 shrink-0" />
    <NIcon name="i-simple-icons-instagram" class="size-10 shrink-0" />
    <NIcon name="i-simple-icons-linkedin" class="size-10 shrink-0" />
    <NIcon name="i-simple-icons-facebook" class="size-10 shrink-0" />
  </UMarquee>
</template>
```

### Pausar ao passar o mouse

Use a prop `pause-on-hover` para pausar a animação quando o usuário passa o mouse sobre o conteúdo.

```vue
<template>
  <UMarquee pause-on-hover>
    <NIcon name="i-simple-icons-github" class="size-10 shrink-0" />
    <NIcon name="i-simple-icons-discord" class="size-10 shrink-0" />
    <NIcon name="i-simple-icons-x" class="size-10 shrink-0" />
    <NIcon name="i-simple-icons-instagram" class="size-10 shrink-0" />
    <NIcon name="i-simple-icons-linkedin" class="size-10 shrink-0" />
    <NIcon name="i-simple-icons-facebook" class="size-10 shrink-0" />
  </UMarquee>
</template>
```

### Invertido

Use a prop `reverse` para inverter a direção da animação.

```vue
<template>
  <UMarquee reverse>
    <NIcon name="i-simple-icons-github" class="size-10 shrink-0" />
    <NIcon name="i-simple-icons-discord" class="size-10 shrink-0" />
    <NIcon name="i-simple-icons-x" class="size-10 shrink-0" />
    <NIcon name="i-simple-icons-instagram" class="size-10 shrink-0" />
    <NIcon name="i-simple-icons-linkedin" class="size-10 shrink-0" />
    <NIcon name="i-simple-icons-facebook" class="size-10 shrink-0" />
  </UMarquee>
</template>
```

### Orientação

Use a prop `orientation` para alterar a direção da rolagem.

```vue
<template>
  <UMarquee orientation="vertical">
    <NIcon name="i-simple-icons-github" class="size-10 shrink-0" />
    <NIcon name="i-simple-icons-discord" class="size-10 shrink-0" />
    <NIcon name="i-simple-icons-x" class="size-10 shrink-0" />
    <NIcon name="i-simple-icons-instagram" class="size-10 shrink-0" />
    <NIcon name="i-simple-icons-linkedin" class="size-10 shrink-0" />
    <NIcon name="i-simple-icons-facebook" class="size-10 shrink-0" />
  </UMarquee>
</template>
```

### Repetir

Use a prop `repeat` para especificar quantas vezes o conteúdo deve ser repetido na animação.

```vue
<template>
  <UMarquee :repeat="6">
    <NIcon name="i-simple-icons-github" class="size-10 shrink-0" />
    <NIcon name="i-simple-icons-discord" class="size-10 shrink-0" />
    <NIcon name="i-simple-icons-x" class="size-10 shrink-0" />
    <NIcon name="i-simple-icons-instagram" class="size-10 shrink-0" />
    <NIcon name="i-simple-icons-linkedin" class="size-10 shrink-0" />
    <NIcon name="i-simple-icons-facebook" class="size-10 shrink-0" />
  </UMarquee>
</template>
```

### Overlay

Use a prop `overlay` para remover as sobreposições de gradiente nas bordas do marquee.

```vue
<template>
  <UMarquee :overlay="false">
    <NIcon name="i-simple-icons-github" class="size-10 shrink-0" />
    <NIcon name="i-simple-icons-discord" class="size-10 shrink-0" />
    <NIcon name="i-simple-icons-x" class="size-10 shrink-0" />
    <NIcon name="i-simple-icons-instagram" class="size-10 shrink-0" />
    <NIcon name="i-simple-icons-linkedin" class="size-10 shrink-0" />
    <NIcon name="i-simple-icons-facebook" class="size-10 shrink-0" />
  </UMarquee>
</template>
```

## Exemplos

### Depoimentos

Use o componente `Marquee` para criar uma animação de rolagem infinita para os seus depoimentos.

::component-example
---
collapse: true
overflowHidden: true
prettier: true
class: px-0
label: With Items
name: marquee-testimonials
---
::

### Capturas de tela

Use o componente `Marquee` para criar uma animação de rolagem infinita para as suas capturas de tela.

::component-example
---
collapse: true
overflowHidden: true
prettier: true
class: "!p-0"
label: With Screenshots
name: marquee-screenshots
---
::

## API

### Props

```ts
/**
 * Props for the Marquee component
 */
interface MarqueeProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  /**
   * Pause the marquee on hover.
   */
  pauseOnHover?: boolean | undefined;
  /**
   * Reverse the direction of the marquee.
   */
  reverse?: boolean | undefined;
  /**
   * The orientation of the marquee.
   * @default "\"horizontal\""
   */
  orientation?: "vertical" | "horizontal" | undefined;
  /**
   * The number of times the marquee should repeat.
   * @default "4"
   */
  repeat?: number | undefined;
  /**
   * Display an overlay on the marquee.
   * @default "true"
   */
  overlay?: boolean | undefined;
  ui?: { root?: SlotClass; content?: SlotClass; } | undefined;
}
```

### Slots

```ts
/**
 * Slots for the Marquee component
 */
interface MarqueeSlots {
  default(): any;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    marquee: {
      slots: {
        root: 'group relative flex items-center overflow-hidden gap-(--gap) [--gap:--spacing(16)] [--duration:20s]',
        content: 'flex items-center shrink-0 justify-around gap-(--gap) min-w-max'
      },
      variants: {
        orientation: {
          horizontal: {
            content: 'w-full'
          },
          vertical: {
            content: 'h-full'
          }
        },
        pauseOnHover: {
          true: {
            content: 'group-hover:[animation-play-state:paused]'
          }
        },
        reverse: {
          true: {
            content: '![animation-direction:reverse]'
          }
        },
        overlay: {
          true: {
            root: 'before:absolute before:pointer-events-none before:content-[""] before:z-2 before:from-default before:to-transparent after:absolute after:pointer-events-none after:content-[""] after:z-2 after:from-default after:to-transparent'
          }
        }
      },
      compoundVariants: [
        {
          orientation: 'horizontal',
          class: {
            root: 'flex-row',
            content: 'flex-row animate-[marquee_var(--duration)_linear_infinite] rtl:animate-[marquee-rtl_var(--duration)_linear_infinite] backface-hidden'
          }
        },
        {
          orientation: 'horizontal',
          overlay: true,
          class: {
            root: 'before:inset-y-0 before:left-0 before:h-full before:w-1/3 before:bg-gradient-to-r after:inset-y-0 after:right-0 after:h-full after:w-1/3 after:bg-gradient-to-l backface-hidden'
          }
        },
        {
          orientation: 'vertical',
          class: {
            root: 'flex-col',
            content: 'flex-col animate-[marquee-vertical_var(--duration)_linear_infinite] rtl:animate-[marquee-vertical-rtl_var(--duration)_linear_infinite] h-[fit-content] backface-hidden'
          }
        },
        {
          orientation: 'vertical',
          overlay: true,
          class: {
            root: 'before:inset-x-0 before:top-0 before:w-full before:h-1/3 before:bg-gradient-to-b after:inset-x-0 after:bottom-0 after:w-full after:h-1/3 after:bg-gradient-to-t backface-hidden'
          }
        }
      ]
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/Marquee.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/marquee.ts).


# Modal

## Uso

Use a [Button](https://ui.nitro.news/docs/components/button) or any other component in the default slot of the Modal.

Depois, use o slot `#content` para adicionar o conteúdo exibido quando o Modal está aberto.

```vue
<template>
  <UModal>
    <NButton label="Open" color="neutral" variant="subtle" />
  
    <template #content>
      <Placeholder class="h-48 m-4" />
    </template></UModal>
</template>
```

Você também pode usar os slots `#header`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, `#body`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} e `#footer`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} para personalizar o conteúdo do Modal.

### Título

Use a prop `title` para definir o título do cabeçalho do Modal.

```vue
<template>
  <UModal title="Modal with title">
    <NButton label="Open" color="neutral" variant="subtle" />
  
    <template #body>
      <Placeholder class="h-48" />
    </template></UModal>
</template>
```

### Descrição

Use a prop `description` para definir a descrição do cabeçalho do Modal.

```vue
<template>
  <UModal title="Modal with description" description="Lorem ipsum dolor sit amet, consectetur adipiscing elit.">
    <NButton label="Open" color="neutral" variant="subtle" />
  
    <template #body>
      <Placeholder class="h-48" />
    </template></UModal>
</template>
```

### Fechar

Use a prop `close` para personalizar ou ocultar o botão de fechar (com o valor `false`) exibido no cabeçalho do Modal.

Você pode passar qualquer propriedade do componente [Button](https://ui.nitro.news/docs/components/button) para personalizá-lo.

```vue
<template>
  <UModal title="Modal with close button" :close="{
  color: 'primary',
  variant: 'outline',
  class: 'rounded-full'
}">
    <NButton label="Open" color="neutral" variant="subtle" />
  
    <template #body>
      <Placeholder class="h-48" />
    </template></UModal>
</template>
```

> \[!TIP]
>
> O botão de fechar não é exibido se o slot `#content` for usado, pois ele faz parte do cabeçalho.

### Ícone de fechar

Use a prop `close-icon` para personalizar o [Icon](https://ui.nitro.news/docs/components/icon) do botão de fechar. O padrão é `i-lucide-x`.

```vue
<template>
  <UModal title="Modal with close button" close-icon="i-lucide-arrow-right">
    <NButton label="Open" color="neutral" variant="subtle" />
  
    <template #body>
      <Placeholder class="h-48" />
    </template></UModal>
</template>
```

**Nuxt:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/nuxt#theme
>
> Você pode personalizar esse ícone globalmente no seu `app.config.ts` na chave `ui.icons.close`.

**Vue:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/vue#theme
>
> Você pode personalizar esse ícone globalmente no seu `vite.config.ts` na chave `ui.icons.close`.

### Transição

Use a prop `transition` para controlar se o Modal é animado ou não. O padrão é `true`.

```vue
<template>
  <UModal :transition="false" title="Modal without transition">
    <NButton label="Open" color="neutral" variant="subtle" />
  
    <template #body>
      <Placeholder class="h-48" />
    </template></UModal>
</template>
```

### Overlay

Use a prop `overlay` para controlar se o Modal tem um overlay ou não. O padrão é `true`.

```vue
<template>
  <UModal :overlay="false" title="Modal without overlay">
    <NButton label="Open" color="neutral" variant="subtle" />
  
    <template #body>
      <Placeholder class="h-48" />
    </template></UModal>
</template>
```

### Modal

Use a prop `modal` para controlar se o Modal bloqueia a interação com o conteúdo externo. O padrão é `true`.

> \[!NOTE]
>
> Quando `modal` é definido como `false`, o overlay é automaticamente desabilitado e o conteúdo externo se torna interativo.

```vue
<template>
  <UModal :modal="false" title="Modal interactive">
    <NButton label="Open" color="neutral" variant="subtle" />
  
    <template #body>
      <Placeholder class="h-48" />
    </template></UModal>
</template>
```

### Dispensável

Use a prop `dismissible` para controlar se o Modal pode ser dispensado ao clicar fora dele ou pressionar escape. O padrão é `true`.

> \[!NOTE]
>
> Um evento `close:prevent` será emitido quando o usuário tentar fechá-lo.

> \[!TIP]
>
> Você pode combinar `modal: false` com `dismissible: false` para tornar o fundo do Modal interativo sem fechá-lo.

```vue
<template>
  <UModal :dismissible="false" modal title="Modal non-dismissible">
    <NButton label="Open" color="neutral" variant="subtle" />
  
    <template #body>
      <Placeholder class="h-48" />
    </template></UModal>
</template>
```

### Rolável `4.2+`

Use a prop `scrollable` para tornar o conteúdo do Modal rolável dentro do overlay.

> \[!WARNING]
>
> Como o overlay é necessário para a rolagem, `modal: false` não é compatível, e `overlay: false` apenas remove o fundo.

```vue
<template>
  <UModal scrollable overlay title="Modal scrollable">
    <NButton label="Open" color="neutral" variant="subtle" />
  
    <template #body>
      <Placeholder class="h-full" />
    </template></UModal>
</template>
```

> \[!CAUTION]
>
> Há um [problema conhecido](https://reka-ui.com/docs/components/dialog#scrollable-overlay){rel="&#x22;nofollow&#x22;"} em que clicar na barra de rolagem pode fechar o diálogo sem querer em alguns sistemas operacionais.

### Tela cheia

Use a prop `fullscreen` para deixar o Modal em tela cheia.

```vue
<template>
  <UModal fullscreen title="Modal fullscreen">
    <NButton label="Open" color="neutral" variant="subtle" />
  
    <template #body>
      <Placeholder class="h-full" />
    </template></UModal>
</template>
```

### Desmontar `Soon`

Use a prop `unmount-on-hide` para evitar que o conteúdo do Modal seja desmontado quando ele é fechado. O padrão é `true`.

```vue
<template>
  <UModal :unmount-on-hide="false" title="Modal">
    <NButton label="Open" color="neutral" variant="subtle" />
  
    <template #body>
      <Placeholder class="h-48" />
    </template></UModal>
</template>
```

> \[!NOTE]
>
> Você pode inspecionar o DOM para ver o conteúdo do Modal sendo renderizado mesmo enquanto ele está fechado.

> \[!TIP]
>
> Quando a prop `portal` é definida como `false`, o conteúdo também é renderizado no servidor. Isso é útil para renderizar um Modal aberto durante o SSR sem uma piscada no carregamento da página, ou para expor seu conteúdo para SEO.

## Exemplos

### Controlar o estado de abertura

Você pode controlar o estado de abertura usando a prop `default-open` ou a diretiva `v-model:open`.

:component-example{name="modal-open-example"}

> \[!NOTE]
>
> Neste exemplo, aproveitando o [`defineShortcuts`](https://ui.nitro.news/docs/composables/define-shortcuts), você pode abrir e fechar o Modal pressionando :kbd{value="O"}.

> \[!TIP]
>
> Isso permite mover o gatilho para fora do Modal ou removê-lo por completo.

### Uso programático

Você pode usar o composable [`useOverlay`](https://ui.nitro.news/docs/composables/use-overlay) para abrir um Modal programaticamente.

> \[!WARNING]
>
> Certifique-se de envolver seu app com o componente [`App`](https://ui.nitro.news/docs/components/app), que usa o componente [`OverlayProvider`](https://gitlab.nitro.news/nitro/ui/-/blob/main/src/runtime/components/OverlayProvider.vue){rel="&#x22;nofollow&#x22;"}.

Primeiro, crie um componente de modal que será aberto programaticamente:

::component-example{prettier :preview='false' name="modal-example"}
::

> \[!NOTE]
>
> Aqui emitimos um evento `close` quando o modal é fechado ou dispensado. Você pode emitir qualquer dado por meio do evento `close`, porém o evento precisa ser emitido para que o valor de retorno seja capturado.

Depois, use-o no seu app:

:component-example{name="modal-programmatic-example"}

> \[!TIP]
>
> Você pode fechar o modal dentro do componente de modal emitindo `emit('close')`.

### Modais aninhados

Você pode aninhar modais uns dentro dos outros.

:component-example{name="modal-nested-example"}

### Com slot de rodapé

Use o slot `#footer` para adicionar conteúdo após o corpo do Modal.

:component-example{name="modal-footer-slot-example"}

### Com paleta de comandos

Você pode usar um componente [CommandPalette](https://ui.nitro.news/docs/components/command-palette) dentro do conteúdo do Modal.

::component-example{collapse name="modal-command-palette-example"}
::

> \[!NOTE]
>
> Este exemplo usa `useLazyFetch` com `immediate: false` para buscar os dados apenas quando o Modal abre.

## API

### Props

```ts
/**
 * Props for the Modal component
 */
interface ModalProps {
  title?: string | undefined;
  description?: string | undefined;
  /**
   * The content of the modal.
   */
  content?: (Omit<DialogContentProps, "as" | "asChild" | "forceMount"> & Partial<EmitsToProps<DialogContentImplEmits>>) | undefined;
  /**
   * Render an overlay behind the modal.
   * @default "true"
   */
  overlay?: boolean | undefined;
  /**
   * When `true`, enables scrollable overlay mode where content scrolls within the overlay.
   */
  scrollable?: boolean | undefined;
  /**
   * Animate the modal when opening or closing.
   * @default "true"
   */
  transition?: boolean | undefined;
  /**
   * When `true`, the modal will take up the full screen.
   */
  fullscreen?: boolean | undefined;
  /**
   * Render the modal in a portal.
   * @default "true"
   */
  portal?: string | boolean | HTMLElement | undefined;
  /**
   * Display a close button to dismiss the modal.
   * `{ size: 'md', color: 'neutral', variant: 'ghost' }`{lang="ts-type"}
   * @default "true"
   */
  close?: boolean | Omit<ButtonProps, LinkPropsKeys> | undefined;
  /**
   * The icon displayed in the close button.
   */
  closeIcon?: any;
  /**
   * When `false`, the modal will not close when clicking outside or pressing escape.
   * @default "true"
   */
  dismissible?: boolean | undefined;
  ui?: { overlay?: SlotClass; content?: SlotClass; header?: SlotClass; wrapper?: SlotClass; body?: SlotClass; actions?: SlotClass; footer?: SlotClass; title?: SlotClass; description?: SlotClass; close?: SlotClass; loading?: SlotClass; spinner?: SlotClass; } | undefined;
  /**
   * The controlled open state of the dialog. Can be binded as `v-model:open`.
   */
  open?: boolean | undefined;
  /**
   * The open state of the dialog when it is initially rendered. Use when you do not need to control its open state.
   */
  defaultOpen?: boolean | undefined;
  /**
   * The modality of the dialog When set to `true`, <br>
   * interaction with outside elements will be disabled and only dialog content will be visible to screen readers.
   * @default "true"
   */
  modal?: boolean | undefined;
  /**
   * When set to `false`, the dialog content will not be unmounted when closed, but instead hidden with CSS. <br>
   * Useful for SEO or when you want to improve performance by not remounting the component on every open.
   */
  unmountOnHide?: boolean | undefined;
}
```

### Slots

```ts
/**
 * Slots for the Modal component
 */
interface ModalSlots {
  default(): any;
  content(): any;
  header(): any;
  title(): any;
  description(): any;
  actions(): any;
  close(): any;
  body(): any;
  footer(): any;
}
```

### Emits

```ts
/**
 * Emitted events for the Modal component
 */
interface ModalEmits {
  leave: (payload: []) => void;
  after:leave: (payload: []) => void;
  enter: (payload: []) => void;
  after:enter: (payload: []) => void;
  close:prevent: (payload: []) => void;
  update:open: (payload: [value: boolean]) => void;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    modal: {
      slots: {
        overlay: 'fixed inset-0',
        content: 'bg-default flex flex-col focus:outline-none',
        header: 'flex items-center gap-1.5 p-4 sm:px-6 min-h-16',
        wrapper: '',
        body: 'flex-1 p-4 sm:p-6',
        actions: 'flex items-center justify-between gap-1.5 p-4 sm:px-6 border-default border-t',
        footer: 'flex items-center gap-1.5 p-4 sm:px-6',
        title: 'text-xl font-semibold text-secondary',
        description: 'mt-1 text-muted text-sm',
        close: 'absolute top-4 end-4',
        loading: 'p-5 flex items-center justify-center',
        spinner: ''
      },
      variants: {
        transition: {
          true: {
            overlay: 'data-[state=open]:animate-[fade-in_200ms_ease-out] data-[state=closed]:animate-[fade-out_200ms_ease-in]',
            content: 'data-[state=open]:animate-[scale-in_200ms_ease-out] data-[state=closed]:animate-[scale-out_200ms_ease-in]'
          }
        },
        fullscreen: {
          true: {
            content: 'inset-0'
          },
          false: {
            content: 'w-[calc(100vw-2rem)] max-w-lg rounded-lg shadow-lg ring ring-default'
          }
        },
        overlay: {
          true: {
            overlay: 'bg-secondary/75'
          }
        },
        scrollable: {
          true: {
            overlay: 'overflow-y-auto',
            content: 'relative'
          },
          false: {
            content: 'fixed',
            body: 'overflow-y-auto'
          }
        }
      },
      compoundVariants: [
        {
          scrollable: true,
          fullscreen: false,
          class: {
            overlay: 'grid place-items-center p-4 sm:py-8'
          }
        },
        {
          scrollable: false,
          fullscreen: false,
          class: {
            content: 'top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 max-h-[calc(100dvh-2rem)] sm:max-h-[calc(100dvh-4rem)] overflow-hidden'
          }
        }
      ]
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/Modal.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/modal.ts).


# NavigationMenu

## Uso

Use o componente NavigationMenu para exibir uma lista de links na horizontal ou na vertical.

```vue
<script setup lang="ts">
import type { NavigationMenuItem } from '@nitro/ui'

const items = ref<NavigationMenuItem[]>([
  {
    label: "Guide",
    icon: "i-lucide-book-open",
    to: "/docs/getting-started",
    children: [
      {
        label: "Introduction",
        description: "Fully styled and customizable components for Nuxt.",
        icon: "i-lucide-house"
      },
      {
        label: "Installation",
        description: "Learn how to install and configure Nitro UI in your application.",
        icon: "i-lucide-cloud-download"
      },
      {
        label: "Icons",
        icon: "i-lucide-smile",
        description: "You have nothing to do, @nuxt/icon will handle it automatically."
      },
      {
        label: "Colors",
        icon: "i-lucide-swatch-book",
        description: "Choose a primary and a neutral color from your Tailwind CSS theme."
      },
      {
        label: "Theme",
        icon: "i-lucide-cog",
        description: "You can customize components by using the `class` / `ui` props or in your app.config.ts."
      }
    ]
  },
  {
    label: "Composables",
    icon: "i-lucide-database",
    to: "/docs/composables",
    children: [
      {
        label: "defineShortcuts",
        icon: "i-lucide-file-text",
        description: "Define shortcuts for your application.",
        to: "/docs/composables/define-shortcuts"
      },
      {
        label: "useOverlay",
        icon: "i-lucide-file-text",
        description: "Display a modal/slideover within your application.",
        to: "/docs/composables/use-overlay"
      },
      {
        label: "useToast",
        icon: "i-lucide-file-text",
        description: "Display a toast within your application.",
        to: "/docs/composables/use-toast"
      }
    ]
  },
  {
    label: "Components",
    icon: "i-lucide-box",
    to: "/docs/components",
    active: true,
    children: [
      {
        label: "Link",
        icon: "i-lucide-file-text",
        description: "Use NuxtLink with superpowers.",
        to: "/docs/components/link"
      },
      {
        label: "Modal",
        icon: "i-lucide-file-text",
        description: "Display a modal within your application.",
        to: "/docs/components/modal"
      },
      {
        label: "NavigationMenu",
        icon: "i-lucide-file-text",
        description: "Display a list of links.",
        to: "/docs/components/navigation-menu"
      },
      {
        label: "Pagination",
        icon: "i-lucide-file-text",
        description: "Display a list of pages.",
        to: "/docs/components/pagination"
      },
      {
        label: "Popover",
        icon: "i-lucide-file-text",
        description: "Display a non-modal dialog that floats around a trigger element.",
        to: "/docs/components/popover"
      },
      {
        label: "Progress",
        icon: "i-lucide-file-text",
        description: "Show a horizontal bar to indicate task progression.",
        to: "/docs/components/progress"
      }
    ]
  },
  {
    label: "GitLab",
    icon: "i-simple-icons-gitlab",
    badge: "6k",
    to: "https://github.com/nuxt/ui",
    target: "_blank"
  },
  {
    label: "Help",
    icon: "i-lucide-circle-help",
    disabled: true
  }
])
</script>

<template>
  <UNavigationMenu :items="items" />
</template>
```

### Itens

Use a prop `items` como um array de objetos com as seguintes propriedades:

- `label?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `icon?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `avatar?: AvatarProps`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `badge?: string | number | BadgeProps`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- [`chip?: boolean | ChipProps`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}](https://ui.nitro.news/#with-chip-in-items)
- [`tooltip?: TooltipProps`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}](https://ui.nitro.news/#with-tooltip-in-items)
- [`popover?: PopoverProps`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}](https://ui.nitro.news/#with-popover-in-items)
- `trailingIcon?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `type?: 'label' | 'trigger' | 'link'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `defaultOpen?: boolean`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `open?: boolean`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `value?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `disabled?: boolean`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- [`slot?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}](https://ui.nitro.news/#with-custom-slot)
- `onSelect?: (e: Event) => void`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `children?: NavigationMenuChildItem[]`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `class?: any`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `ui?: { linkLeadingAvatarSize?: ClassNameValue, linkLeadingAvatar?: ClassNameValue, linkLeadingIcon?: ClassNameValue, linkLeadingChipSize?: ClassNameValue, linkLabel?: ClassNameValue, linkLabelExternalIcon?: ClassNameValue, linkTrailing?: ClassNameValue, linkTrailingBadgeSize?: ClassNameValue, linkTrailingBadge?: ClassNameValue, linkTrailingIcon?: ClassNameValue, label?: ClassNameValue, link?: ClassNameValue, content?: ClassNameValue, childList?: ClassNameValue, childLabel?: ClassNameValue, childItem?: ClassNameValue, childLink?: ClassNameValue, childLinkIcon?: ClassNameValue, childLinkWrapper?: ClassNameValue, childLinkLabel?: ClassNameValue, childLinkLabelExternalIcon?: ClassNameValue, childLinkDescription?: ClassNameValue }`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Você pode passar qualquer propriedade do componente [Link](https://ui.nitro.news/docs/components/link#props), como `to`, `target`, etc.

```vue
<script setup lang="ts">
import type { NavigationMenuItem } from '@nitro/ui'

const items = ref<NavigationMenuItem[]>([
  {
    label: "Guide",
    icon: "i-lucide-book-open",
    to: "/docs/getting-started",
    children: [
      {
        label: "Introduction",
        description: "Fully styled and customizable components for Nuxt.",
        icon: "i-lucide-house"
      },
      {
        label: "Installation",
        description: "Learn how to install and configure Nitro UI in your application.",
        icon: "i-lucide-cloud-download"
      },
      {
        label: "Icons",
        icon: "i-lucide-smile",
        description: "You have nothing to do, @nuxt/icon will handle it automatically."
      },
      {
        label: "Colors",
        icon: "i-lucide-swatch-book",
        description: "Choose a primary and a neutral color from your Tailwind CSS theme."
      },
      {
        label: "Theme",
        icon: "i-lucide-cog",
        description: "You can customize components by using the `class` / `ui` props or in your app.config.ts."
      }
    ]
  },
  {
    label: "Composables",
    icon: "i-lucide-database",
    to: "/docs/composables",
    children: [
      {
        label: "defineShortcuts",
        icon: "i-lucide-file-text",
        description: "Define shortcuts for your application.",
        to: "/docs/composables/define-shortcuts"
      },
      {
        label: "useOverlay",
        icon: "i-lucide-file-text",
        description: "Display a modal/slideover within your application.",
        to: "/docs/composables/use-overlay"
      },
      {
        label: "useToast",
        icon: "i-lucide-file-text",
        description: "Display a toast within your application.",
        to: "/docs/composables/use-toast"
      }
    ]
  },
  {
    label: "Components",
    icon: "i-lucide-box",
    to: "/docs/components",
    active: true,
    children: [
      {
        label: "Link",
        icon: "i-lucide-file-text",
        description: "Use NuxtLink with superpowers.",
        to: "/docs/components/link"
      },
      {
        label: "Modal",
        icon: "i-lucide-file-text",
        description: "Display a modal within your application.",
        to: "/docs/components/modal"
      },
      {
        label: "NavigationMenu",
        icon: "i-lucide-file-text",
        description: "Display a list of links.",
        to: "/docs/components/navigation-menu"
      },
      {
        label: "Pagination",
        icon: "i-lucide-file-text",
        description: "Display a list of pages.",
        to: "/docs/components/pagination"
      },
      {
        label: "Popover",
        icon: "i-lucide-file-text",
        description: "Display a non-modal dialog that floats around a trigger element.",
        to: "/docs/components/popover"
      },
      {
        label: "Progress",
        icon: "i-lucide-file-text",
        description: "Show a horizontal bar to indicate task progression.",
        to: "/docs/components/progress"
      }
    ]
  },
  {
    label: "GitLab",
    icon: "i-simple-icons-gitlab",
    badge: "6k",
    to: "https://github.com/nuxt/ui",
    target: "_blank"
  },
  {
    label: "Help",
    icon: "i-lucide-circle-help",
    disabled: true
  }
])
</script>

<template>
  <UNavigationMenu :items="items" class="w-full justify-center" />
</template>
```

> \[!NOTE]
>
> Você também pode passar um array de arrays para a prop `items` para exibir grupos de itens.

> \[!TIP]
>
> Cada item pode receber um array `children` de objetos com as seguintes propriedades para criar submenus:
>
> - `label: string`
> - `description?: string`
> - `icon?: string`
> - `onSelect?: (e: Event) => void`
> - `class?: any`

### Orientação

Use a prop `orientation` para alterar a orientação do NavigationMenu.

> \[!NOTE]
>
> Quando a orientação é `vertical`, um componente [Accordion](https://ui.nitro.news/docs/components/accordion) é usado para exibir cada grupo. Você pode controlar o estado de abertura de cada item usando as propriedades `open` e `defaultOpen` e alterar o comportamento usando as props [`collapsible`](https://ui.nitro.news/docs/components/accordion#collapsible) e [`type`](https://ui.nitro.news/docs/components/accordion#multiple).

```vue
<script setup lang="ts">
import type { NavigationMenuItem } from '@nitro/ui'

const items = ref<NavigationMenuItem[][]>([
  [
    {
      label: "Links",
      type: "label"
    },
    {
      label: "Guide",
      icon: "i-lucide-book-open",
      children: [
        {
          label: "Introduction",
          description: "Fully styled and customizable components for Nuxt.",
          icon: "i-lucide-house"
        },
        {
          label: "Installation",
          description: "Learn how to install and configure Nitro UI in your application.",
          icon: "i-lucide-cloud-download"
        },
        {
          label: "Icons",
          icon: "i-lucide-smile",
          description: "You have nothing to do, @nuxt/icon will handle it automatically."
        },
        {
          label: "Colors",
          icon: "i-lucide-swatch-book",
          description: "Choose a primary and a neutral color from your Tailwind CSS theme."
        },
        {
          label: "Theme",
          icon: "i-lucide-cog",
          description: "You can customize components by using the `class` / `ui` props or in your app.config.ts."
        }
      ]
    },
    {
      label: "Composables",
      icon: "i-lucide-database",
      children: [
        {
          label: "defineShortcuts",
          icon: "i-lucide-file-text",
          description: "Define shortcuts for your application.",
          to: "/docs/composables/define-shortcuts"
        },
        {
          label: "useOverlay",
          icon: "i-lucide-file-text",
          description: "Display a modal/slideover within your application.",
          to: "/docs/composables/use-overlay"
        },
        {
          label: "useToast",
          icon: "i-lucide-file-text",
          description: "Display a toast within your application.",
          to: "/docs/composables/use-toast"
        }
      ]
    },
    {
      label: "Components",
      icon: "i-lucide-box",
      to: "/docs/components",
      type: "trigger",
      active: true,
      defaultOpen: true,
      children: [
        {
          label: "Link",
          icon: "i-lucide-file-text",
          description: "Use NuxtLink with superpowers.",
          to: "/docs/components/link"
        },
        {
          label: "Modal",
          icon: "i-lucide-file-text",
          description: "Display a modal within your application.",
          to: "/docs/components/modal"
        },
        {
          label: "NavigationMenu",
          icon: "i-lucide-file-text",
          description: "Display a list of links.",
          to: "/docs/components/navigation-menu"
        },
        {
          label: "Pagination",
          icon: "i-lucide-file-text",
          description: "Display a list of pages.",
          to: "/docs/components/pagination"
        },
        {
          label: "Popover",
          icon: "i-lucide-file-text",
          description: "Display a non-modal dialog that floats around a trigger element.",
          to: "/docs/components/popover"
        },
        {
          label: "Progress",
          icon: "i-lucide-file-text",
          description: "Show a horizontal bar to indicate task progression.",
          to: "/docs/components/progress"
        }
      ]
    }
  ],
  [
    {
      label: "GitLab",
      icon: "i-simple-icons-gitlab",
      badge: "6k",
      to: "https://github.com/nuxt/ui",
      target: "_blank"
    },
    {
      label: "Help",
      icon: "i-lucide-circle-help",
      disabled: true
    }
  ]
])
</script>

<template>
  <UNavigationMenu orientation="vertical" :items="items" class="data-[orientation=vertical]:w-48" />
</template>
```

> \[!NOTE]
>
> Os grupos ficam espaçados quando a orientação é `horizontal` e separados quando a orientação é `vertical`.

### Recolhido

Na orientação `vertical`, use a prop `collapsed` para recolher o NavigationMenu; isso pode ser útil em uma sidebar, por exemplo.

> \[!NOTE]
>
> Você pode usar as props [`tooltip`](https://ui.nitro.news/#with-tooltip-in-items) e [`popover`](https://ui.nitro.news/#with-popover-in-items) para exibir mais informações nos itens recolhidos.

```vue
<script setup lang="ts">
import type { NavigationMenuItem } from '@nitro/ui'

const items = ref<NavigationMenuItem[][]>([
  [
    {
      label: "Links",
      type: "label"
    },
    {
      label: "Guide",
      icon: "i-lucide-book-open",
      children: [
        {
          label: "Introduction",
          description: "Fully styled and customizable components for Nuxt.",
          icon: "i-lucide-house"
        },
        {
          label: "Installation",
          description: "Learn how to install and configure Nitro UI in your application.",
          icon: "i-lucide-cloud-download"
        },
        {
          label: "Icons",
          icon: "i-lucide-smile",
          description: "You have nothing to do, @nuxt/icon will handle it automatically."
        },
        {
          label: "Colors",
          icon: "i-lucide-swatch-book",
          description: "Choose a primary and a neutral color from your Tailwind CSS theme."
        },
        {
          label: "Theme",
          icon: "i-lucide-cog",
          description: "You can customize components by using the `class` / `ui` props or in your app.config.ts."
        }
      ]
    },
    {
      label: "Composables",
      icon: "i-lucide-database",
      children: [
        {
          label: "defineShortcuts",
          icon: "i-lucide-file-text",
          description: "Define shortcuts for your application.",
          to: "/docs/composables/define-shortcuts"
        },
        {
          label: "useOverlay",
          icon: "i-lucide-file-text",
          description: "Display a modal/slideover within your application.",
          to: "/docs/composables/use-overlay"
        },
        {
          label: "useToast",
          icon: "i-lucide-file-text",
          description: "Display a toast within your application.",
          to: "/docs/composables/use-toast"
        }
      ]
    },
    {
      label: "Components",
      icon: "i-lucide-box",
      to: "/docs/components",
      active: true,
      children: [
        {
          label: "Link",
          icon: "i-lucide-file-text",
          description: "Use NuxtLink with superpowers.",
          to: "/docs/components/link"
        },
        {
          label: "Modal",
          icon: "i-lucide-file-text",
          description: "Display a modal within your application.",
          to: "/docs/components/modal"
        },
        {
          label: "NavigationMenu",
          icon: "i-lucide-file-text",
          description: "Display a list of links.",
          to: "/docs/components/navigation-menu"
        },
        {
          label: "Pagination",
          icon: "i-lucide-file-text",
          description: "Display a list of pages.",
          to: "/docs/components/pagination"
        },
        {
          label: "Popover",
          icon: "i-lucide-file-text",
          description: "Display a non-modal dialog that floats around a trigger element.",
          to: "/docs/components/popover"
        },
        {
          label: "Progress",
          icon: "i-lucide-file-text",
          description: "Show a horizontal bar to indicate task progression.",
          to: "/docs/components/progress"
        }
      ]
    }
  ],
  [
    {
      label: "GitLab",
      icon: "i-simple-icons-gitlab",
      badge: "6k",
      to: "https://github.com/nuxt/ui",
      target: "_blank"
    },
    {
      label: "Help",
      icon: "i-lucide-circle-help",
      disabled: true
    }
  ]
])
</script>

<template>
  <UNavigationMenu collapsed :tooltip="false" :popover="false" orientation="vertical" :items="items" />
</template>
```

### Destaque

Use a prop `highlight` para exibir uma borda destacada para o item ativo.

Use a prop `highlight-color` para alterar a cor da borda. O padrão é o valor da prop `color`.

```vue
<script setup lang="ts">
import type { NavigationMenuItem } from '@nitro/ui'

const items = ref<NavigationMenuItem[][]>([
  [
    {
      label: "Guide",
      icon: "i-lucide-book-open",
      children: [
        {
          label: "Introduction",
          description: "Fully styled and customizable components for Nuxt.",
          icon: "i-lucide-house"
        },
        {
          label: "Installation",
          description: "Learn how to install and configure Nitro UI in your application.",
          icon: "i-lucide-cloud-download"
        },
        {
          label: "Icons",
          icon: "i-lucide-smile",
          description: "You have nothing to do, @nuxt/icon will handle it automatically."
        },
        {
          label: "Colors",
          icon: "i-lucide-swatch-book",
          description: "Choose a primary and a neutral color from your Tailwind CSS theme."
        },
        {
          label: "Theme",
          icon: "i-lucide-cog",
          description: "You can customize components by using the `class` / `ui` props or in your app.config.ts."
        }
      ]
    },
    {
      label: "Composables",
      icon: "i-lucide-database",
      children: [
        {
          label: "defineShortcuts",
          icon: "i-lucide-file-text",
          description: "Define shortcuts for your application.",
          to: "/docs/composables/define-shortcuts"
        },
        {
          label: "useOverlay",
          icon: "i-lucide-file-text",
          description: "Display a modal/slideover within your application.",
          to: "/docs/composables/use-overlay"
        },
        {
          label: "useToast",
          icon: "i-lucide-file-text",
          description: "Display a toast within your application.",
          to: "/docs/composables/use-toast"
        }
      ]
    },
    {
      label: "Components",
      icon: "i-lucide-box",
      to: "/docs/components",
      active: true,
      defaultOpen: true,
      children: [
        {
          label: "Link",
          icon: "i-lucide-file-text",
          description: "Use NuxtLink with superpowers.",
          to: "/docs/components/link"
        },
        {
          label: "Modal",
          icon: "i-lucide-file-text",
          description: "Display a modal within your application.",
          to: "/docs/components/modal"
        },
        {
          label: "NavigationMenu",
          icon: "i-lucide-file-text",
          description: "Display a list of links.",
          to: "/docs/components/navigation-menu"
        },
        {
          label: "Pagination",
          icon: "i-lucide-file-text",
          description: "Display a list of pages.",
          to: "/docs/components/pagination"
        },
        {
          label: "Popover",
          icon: "i-lucide-file-text",
          description: "Display a non-modal dialog that floats around a trigger element.",
          to: "/docs/components/popover"
        },
        {
          label: "Progress",
          icon: "i-lucide-file-text",
          description: "Show a horizontal bar to indicate task progression.",
          to: "/docs/components/progress"
        }
      ]
    }
  ],
  [
    {
      label: "GitLab",
      icon: "i-simple-icons-gitlab",
      badge: "6k",
      to: "https://github.com/nuxt/ui",
      target: "_blank"
    },
    {
      label: "Help",
      icon: "i-lucide-circle-help",
      disabled: true
    }
  ]
])
</script>

<template>
  <UNavigationMenu highlight highlight-color="primary" orientation="horizontal" :items="items" class="data-[orientation=horizontal]:border-b border-default data-[orientation=horizontal]:w-full data-[orientation=vertical]:w-48" />
</template>
```

> \[!NOTE]
>
> Neste exemplo, a classe `border-b` é aplicada para exibir uma borda na orientação `horizontal`; isso não é feito por padrão para deixar você com um ponto de partida limpo.

> \[!CAUTION]
>
> Na orientação `vertical`, a prop `highlight` destaca apenas a borda dos filhos ativos.

### Cor

Use a prop `color` para alterar a cor do NavigationMenu.

```vue
<script setup lang="ts">
import type { NavigationMenuItem } from '@nitro/ui'

const items = ref<NavigationMenuItem[][]>([
  [
    {
      label: "Guide",
      icon: "i-lucide-book-open",
      to: "/docs/getting-started"
    },
    {
      label: "Composables",
      icon: "i-lucide-database",
      to: "/docs/composables"
    },
    {
      label: "Components",
      icon: "i-lucide-box",
      to: "/docs/components",
      active: true
    }
  ],
  [
    {
      label: "GitLab",
      icon: "i-simple-icons-gitlab",
      badge: "6k",
      to: "https://github.com/nuxt/ui",
      target: "_blank"
    }
  ]
])
</script>

<template>
  <UNavigationMenu color="neutral" :items="items" class="w-full" />
</template>
```

### Variante

Use a prop `variant` para alterar a variante do NavigationMenu.

```vue
<script setup lang="ts">
import type { NavigationMenuItem } from '@nitro/ui'

const items = ref<NavigationMenuItem[][]>([
  [
    {
      label: "Guide",
      icon: "i-lucide-book-open",
      to: "/docs/getting-started"
    },
    {
      label: "Composables",
      icon: "i-lucide-database",
      to: "/docs/composables"
    },
    {
      label: "Components",
      icon: "i-lucide-box",
      to: "/docs/components",
      active: true
    }
  ],
  [
    {
      label: "GitLab",
      icon: "i-simple-icons-gitlab",
      badge: "6k",
      to: "https://github.com/nuxt/ui",
      target: "_blank"
    }
  ]
])
</script>

<template>
  <UNavigationMenu color="neutral" variant="link" :highlight="false" :items="items" class="w-full" />
</template>
```

> \[!NOTE]
>
> A prop `highlight` altera o estilo do item ativo da variante `pill`. Experimente para ver a diferença.

### Ícone à direita

Use a prop `trailing-icon` para personalizar o [Icon](https://ui.nitro.news/docs/components/icon) à direita de cada item. O padrão é `i-lucide-chevron-down`. Este ícone só é exibido quando um item tem filhos.

> \[!TIP]
>
> Você também pode definir um ícone para um item específico usando a propriedade `trailingIcon` no objeto do item.

```vue
<script setup lang="ts">
import type { NavigationMenuItem } from '@nitro/ui'

const items = ref<NavigationMenuItem[]>([
  {
    label: "Guide",
    icon: "i-lucide-book-open",
    to: "/docs/getting-started",
    children: [
      {
        label: "Introduction",
        description: "Fully styled and customizable components for Nuxt.",
        icon: "i-lucide-house"
      },
      {
        label: "Installation",
        description: "Learn how to install and configure Nitro UI in your application.",
        icon: "i-lucide-cloud-download"
      },
      {
        label: "Icons",
        icon: "i-lucide-smile",
        description: "You have nothing to do, @nuxt/icon will handle it automatically."
      },
      {
        label: "Colors",
        icon: "i-lucide-swatch-book",
        description: "Choose a primary and a neutral color from your Tailwind CSS theme."
      },
      {
        label: "Theme",
        icon: "i-lucide-cog",
        description: "You can customize components by using the `class` / `ui` props or in your app.config.ts."
      }
    ]
  },
  {
    label: "Composables",
    icon: "i-lucide-database",
    to: "/docs/composables",
    children: [
      {
        label: "defineShortcuts",
        icon: "i-lucide-file-text",
        description: "Define shortcuts for your application.",
        to: "/docs/composables/define-shortcuts"
      },
      {
        label: "useOverlay",
        icon: "i-lucide-file-text",
        description: "Display a modal/slideover within your application.",
        to: "/docs/composables/use-overlay"
      },
      {
        label: "useToast",
        icon: "i-lucide-file-text",
        description: "Display a toast within your application.",
        to: "/docs/composables/use-toast"
      }
    ]
  },
  {
    label: "Components",
    icon: "i-lucide-box",
    to: "/docs/components",
    active: true,
    children: [
      {
        label: "Link",
        icon: "i-lucide-file-text",
        description: "Use NuxtLink with superpowers.",
        to: "/docs/components/link"
      },
      {
        label: "Modal",
        icon: "i-lucide-file-text",
        description: "Display a modal within your application.",
        to: "/docs/components/modal"
      },
      {
        label: "NavigationMenu",
        icon: "i-lucide-file-text",
        description: "Display a list of links.",
        to: "/docs/components/navigation-menu"
      },
      {
        label: "Pagination",
        icon: "i-lucide-file-text",
        description: "Display a list of pages.",
        to: "/docs/components/pagination"
      },
      {
        label: "Popover",
        icon: "i-lucide-file-text",
        description: "Display a non-modal dialog that floats around a trigger element.",
        to: "/docs/components/popover"
      },
      {
        label: "Progress",
        icon: "i-lucide-file-text",
        description: "Show a horizontal bar to indicate task progression.",
        to: "/docs/components/progress"
      }
    ]
  }
])
</script>

<template>
  <UNavigationMenu trailing-icon="i-lucide-arrow-down" :items="items" class="w-full justify-center" />
</template>
```

**Nuxt:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/nuxt#theme
>
> Você pode personalizar esse ícone globalmente no seu `app.config.ts` na chave `ui.icons.chevronDown`.

**Vue:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/vue#theme
>
> Você pode personalizar esse ícone globalmente no seu `vite.config.ts` na chave `ui.icons.chevronDown`.

### Seta

Use a prop `arrow` para exibir uma seta no conteúdo do NavigationMenu quando os itens têm filhos.

```vue
<script setup lang="ts">
import type { NavigationMenuItem } from '@nitro/ui'

const items = ref<NavigationMenuItem[]>([
  {
    label: "Guide",
    icon: "i-lucide-book-open",
    to: "/docs/getting-started",
    children: [
      {
        label: "Introduction",
        description: "Fully styled and customizable components for Nuxt.",
        icon: "i-lucide-house"
      },
      {
        label: "Installation",
        description: "Learn how to install and configure Nitro UI in your application.",
        icon: "i-lucide-cloud-download"
      },
      {
        label: "Icons",
        icon: "i-lucide-smile",
        description: "You have nothing to do, @nuxt/icon will handle it automatically."
      },
      {
        label: "Colors",
        icon: "i-lucide-swatch-book",
        description: "Choose a primary and a neutral color from your Tailwind CSS theme."
      },
      {
        label: "Theme",
        icon: "i-lucide-cog",
        description: "You can customize components by using the `class` / `ui` props or in your app.config.ts."
      }
    ]
  },
  {
    label: "Composables",
    icon: "i-lucide-database",
    to: "/docs/composables",
    children: [
      {
        label: "defineShortcuts",
        icon: "i-lucide-file-text",
        description: "Define shortcuts for your application.",
        to: "/docs/composables/define-shortcuts"
      },
      {
        label: "useOverlay",
        icon: "i-lucide-file-text",
        description: "Display a modal/slideover within your application.",
        to: "/docs/composables/use-overlay"
      },
      {
        label: "useToast",
        icon: "i-lucide-file-text",
        description: "Display a toast within your application.",
        to: "/docs/composables/use-toast"
      }
    ]
  },
  {
    label: "Components",
    icon: "i-lucide-box",
    to: "/docs/components",
    active: true,
    children: [
      {
        label: "Link",
        icon: "i-lucide-file-text",
        description: "Use NuxtLink with superpowers.",
        to: "/docs/components/link"
      },
      {
        label: "Modal",
        icon: "i-lucide-file-text",
        description: "Display a modal within your application.",
        to: "/docs/components/modal"
      },
      {
        label: "NavigationMenu",
        icon: "i-lucide-file-text",
        description: "Display a list of links.",
        to: "/docs/components/navigation-menu"
      },
      {
        label: "Pagination",
        icon: "i-lucide-file-text",
        description: "Display a list of pages.",
        to: "/docs/components/pagination"
      },
      {
        label: "Popover",
        icon: "i-lucide-file-text",
        description: "Display a non-modal dialog that floats around a trigger element.",
        to: "/docs/components/popover"
      },
      {
        label: "Progress",
        icon: "i-lucide-file-text",
        description: "Show a horizontal bar to indicate task progression.",
        to: "/docs/components/progress"
      }
    ]
  }
])
</script>

<template>
  <UNavigationMenu arrow :items="items" class="w-full justify-center" />
</template>
```

> \[!NOTE]
>
> A seta é animada para acompanhar o item ativo.

### Orientação do conteúdo

Use a prop `content-orientation` para alterar a orientação do conteúdo.

> \[!WARNING]
>
> Esta prop só funciona quando a `orientation` é `horizontal`.

```vue
<script setup lang="ts">
import type { NavigationMenuItem } from '@nitro/ui'

const items = ref<NavigationMenuItem[]>([
  {
    label: "Guide",
    icon: "i-lucide-book-open",
    to: "/docs/getting-started",
    children: [
      {
        label: "Introduction",
        description: "Fully styled and customizable components for Nuxt.",
        icon: "i-lucide-house"
      },
      {
        label: "Installation",
        description: "Learn how to install and configure Nitro UI in your application.",
        icon: "i-lucide-cloud-download"
      },
      {
        label: "Icons",
        icon: "i-lucide-smile",
        description: "You have nothing to do, @nuxt/icon will handle it automatically."
      }
    ]
  },
  {
    label: "Composables",
    icon: "i-lucide-database",
    to: "/docs/composables",
    children: [
      {
        label: "defineShortcuts",
        icon: "i-lucide-file-text",
        description: "Define shortcuts for your application.",
        to: "/docs/composables/define-shortcuts"
      },
      {
        label: "useOverlay",
        icon: "i-lucide-file-text",
        description: "Display a modal/slideover within your application.",
        to: "/docs/composables/use-overlay"
      },
      {
        label: "useToast",
        icon: "i-lucide-file-text",
        description: "Display a toast within your application.",
        to: "/docs/composables/use-toast"
      }
    ]
  },
  {
    label: "Components",
    icon: "i-lucide-box",
    to: "/docs/components",
    active: true,
    children: [
      {
        label: "Link",
        icon: "i-lucide-file-text",
        description: "Use NuxtLink with superpowers.",
        to: "/docs/components/link"
      },
      {
        label: "Modal",
        icon: "i-lucide-file-text",
        description: "Display a modal within your application.",
        to: "/docs/components/modal"
      },
      {
        label: "NavigationMenu",
        icon: "i-lucide-file-text",
        description: "Display a list of links.",
        to: "/docs/components/navigation-menu"
      },
      {
        label: "Pagination",
        icon: "i-lucide-file-text",
        description: "Display a list of pages.",
        to: "/docs/components/pagination"
      }
    ]
  }
])
</script>

<template>
  <UNavigationMenu arrow content-orientation="vertical" :items="items" class="w-full justify-center" />
</template>
```

### Desmontar

Use a prop `unmount-on-hide` para controlar o comportamento de desmontagem do conteúdo. O padrão é `true`.

```vue
<script setup lang="ts">
import type { NavigationMenuItem } from '@nitro/ui'

const items = ref<NavigationMenuItem[]>([
  {
    label: "Guide",
    icon: "i-lucide-book-open",
    to: "/docs/getting-started",
    children: [
      {
        label: "Introduction",
        description: "Fully styled and customizable components for Nuxt.",
        icon: "i-lucide-house"
      },
      {
        label: "Installation",
        description: "Learn how to install and configure Nitro UI in your application.",
        icon: "i-lucide-cloud-download"
      },
      {
        label: "Icons",
        icon: "i-lucide-smile",
        description: "You have nothing to do, @nuxt/icon will handle it automatically."
      },
      {
        label: "Colors",
        icon: "i-lucide-swatch-book",
        description: "Choose a primary and a neutral color from your Tailwind CSS theme."
      },
      {
        label: "Theme",
        icon: "i-lucide-cog",
        description: "You can customize components by using the `class` / `ui` props or in your app.config.ts."
      }
    ]
  },
  {
    label: "Composables",
    icon: "i-lucide-database",
    to: "/docs/composables",
    children: [
      {
        label: "defineShortcuts",
        icon: "i-lucide-file-text",
        description: "Define shortcuts for your application.",
        to: "/docs/composables/define-shortcuts"
      },
      {
        label: "useOverlay",
        icon: "i-lucide-file-text",
        description: "Display a modal/slideover within your application.",
        to: "/docs/composables/use-overlay"
      },
      {
        label: "useToast",
        icon: "i-lucide-file-text",
        description: "Display a toast within your application.",
        to: "/docs/composables/use-toast"
      }
    ]
  },
  {
    label: "Components",
    icon: "i-lucide-box",
    to: "/docs/components",
    active: true,
    children: [
      {
        label: "Link",
        icon: "i-lucide-file-text",
        description: "Use NuxtLink with superpowers.",
        to: "/docs/components/link"
      },
      {
        label: "Modal",
        icon: "i-lucide-file-text",
        description: "Display a modal within your application.",
        to: "/docs/components/modal"
      },
      {
        label: "NavigationMenu",
        icon: "i-lucide-file-text",
        description: "Display a list of links.",
        to: "/docs/components/navigation-menu"
      },
      {
        label: "Pagination",
        icon: "i-lucide-file-text",
        description: "Display a list of pages.",
        to: "/docs/components/pagination"
      },
      {
        label: "Popover",
        icon: "i-lucide-file-text",
        description: "Display a non-modal dialog that floats around a trigger element.",
        to: "/docs/components/popover"
      },
      {
        label: "Progress",
        icon: "i-lucide-file-text",
        description: "Show a horizontal bar to indicate task progression.",
        to: "/docs/components/progress"
      }
    ]
  }
])
</script>

<template>
  <UNavigationMenu :unmount-on-hide="false" :items="items" class="w-full justify-center" />
</template>
```

> \[!NOTE]
>
> Você pode inspecionar o DOM para ver o conteúdo de cada item sendo renderizado.

## Exemplos

### Controlar o item ativo

Você pode controlar o(s) item(ns) ativo(s) usando a prop `default-value` ou a diretiva `v-model` com o `value` do item. Se nenhum `value` for fornecido, o padrão é `item-${index}` para itens de nível superior ou `item-${level}-${index}` para itens aninhados.

::component-example{collapse name="navigation-menu-model-value-example"}
::

> \[!TIP]
>
> Use a prop `value-key` para alterar a chave usada para corresponder os itens quando um `v-model` ou `default-value` é fornecido.

> \[!NOTE]
>
> Neste exemplo, aproveitando o [`defineShortcuts`](https://ui.nitro.news/docs/composables/define-shortcuts), você pode trocar o item ativo pressionando :kbd{value="1"}, :kbd{value="2"} ou :kbd{value="3"}.

### Com tooltip nos itens

Quando a orientação é `vertical` e o menu está `collapsed`, você pode definir a prop `tooltip` como `true` para exibir um [Tooltip](https://ui.nitro.news/docs/components/tooltip) ao redor dos itens com o rótulo deles, mas você também pode usar a propriedade `tooltip` em cada item para sobrescrever o tooltip padrão. Na orientação `horizontal`, você pode usar a propriedade `tooltip` em cada item para exibir um [Tooltip](https://ui.nitro.news/docs/components/tooltip) ao redor dos itens.

> \[!NOTE]
>
> A propriedade `tooltip` em um item sempre exibirá um tooltip, independentemente da prop `tooltip` global.

Você pode passar qualquer propriedade do componente [Tooltip](https://ui.nitro.news/docs/components/tooltip) globalmente ou em cada item.

```vue
<script setup lang="ts">
import type { NavigationMenuItem } from '@nitro/ui'

const items = ref<NavigationMenuItem[][]>([
  [
    {
      label: "Links",
      type: "label"
    },
    {
      label: "Guide",
      icon: "i-lucide-book-open",
      children: [
        {
          label: "Introduction",
          description: "Fully styled and customizable components for Nuxt.",
          icon: "i-lucide-house"
        },
        {
          label: "Installation",
          description: "Learn how to install and configure Nitro UI in your application.",
          icon: "i-lucide-cloud-download"
        },
        {
          label: "Icons",
          icon: "i-lucide-smile",
          description: "You have nothing to do, @nuxt/icon will handle it automatically."
        },
        {
          label: "Colors",
          icon: "i-lucide-swatch-book",
          description: "Choose a primary and a neutral color from your Tailwind CSS theme."
        },
        {
          label: "Theme",
          icon: "i-lucide-cog",
          description: "You can customize components by using the `class` / `ui` props or in your app.config.ts."
        }
      ]
    },
    {
      label: "Composables",
      icon: "i-lucide-database",
      children: [
        {
          label: "defineShortcuts",
          icon: "i-lucide-file-text",
          description: "Define shortcuts for your application.",
          to: "/docs/composables/define-shortcuts"
        },
        {
          label: "useOverlay",
          icon: "i-lucide-file-text",
          description: "Display a modal/slideover within your application.",
          to: "/docs/composables/use-overlay"
        },
        {
          label: "useToast",
          icon: "i-lucide-file-text",
          description: "Display a toast within your application.",
          to: "/docs/composables/use-toast"
        }
      ]
    },
    {
      label: "Components",
      icon: "i-lucide-box",
      to: "/docs/components",
      active: true,
      children: [
        {
          label: "Link",
          icon: "i-lucide-file-text",
          description: "Use NuxtLink with superpowers.",
          to: "/docs/components/link"
        },
        {
          label: "Modal",
          icon: "i-lucide-file-text",
          description: "Display a modal within your application.",
          to: "/docs/components/modal"
        },
        {
          label: "NavigationMenu",
          icon: "i-lucide-file-text",
          description: "Display a list of links.",
          to: "/docs/components/navigation-menu"
        },
        {
          label: "Pagination",
          icon: "i-lucide-file-text",
          description: "Display a list of pages.",
          to: "/docs/components/pagination"
        },
        {
          label: "Popover",
          icon: "i-lucide-file-text",
          description: "Display a non-modal dialog that floats around a trigger element.",
          to: "/docs/components/popover"
        },
        {
          label: "Progress",
          icon: "i-lucide-file-text",
          description: "Show a horizontal bar to indicate task progression.",
          to: "/docs/components/progress"
        }
      ]
    }
  ],
  [
    {
      label: "GitLab",
      icon: "i-simple-icons-gitlab",
      badge: "6k",
      to: "https://github.com/nuxt/ui",
      target: "_blank",
      tooltip: {
        text: "Open on GitHub",
        kbds: [
          "6k"
        ]
      }
    },
    {
      label: "Help",
      icon: "i-lucide-circle-help",
      disabled: true
    }
  ]
])
</script>

<template>
  <UNavigationMenu tooltip collapsed orientation="vertical" :items="items" />
</template>
```

### Com popover nos itens

Quando a orientação é `vertical` e o menu está `collapsed`, você pode definir a prop `popover` como `true` para exibir um [Popover](https://ui.nitro.news/docs/components/popover) ao redor dos itens com os filhos deles, mas você também pode usar a propriedade `popover` em cada item para sobrescrever o popover padrão.

> \[!NOTE]
>
> A propriedade `popover` em um item sempre exibirá um popover, independentemente da prop `popover` global.

Você pode passar qualquer propriedade do componente [Popover](https://ui.nitro.news/docs/components/popover) globalmente ou em cada item.

```vue
<script setup lang="ts">
import type { NavigationMenuItem } from '@nitro/ui'

const items = ref<NavigationMenuItem[][]>([
  [
    {
      label: "Links",
      type: "label"
    },
    {
      label: "Guide",
      icon: "i-lucide-book-open",
      children: [
        {
          label: "Introduction",
          description: "Fully styled and customizable components for Nuxt.",
          icon: "i-lucide-house"
        },
        {
          label: "Installation",
          description: "Learn how to install and configure Nitro UI in your application.",
          icon: "i-lucide-cloud-download"
        },
        {
          label: "Icons",
          icon: "i-lucide-smile",
          description: "You have nothing to do, @nuxt/icon will handle it automatically."
        },
        {
          label: "Colors",
          icon: "i-lucide-swatch-book",
          description: "Choose a primary and a neutral color from your Tailwind CSS theme."
        },
        {
          label: "Theme",
          icon: "i-lucide-cog",
          description: "You can customize components by using the `class` / `ui` props or in your app.config.ts."
        }
      ]
    },
    {
      label: "Composables",
      icon: "i-lucide-database",
      popover: {
        mode: "click"
      },
      children: [
        {
          label: "defineShortcuts",
          icon: "i-lucide-file-text",
          description: "Define shortcuts for your application.",
          to: "/docs/composables/define-shortcuts"
        },
        {
          label: "useOverlay",
          icon: "i-lucide-file-text",
          description: "Display a modal/slideover within your application.",
          to: "/docs/composables/use-overlay"
        },
        {
          label: "useToast",
          icon: "i-lucide-file-text",
          description: "Display a toast within your application.",
          to: "/docs/composables/use-toast"
        }
      ]
    },
    {
      label: "Components",
      icon: "i-lucide-box",
      to: "/docs/components",
      active: true,
      children: [
        {
          label: "Link",
          icon: "i-lucide-file-text",
          description: "Use NuxtLink with superpowers.",
          to: "/docs/components/link"
        },
        {
          label: "Modal",
          icon: "i-lucide-file-text",
          description: "Display a modal within your application.",
          to: "/docs/components/modal"
        },
        {
          label: "NavigationMenu",
          icon: "i-lucide-file-text",
          description: "Display a list of links.",
          to: "/docs/components/navigation-menu"
        },
        {
          label: "Pagination",
          icon: "i-lucide-file-text",
          description: "Display a list of pages.",
          to: "/docs/components/pagination"
        },
        {
          label: "Popover",
          icon: "i-lucide-file-text",
          description: "Display a non-modal dialog that floats around a trigger element.",
          to: "/docs/components/popover"
        },
        {
          label: "Progress",
          icon: "i-lucide-file-text",
          description: "Show a horizontal bar to indicate task progression.",
          to: "/docs/components/progress"
        }
      ]
    }
  ],
  [
    {
      label: "GitLab",
      icon: "i-simple-icons-gitlab",
      badge: "6k",
      to: "https://github.com/nuxt/ui",
      target: "_blank",
      tooltip: {
        text: "Open on GitHub",
        kbds: [
          "6k"
        ]
      }
    },
    {
      label: "Help",
      icon: "i-lucide-circle-help",
      disabled: true
    }
  ]
])
</script>

<template>
  <UNavigationMenu popover collapsed orientation="vertical" :items="items" />
</template>
```

> \[!TIP]
> See: #with-content-slot
>
> Você pode usar o slot `#content` para personalizar o conteúdo do popover na orientação `vertical`.

### Com chip nos itens `4.5+`

Use a propriedade `chip` para exibir um [Chip](https://ui.nitro.news/docs/components/chip) ao redor do ícone dos itens; você pode passar qualquer uma das props dele.

```vue
<script setup lang="ts">
import type { NavigationMenuItem } from '@nitro/ui'

const items = ref<NavigationMenuItem[][]>([
  [
    {
      label: "Guide",
      icon: "i-lucide-book-open",
      chip: {
        color: "error"
      }
    },
    {
      label: "Composables",
      icon: "i-lucide-database",
      chip: {
        color: "info",
        text: 3
      }
    },
    {
      label: "Components",
      icon: "i-lucide-box",
      to: "/docs/components",
      active: true,
      chip: true
    }
  ],
  [
    {
      label: "GitLab",
      icon: "i-simple-icons-gitlab",
      to: "https://github.com/nuxt/ui",
      target: "_blank"
    },
    {
      label: "Help",
      icon: "i-lucide-circle-help",
      disabled: true
    }
  ]
])
</script>

<template>
  <UNavigationMenu collapsed orientation="vertical" :items="items" />
</template>
```

### Com barra de abas inferior

Use a prop `ui` para transformar o NavigationMenu em uma barra de abas inferior no estilo mobile, com ícones e rótulos pequenos, semelhante ao YouTube ou Instagram.

::component-example{collapse name="navigation-menu-bottom-tab-bar-example"}
::

### Com rótulos recolhidos

Use a prop `ui` para exibir um rótulo abaixo de cada ícone quando recolhido.

::component-example{collapse name="navigation-menu-collapsed-label-example"}
::

> \[!TIP]
>
> Você também pode fazer isso globalmente por meio do `app.config.ts` usando [`compoundVariants`](https://ui.nitro.news/docs/getting-started/theme/components#compound-variants):
>
> ```ts [app/app.config.ts]
> export default defineAppConfig({
>   ui: {
>     navigationMenu: {
>       compoundVariants: [{
>         orientation: 'vertical',
>         collapsed: true,
>         class: {
>           link: 'flex-col',
>           linkLabel: 'block text-[10px]/3 text-center'
>         }
>       }]
>     }
>   }
> })
> ```

### Com slot personalizado

Use a propriedade `slot` para personalizar um item específico.

Você terá acesso aos seguintes slots:

- `#{{ item.slot }}`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `#{{ item.slot }}-leading`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `#{{ item.slot }}-label`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `#{{ item.slot }}-trailing`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `#{{ item.slot }}-content`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

::component-example{collapse name="navigation-menu-custom-slot-example"}
::

> \[!TIP]
> See: #slots
>
> Você também pode usar os slots `#item`, `#item-leading`, `#item-label`, `#item-trailing` e `#item-content` para personalizar todos os itens.

### Com slot à direita

Use o slot `#item-trailing` ou a propriedade `slot` (`#{{ item.slot }}-trailing`) para adicionar um [DropdownMenu](https://ui.nitro.news/docs/components/dropdown-menu) que aparece no hover, semelhante ao Notion ou Linear.

::component-example{collapse name="navigation-menu-trailing-slot-example"}
::

### Com slot de conteúdo

Use o slot `#item-content` ou a propriedade `slot` (`#{{ item.slot }}-content`) para personalizar o conteúdo de um item específico.

::component-example{collapse name="navigation-menu-content-slot-example"}
::

> \[!NOTE]
>
> Neste exemplo, adicionamos a classe `sm:w-(--reka-navigation-menu-viewport-width)` no `viewport` para ter uma largura dinâmica. Isso exige definir uma largura no primeiro filho do conteúdo.

## API

### Props

```ts
/**
 * Props for the NavigationMenu component
 */
interface NavigationMenuProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  /**
   * Determines whether a "single" or "multiple" items can be selected at a time.
   * 
   * Only works when `orientation` is `vertical`.
   * @default "\"multiple\" as never"
   */
  type?: K | undefined;
  /**
   * The controlled value of the active item(s).
   * - In horizontal orientation: always `string`
   * - In vertical orientation with `type="single"`: `string`
   * - In vertical orientation with `type="multiple"`: `string[]`
   * 
   * Use this when you need to control the state of the items. Can be binded with `v-model`
   */
  modelValue?: NavigationMenuModelValue<K, O> | undefined;
  /**
   * The default active value of the item(s).
   * - In horizontal orientation: always `string`
   * - In vertical orientation with `type="single"`: `string`
   * - In vertical orientation with `type="multiple"`: `string[]`
   * 
   * Use when you do not need to control the state of the item(s).
   */
  defaultValue?: NavigationMenuModelValue<K, O> | undefined;
  /**
   * The icon displayed to open the menu.
   */
  trailingIcon?: any;
  /**
   * The icon displayed when the item is an external link.
   * Set to `false` to hide the external icon.
   * @default "true"
   */
  externalIcon?: any;
  items?: T | undefined;
  color?: "primary" | "secondary" | "accent" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
  variant?: "pill" | "link" | undefined;
  /**
   * The orientation of the menu.
   * @default "\"horizontal\" as never"
   */
  orientation?: O | undefined;
  /**
   * Collapse the navigation menu to only show icons.
   * Only works when `orientation` is `vertical`.
   */
  collapsed?: boolean | undefined;
  /**
   * Display a tooltip on the items with the label of the item.
   * Only works when `orientation` is `vertical` and `collapsed` is `true`.
   * `{ delayDuration: 0, content: { side: 'right' } }`{lang="ts-type"}
   */
  tooltip?: boolean | TooltipProps | undefined;
  /**
   * Display a popover on the items when the menu is collapsed with the children list.
   * `{ mode: 'hover', content: { side: 'right', align: 'start', alignOffset: 2 } }`{lang="ts-type"}
   */
  popover?: boolean | PopoverProps<PopoverMode> | undefined;
  /**
   * Display a line next to the active item.
   */
  highlight?: boolean | undefined;
  highlightColor?: "primary" | "secondary" | "accent" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
  /**
   * The content of the menu.
   */
  content?: (Omit<NavigationMenuContentProps, "as" | "asChild" | "forceMount"> & Partial<EmitsToProps<DismissableLayerEmits>>) | undefined;
  /**
   * The orientation of the content.
   * Only works when `orientation` is `horizontal`.
   * @default "\"horizontal\""
   */
  contentOrientation?: "horizontal" | "vertical" | undefined;
  /**
   * Display an arrow alongside the menu.
   */
  arrow?: boolean | undefined;
  /**
   * The key used to get the value from the item.
   * @default "\"value\""
   */
  valueKey?: GetItemKeys<T> | undefined;
  /**
   * The key used to get the label from the item.
   * @default "\"label\""
   */
  labelKey?: GetItemKeys<T> | undefined;
  ui?: { root?: SlotClass; list?: SlotClass; label?: SlotClass; item?: SlotClass; link?: SlotClass; linkLeadingIcon?: SlotClass; linkLeadingAvatar?: SlotClass; linkLeadingAvatarSize?: SlotClass; linkLeadingChipSize?: SlotClass; linkTrailing?: SlotClass; linkTrailingBadge?: SlotClass; linkTrailingBadgeSize?: SlotClass; linkTrailingIcon?: SlotClass; linkLabel?: SlotClass; linkLabelExternalIcon?: SlotClass; childList?: SlotClass; childLabel?: SlotClass; childItem?: SlotClass; childLink?: SlotClass; childLinkWrapper?: SlotClass; childLinkIcon?: SlotClass; childLinkLabel?: SlotClass; childLinkLabelExternalIcon?: SlotClass; childLinkDescription?: SlotClass; separator?: SlotClass; viewportWrapper?: SlotClass; viewport?: SlotClass; content?: SlotClass; indicator?: SlotClass; arrow?: SlotClass; } | undefined;
  /**
   * The duration from when the pointer enters the trigger until the tooltip gets opened.
   * @default "0"
   */
  delayDuration?: number | undefined;
  /**
   * If `true`, menu cannot be open by click on trigger
   */
  disableClickTrigger?: boolean | undefined;
  /**
   * If `true`, menu cannot be open by hover on trigger
   */
  disableHoverTrigger?: boolean | undefined;
  /**
   * How much time a user has to enter another trigger without incurring a delay again.
   */
  skipDelayDuration?: number | undefined;
  /**
   * If `true`, menu will not close during pointer leave event
   */
  disablePointerLeaveClose?: boolean | undefined;
  /**
   * When `true`, the element will be unmounted on closed state.
   * @default "true"
   */
  unmountOnHide?: boolean | undefined;
  /**
   * When `true`, prevents the user from interacting with the accordion and all its items
   */
  disabled?: boolean | undefined;
  /**
   * When type is "single", allows closing content when clicking trigger for an open item.
   * When type is "multiple", this prop has no effect.
   * @default "true"
   */
  collapsible?: boolean | undefined;
}
```

### Slots

```ts
/**
 * Slots for the NavigationMenu component
 */
interface NavigationMenuSlots {
  item(): any;
  item-leading(): any;
  item-label(): any;
  item-trailing(): any;
  item-content(): any;
  list-leading(): any;
  list-trailing(): any;
}
```

### Emits

```ts
/**
 * Emitted events for the NavigationMenu component
 */
interface NavigationMenuEmits {
  update:modelValue: (payload: [value: NavigationMenuModelValue<K, O> | undefined]) => void;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    navigationMenu: {
      slots: {
        root: 'relative flex gap-1.5 [&>div]:min-w-0',
        list: 'isolate min-w-0',
        label: 'w-full flex items-center gap-1.5 font-semibold text-xs/5 text-highlighted px-2.5 py-1.5',
        item: 'min-w-0',
        link: 'group relative w-full flex items-center gap-1.5 font-medium text-sm before:absolute before:z-[-1] before:rounded-md focus:outline-none focus-visible:outline-none focus-visible:before:outline-3',
        linkLeadingIcon: 'shrink-0 size-5',
        linkLeadingAvatar: 'shrink-0',
        linkLeadingAvatarSize: '2xs',
        linkLeadingChipSize: 'sm',
        linkTrailing: 'group ms-auto inline-flex gap-1.5 items-center',
        linkTrailingBadge: 'shrink-0',
        linkTrailingBadgeSize: 'sm',
        linkTrailingIcon: 'size-5 transform shrink-0 group-data-[state=open]:rotate-180 transition-transform duration-200',
        linkLabel: 'truncate',
        linkLabelExternalIcon: 'inline-block size-3 align-top text-dimmed',
        childList: 'isolate',
        childLabel: 'text-xs text-highlighted',
        childItem: '',
        childLink: 'group relative size-full flex items-start text-start text-sm before:absolute before:z-[-1] before:rounded-md focus:outline-none focus-visible:outline-none focus-visible:before:outline-3',
        childLinkWrapper: 'min-w-0',
        childLinkIcon: 'size-5 shrink-0',
        childLinkLabel: 'truncate',
        childLinkLabelExternalIcon: 'inline-block size-3 align-top text-dimmed',
        childLinkDescription: 'text-muted',
        separator: 'px-2 h-px bg-border',
        viewportWrapper: 'absolute top-full left-0 flex w-full',
        viewport: 'relative overflow-hidden bg-default shadow-lg rounded-md ring ring-default h-(--reka-navigation-menu-viewport-height) w-full transition-[width,height,left,right] duration-200 origin-[top_center] data-[state=open]:animate-[scale-in_100ms_ease-out] data-[state=closed]:animate-[scale-out_100ms_ease-in] z-1',
        content: '',
        indicator: 'absolute left-0 data-[state=visible]:animate-[fade-in_100ms_ease-out] data-[state=hidden]:animate-[fade-out_100ms_ease-in] data-[state=hidden]:opacity-0 bottom-0 z-2 w-(--reka-navigation-menu-indicator-size) translate-x-(--reka-navigation-menu-indicator-position) flex h-2.5 items-end justify-center overflow-hidden transition-[translate,width] duration-200',
        arrow: 'relative top-[50%] size-2.5 rotate-45 border border-default bg-default z-1 rounded-xs'
      },
      variants: {
        color: {
          primary: {
            link: 'before:outline-primary/25',
            childLink: 'before:outline-primary/25'
          },
          secondary: {
            link: 'before:outline-secondary/25',
            childLink: 'before:outline-secondary/25'
          },
          accent: {
            link: 'before:outline-accent/25',
            childLink: 'before:outline-accent/25'
          },
          success: {
            link: 'before:outline-success/25',
            childLink: 'before:outline-success/25'
          },
          info: {
            link: 'before:outline-info/25',
            childLink: 'before:outline-info/25'
          },
          warning: {
            link: 'before:outline-warning/25',
            childLink: 'before:outline-warning/25'
          },
          error: {
            link: 'before:outline-error/25',
            childLink: 'before:outline-error/25'
          },
          neutral: {
            link: 'before:outline-inverted/25',
            childLink: 'before:outline-inverted/25'
          }
        },
        highlightColor: {
          primary: '',
          secondary: '',
          accent: '',
          success: '',
          info: '',
          warning: '',
          error: '',
          neutral: ''
        },
        variant: {
          pill: '',
          link: ''
        },
        orientation: {
          horizontal: {
            root: 'items-center justify-between',
            list: 'flex items-center',
            item: 'py-2',
            link: 'px-2.5 py-1.5 before:inset-x-px before:inset-y-0',
            childList: 'grid p-2',
            childLink: 'px-3 py-2 gap-2 before:inset-x-px before:inset-y-0',
            childLinkLabel: 'font-medium',
            content: 'absolute top-0 left-0 w-full max-h-[70vh] overflow-y-auto'
          },
          vertical: {
            root: 'flex-col',
            link: 'flex-row px-2.5 py-1.5 before:inset-y-px before:inset-x-0',
            childLabel: 'px-1.5 py-0.5',
            childLink: 'p-1.5 gap-1.5 before:inset-y-px before:inset-x-0'
          }
        },
        contentOrientation: {
          horizontal: {
            viewportWrapper: 'justify-center',
            content: 'data-[motion=from-start]:animate-[enter-from-left_200ms_ease] data-[motion=from-end]:animate-[enter-from-right_200ms_ease] data-[motion=to-start]:animate-[exit-to-left_200ms_ease] data-[motion=to-end]:animate-[exit-to-right_200ms_ease]'
          },
          vertical: {
            viewport: 'sm:w-(--reka-navigation-menu-viewport-width) left-(--reka-navigation-menu-viewport-left) rtl:left-auto rtl:right-[calc(100%-var(--reka-navigation-menu-viewport-left)-var(--reka-navigation-menu-viewport-width))]'
          }
        },
        active: {
          true: {
            childLink: 'before:bg-elevated text-highlighted',
            childLinkIcon: 'text-default'
          },
          false: {
            link: 'text-muted',
            linkLeadingIcon: 'text-dimmed',
            childLink: [
              'hover:before:bg-elevated/50 text-default hover:text-highlighted',
              'transition-colors before:transition-colors'
            ],
            childLinkIcon: [
              'text-dimmed group-hover:text-default',
              'transition-colors'
            ]
          }
        },
        disabled: {
          true: {
            link: 'cursor-not-allowed opacity-75'
          }
        },
        highlight: {
          true: ''
        },
        level: {
          true: ''
        },
        collapsed: {
          true: ''
        }
      },
      compoundVariants: [
        {
          orientation: 'horizontal',
          contentOrientation: 'horizontal',
          class: {
            childList: 'grid-cols-2 gap-2'
          }
        },
        {
          orientation: 'horizontal',
          contentOrientation: 'vertical',
          class: {
            childList: 'gap-1',
            content: 'w-60'
          }
        },
        {
          orientation: 'vertical',
          collapsed: false,
          class: {
            childList: 'ms-5 border-s border-default',
            childItem: 'ps-1.5 -ms-px',
            content: 'data-[state=open]:animate-[collapsible-down_200ms_ease-out] data-[state=closed]:animate-[collapsible-up_200ms_ease-out] data-[state=closed]:overflow-hidden'
          }
        },
        {
          orientation: 'vertical',
          collapsed: true,
          class: {
            link: 'px-1.5',
            linkLabel: 'hidden',
            linkTrailing: 'hidden',
            content: 'shadow-sm rounded-sm min-h-6 p-1'
          }
        },
        {
          orientation: 'horizontal',
          highlight: true,
          class: {
            link: [
              'after:absolute after:-bottom-2 after:inset-x-2.5 after:block after:h-px after:rounded-full',
              'after:transition-colors'
            ]
          }
        },
        {
          orientation: 'vertical',
          highlight: true,
          level: true,
          class: {
            link: [
              'after:absolute after:-start-1.5 after:inset-y-0.5 after:block after:w-px after:rounded-full',
              'after:transition-colors'
            ]
          }
        },
        {
          disabled: false,
          active: false,
          variant: 'pill',
          class: {
            link: [
              'hover:text-highlighted hover:before:bg-elevated/50',
              'transition-colors before:transition-colors'
            ],
            linkLeadingIcon: [
              'group-hover:text-default',
              'transition-colors'
            ]
          }
        },
        {
          disabled: false,
          active: false,
          variant: 'pill',
          orientation: 'horizontal',
          class: {
            link: 'data-[state=open]:text-highlighted',
            linkLeadingIcon: 'group-data-[state=open]:text-default'
          }
        },
        {
          disabled: false,
          variant: 'pill',
          highlight: true,
          orientation: 'horizontal',
          class: {
            link: 'data-[state=open]:before:bg-elevated/50'
          }
        },
        {
          disabled: false,
          variant: 'pill',
          highlight: false,
          active: false,
          orientation: 'horizontal',
          class: {
            link: 'data-[state=open]:before:bg-elevated/50'
          }
        },
        {
          color: 'primary',
          variant: 'pill',
          active: true,
          class: {
            link: 'text-primary',
            linkLeadingIcon: 'text-primary group-data-[state=open]:text-primary'
          }
        },
        {
          color: 'secondary',
          variant: 'pill',
          active: true,
          class: {
            link: 'text-secondary',
            linkLeadingIcon: 'text-secondary group-data-[state=open]:text-secondary'
          }
        },
        {
          color: 'accent',
          variant: 'pill',
          active: true,
          class: {
            link: 'text-accent',
            linkLeadingIcon: 'text-accent group-data-[state=open]:text-accent'
          }
        },
        {
          color: 'success',
          variant: 'pill',
          active: true,
          class: {
            link: 'text-success',
            linkLeadingIcon: 'text-success group-data-[state=open]:text-success'
          }
        },
        {
          color: 'info',
          variant: 'pill',
          active: true,
          class: {
            link: 'text-info',
            linkLeadingIcon: 'text-info group-data-[state=open]:text-info'
          }
        },
        {
          color: 'warning',
          variant: 'pill',
          active: true,
          class: {
            link: 'text-warning',
            linkLeadingIcon: 'text-warning group-data-[state=open]:text-warning'
          }
        },
        {
          color: 'error',
          variant: 'pill',
          active: true,
          class: {
            link: 'text-error',
            linkLeadingIcon: 'text-error group-data-[state=open]:text-error'
          }
        },
        {
          color: 'neutral',
          variant: 'pill',
          active: true,
          class: {
            link: 'text-highlighted',
            linkLeadingIcon: 'text-highlighted group-data-[state=open]:text-highlighted'
          }
        },
        {
          variant: 'pill',
          active: true,
          highlight: false,
          class: {
            link: 'before:bg-elevated'
          }
        },
        {
          variant: 'pill',
          active: true,
          highlight: true,
          disabled: false,
          class: {
            link: [
              'hover:before:bg-elevated/50',
              'before:transition-colors'
            ]
          }
        },
        {
          disabled: false,
          active: false,
          variant: 'link',
          class: {
            link: [
              'hover:text-highlighted',
              'transition-colors'
            ],
            linkLeadingIcon: [
              'group-hover:text-default',
              'transition-colors'
            ]
          }
        },
        {
          disabled: false,
          active: false,
          variant: 'link',
          orientation: 'horizontal',
          class: {
            link: 'data-[state=open]:text-highlighted',
            linkLeadingIcon: 'group-data-[state=open]:text-default'
          }
        },
        {
          color: 'primary',
          variant: 'link',
          active: true,
          class: {
            link: 'text-primary',
            linkLeadingIcon: 'text-primary group-data-[state=open]:text-primary'
          }
        },
        {
          color: 'secondary',
          variant: 'link',
          active: true,
          class: {
            link: 'text-secondary',
            linkLeadingIcon: 'text-secondary group-data-[state=open]:text-secondary'
          }
        },
        {
          color: 'accent',
          variant: 'link',
          active: true,
          class: {
            link: 'text-accent',
            linkLeadingIcon: 'text-accent group-data-[state=open]:text-accent'
          }
        },
        {
          color: 'success',
          variant: 'link',
          active: true,
          class: {
            link: 'text-success',
            linkLeadingIcon: 'text-success group-data-[state=open]:text-success'
          }
        },
        {
          color: 'info',
          variant: 'link',
          active: true,
          class: {
            link: 'text-info',
            linkLeadingIcon: 'text-info group-data-[state=open]:text-info'
          }
        },
        {
          color: 'warning',
          variant: 'link',
          active: true,
          class: {
            link: 'text-warning',
            linkLeadingIcon: 'text-warning group-data-[state=open]:text-warning'
          }
        },
        {
          color: 'error',
          variant: 'link',
          active: true,
          class: {
            link: 'text-error',
            linkLeadingIcon: 'text-error group-data-[state=open]:text-error'
          }
        },
        {
          color: 'neutral',
          variant: 'link',
          active: true,
          class: {
            link: 'text-highlighted',
            linkLeadingIcon: 'text-highlighted group-data-[state=open]:text-highlighted'
          }
        },
        {
          highlightColor: 'primary',
          highlight: true,
          level: true,
          active: true,
          class: {
            link: 'after:bg-primary'
          }
        },
        {
          highlightColor: 'secondary',
          highlight: true,
          level: true,
          active: true,
          class: {
            link: 'after:bg-secondary'
          }
        },
        {
          highlightColor: 'accent',
          highlight: true,
          level: true,
          active: true,
          class: {
            link: 'after:bg-accent'
          }
        },
        {
          highlightColor: 'success',
          highlight: true,
          level: true,
          active: true,
          class: {
            link: 'after:bg-success'
          }
        },
        {
          highlightColor: 'info',
          highlight: true,
          level: true,
          active: true,
          class: {
            link: 'after:bg-info'
          }
        },
        {
          highlightColor: 'warning',
          highlight: true,
          level: true,
          active: true,
          class: {
            link: 'after:bg-warning'
          }
        },
        {
          highlightColor: 'error',
          highlight: true,
          level: true,
          active: true,
          class: {
            link: 'after:bg-error'
          }
        },
        {
          highlightColor: 'neutral',
          highlight: true,
          level: true,
          active: true,
          class: {
            link: 'after:bg-inverted'
          }
        }
      ],
      defaultVariants: {
        color: 'primary',
        highlightColor: 'primary',
        variant: 'pill'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/NavigationMenu.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/navigation-menu.ts).


# Page

## Uso

O componente Page ajuda você a criar layouts com colunas esquerda e direita opcionais. Ele é perfeito para construir sites de documentação e outras páginas focadas em conteúdo.

```vue {2,6}
<template>
  <NPage>
    <template #left />

    <template #right />
  </NPage>
</template>
```

> \[!TIP]
>
> A página é exibida como um layout de coluna única centralizado se nenhum slot for especificado.

## Exemplos

> \[!NOTE]
>
> Embora estes exemplos usem o [Nuxt Content](https://content.nuxt.com){rel="&#x22;nofollow&#x22;"}, os componentes podem ser integrados a qualquer sistema de gerenciamento de conteúdo.

### Dentro de um layout

Use o componente Page em um layout com o slot `left` para exibir uma navegação:

```vue [layouts/docs.vue] {9-13}
<script setup lang="ts">
import type { ContentNavigationItem } from '@nuxt/content'

const navigation = inject<Ref<ContentNavigationItem[]>>('navigation')
</script>

<template>
  <NPage>
    <template #left>
      <NPageAside>
        <NContentNavigation :navigation="navigation" />
      </NPageAside>
    </template>

    <slot />
  </NPage>
</template>
```

> \[!NOTE]
>
> Neste exemplo, usamos o componente `ContentNavigation` para exibir a navegação injetada em `app.vue`.

### Dentro de uma página

Use o componente Page em uma página com o slot `right` para exibir um sumário:

```vue [pages/[...slug\\].vue] {29-31}
<script setup lang="ts">
const route = useRoute()

definePageMeta({
  layout: 'docs'
})

const { data: page } = await useAsyncData(route.path, () => {
  return queryCollection('docs').path(route.path).first()
})

const { data: surround } = await useAsyncData(`${route.path}-surround`, () => {
  return queryCollectionItemSurroundings('content', route.path)
})
</script>

<template>
  <NPage>
    <NPageHeader :title="page.title" :description="page.description" />

    <NPageBody>
      <ContentRenderer :value="page" />

      <NSeparator />

      <NContentSurround :surround="surround" />
    </NPageBody>

    <template #right>
      <NContentToc :links="page.body.toc.links" />
    </template>
  </NPage>
</template>
```

> \[!NOTE]
>
> Neste exemplo, usamos o componente `ContentToc` para exibir o sumário.

## API

### Props

```ts
/**
 * Props for the Page component
 */
interface PageProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  ui?: { root?: SlotClass; left?: SlotClass; center?: SlotClass; right?: SlotClass; } | undefined;
}
```

### Slots

```ts
/**
 * Slots for the Page component
 */
interface PageSlots {
  left(): any;
  default(): any;
  right(): any;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    page: {
      slots: {
        root: 'flex flex-col lg:grid lg:grid-cols-10 lg:gap-10',
        left: 'lg:col-span-2',
        center: 'lg:col-span-8',
        right: 'lg:col-span-2 order-first lg:order-last'
      },
      variants: {
        left: {
          true: ''
        },
        right: {
          true: ''
        }
      },
      compoundVariants: [
        {
          left: true,
          right: true,
          class: {
            center: 'lg:col-span-6'
          }
        },
        {
          left: false,
          right: false,
          class: {
            center: 'lg:col-span-10'
          }
        }
      ]
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/Page.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/page.ts).


# PageAnchors

## Uso

Use o componente PageAnchors para exibir uma lista de links.

```vue
<script setup lang="ts">
import type { PageAnchor } from '@nitro/ui'

const links = ref<PageAnchor[]>([
  {
    label: "Documentation",
    icon: "i-lucide-book-open",
    to: "/docs/getting-started"
  },
  {
    label: "Components",
    icon: "i-lucide-box",
    to: "/docs/components"
  },
  {
    label: "Figma Kit",
    icon: "i-simple-icons-figma",
    to: "https://go.nuxt.com/figma-ui",
    target: "_blank"
  },
  {
    label: "Releases",
    icon: "i-simple-icons-gitlab",
    to: "https://github.com/nuxt/ui/releases",
    target: "_blank"
  }
])
</script>

<template>
  <UPageAnchors :links="links" />
</template>
```

### Links

Use a prop `links` como um array de objetos com as seguintes propriedades:

- `label: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `icon?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `class?: any`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `ui?: { item?: ClassNameValue, link?: ClassNameValue, linkLabel?: ClassNameValue, linkLabelExternalIcon?: ClassNameValue, linkLeading?: ClassNameValue, linkLeadingIcon?: ClassNameValue }`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Você pode passar qualquer propriedade do componente [Link](https://ui.nitro.news/docs/components/link#props), como `to`, `target`, etc.

```vue
<script setup lang="ts">
import type { PageAnchor } from '@nitro/ui'

const links = ref<PageAnchor[]>([
  {
    label: "Documentation",
    icon: "i-lucide-book-open",
    to: "/docs/getting-started"
  },
  {
    label: "Components",
    icon: "i-lucide-box",
    to: "/docs/components"
  },
  {
    label: "Figma Kit",
    icon: "i-simple-icons-figma",
    to: "https://go.nuxt.com/figma-ui",
    target: "_blank"
  },
  {
    label: "Releases",
    icon: "i-simple-icons-gitlab",
    to: "https://github.com/nuxt/ui/releases",
    target: "_blank"
  }
])
</script>

<template>
  <UPageAnchors :links="links" />
</template>
```

## Exemplos

> \[!NOTE]
>
> Embora estes exemplos usem o [Nuxt Content](https://content.nuxt.com){rel="&#x22;nofollow&#x22;"}, os componentes podem ser integrados a qualquer sistema de gerenciamento de conteúdo.

### Dentro de um layout

Use o componente PageAnchors dentro do componente [PageAside](https://ui.nitro.news/docs/components/page-aside) para exibir uma lista de links acima da navegação.

```vue [layouts/docs.vue] {35}
<script setup lang="ts">
import type { PageAnchor } from '@nitro/ui'
import type { ContentNavigationItem } from '@nuxt/content'

const navigation = inject<ContentNavigationItem[]>('navigation')

const links: PageAnchor[] = [{
  label: 'Documentation',
  icon: 'i-lucide-book-open',
  to: '/docs/getting-started'
}, {
  label: 'Components',
  icon: 'i-lucide-box',
  to: '/docs/components'
}, {
  label: 'Figma Kit',
  icon: 'i-simple-icons-figma',
  to: 'https://go.nuxt.com/figma-ui',
  target: '_blank'
}, {
  label: 'Releases',
  icon: 'i-lucide-rocket',
  to: 'https://github.com/nuxt/ui/releases',
  target: '_blank'
}]
</script>

<template>
  <NPage>
    <template #left>
      <NPageAside>
        <NPageAnchors :links="links" />

        <NSeparator type="dashed" />

        <NContentNavigation :navigation="navigation" />
      </NPageAside>
    </template>

    <slot />
  </NPage>
</template>
```

## API

### Props

```ts
/**
 * Props for the PageAnchors component
 */
interface PageAnchorsProps {
  /**
   * The element or component this component should render as.
   * @default "\"nav\""
   */
  as?: any;
  links?: T[] | undefined;
  ui?: { root?: SlotClass; list?: SlotClass; item?: SlotClass; link?: SlotClass; linkLeading?: SlotClass; linkLeadingIcon?: SlotClass; linkLabel?: SlotClass; linkLabelExternalIcon?: SlotClass; } | undefined;
}
```

### Slots

```ts
/**
 * Slots for the PageAnchors component
 */
interface PageAnchorsSlots {
  link(): any;
  link-leading(): any;
  link-label(): any;
  link-trailing(): any;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    pageAnchors: {
      slots: {
        root: '',
        list: '',
        item: 'relative',
        link: 'group text-sm flex items-center gap-1.5 py-1 rounded-sm outline-primary/25 focus-visible:outline-3',
        linkLeading: 'rounded-md p-1 inline-flex ring-inset ring',
        linkLeadingIcon: 'size-4 shrink-0',
        linkLabel: 'truncate',
        linkLabelExternalIcon: 'size-3 absolute top-0 text-dimmed'
      },
      variants: {
        active: {
          true: {
            link: 'text-primary font-semibold',
            linkLeading: 'bg-primary ring-primary text-inverted'
          },
          false: {
            link: [
              'text-muted hover:text-default font-medium',
              'transition-colors'
            ],
            linkLeading: [
              'bg-elevated/50 ring-accented text-dimmed group-hover:bg-primary group-hover:ring-primary group-hover:text-inverted',
              'transition'
            ]
          }
        }
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/PageAnchors.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/page-anchors.ts).


# PageAside

## Uso

O componente PageAside é um elemento `<aside>` fixo que só é exibido a partir do [breakpoint `lg`](https://tailwindcss.com/docs/breakpoints){rel="&#x22;nofollow&#x22;"}.

> \[!TIP]
> See: /docs/getting-started/theme/css-variables#header
>
> O componente PageAside usa a variável CSS `--ui-header-height` para se posicionar corretamente abaixo do `Header`.

Use-o dentro do slot `left` ou `right` do componente [Page](https://ui.nitro.news/docs/components/page):

```vue {4}
<template>
  <NPage>
    <template #left>
      <NPageAside />
    </template>
  </NPage>
</template>
```

## Exemplos

> \[!NOTE]
>
> Embora estes exemplos usem o [Nuxt Content](https://content.nuxt.com){rel="&#x22;nofollow&#x22;"}, os componentes podem ser integrados a qualquer sistema de gerenciamento de conteúdo.

### Dentro de um layout

Use o componente PageAside em um layout para exibir a navegação:

```vue [layouts/docs.vue] {9-13}
<script setup lang="ts">
import type { ContentNavigationItem } from '@nuxt/content'

const navigation = inject<Ref<ContentNavigationItem[]>>('navigation')
</script>

<template>
  <NPage>
    <template #left>
      <NPageAside>
        <NContentNavigation :navigation="navigation" />
      </NPageAside>
    </template>

    <slot />
  </NPage>
</template>
```

> \[!NOTE]
>
> Neste exemplo, usamos o componente `ContentNavigation` para exibir a navegação injetada em `app.vue`.

## API

### Props

```ts
/**
 * Props for the PageAside component
 */
interface PageAsideProps {
  /**
   * The element or component this component should render as.
   * @default "\"aside\""
   */
  as?: any;
  ui?: { root?: SlotClass; container?: SlotClass; top?: SlotClass; topHeader?: SlotClass; topBody?: SlotClass; topFooter?: SlotClass; } | undefined;
}
```

### Slots

```ts
/**
 * Slots for the PageAside component
 */
interface PageAsideSlots {
  top(): any;
  default(): any;
  bottom(): any;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    pageAside: {
      slots: {
        root: 'hidden overflow-y-auto lg:block lg:max-h-[calc(100vh-var(--ui-header-height))] lg:sticky lg:top-(--ui-header-height) py-8 lg:ps-4 lg:-ms-4 lg:pe-6.5',
        container: 'relative',
        top: 'sticky -top-8 -mt-8 pointer-events-none z-[1]',
        topHeader: 'h-8 bg-default -mx-4 px-4',
        topBody: 'bg-default relative pointer-events-auto flex flex-col -mx-4 px-4',
        topFooter: 'h-8 bg-gradient-to-b from-default -mx-4 px-4'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/PageAside.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/page-aside.ts).


# PageBody

## Uso

O componente PageBody envolve o seu conteúdo principal e adiciona um espaçamento interno para um espaçamento consistente.

Use-o dentro do slot padrão do componente [Page](https://ui.nitro.news/docs/components/page), após o componente [PageHeader](https://ui.nitro.news/docs/components/page-header):

```vue {5}
<template>
  <NPage>
    <NPageHeader />

    <NPageBody />
  </NPage>
</template>
```

## Exemplos

> \[!NOTE]
>
> Embora estes exemplos usem o [Nuxt Content](https://content.nuxt.com){rel="&#x22;nofollow&#x22;"}, os componentes podem ser integrados a qualquer sistema de gerenciamento de conteúdo.

### Dentro de uma página

Use o componente PageBody em uma página para exibir o conteúdo da página:

```vue [pages/[...slug\\].vue] {21-27}
<script setup lang="ts">
const route = useRoute()

definePageMeta({
  layout: 'docs'
})

const { data: page } = await useAsyncData(route.path, () => {
  return queryCollection('docs').path(route.path).first()
})

const { data: surround } = await useAsyncData(`${route.path}-surround`, () => {
  return queryCollectionItemSurroundings('content', route.path)
})
</script>

<template>
  <NPage>
    <NPageHeader :title="page.title" :description="page.description" />

    <NPageBody>
      <ContentRenderer :value="page" />

      <NSeparator />

      <NContentSurround :surround="surround" />
    </NPageBody>

    <template #right>
      <NContentToc :links="page.body.toc.links" />
    </template>
  </NPage>
</template>
```

> \[!NOTE]
>
> Neste exemplo, usamos o componente [`ContentRenderer`](https://content.nuxt.com/docs/components/content-renderer){rel="&#x22;nofollow&#x22;"} do `@nuxt/content` para renderizar o conteúdo da página.

## API

### Props

```ts
/**
 * Props for the PageBody component
 */
interface PageBodyProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  ui?: { base?: any; } | undefined;
}
```

### Slots

```ts
/**
 * Slots for the PageBody component
 */
interface PageBodySlots {
  default(): any;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    pageBody: {
      base: 'mt-8 pb-24 space-y-12'
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/PageBody.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/page-body.ts).


# PageCard

## Uso

O componente PageCard oferece uma maneira flexível de exibir conteúdo em um card, com uma ilustração no slot padrão.

```vue
<template>
  <n-page-card description=O Nitro UI se integra à versão mais recente do Tailwind CSS, trazendo melhorias significativas. icon=i-simple-icons-tailwindcss title=Tailwind CSS>
  <img alt=Tailwind CSS src=/tailwindcss-v4.svg /></n-page-card>
</template>
```

> \[!TIP]
>
> Use os componentes [PageGrid](https://ui.nitro.news/docs/components/page-grid), [PageColumns](https://ui.nitro.news/docs/components/page-columns) ou [PageList](https://ui.nitro.news/docs/components/page-list) para exibir vários PageCard.

### Título

Use a prop `title` para definir o título do card.

```vue
<template>
  <UPageCard title="Tailwind CSS" />
</template>
```

### Descrição

Use a prop `description` para definir a descrição do card.

```vue
<template>
  <UPageCard title="Tailwind CSS" description="Nitro UI integrates with latest Tailwind CSS, bringing significant improvements." />
</template>
```

### Ícone

Use a prop `icon` para definir o ícone do card.

```vue
<template>
  <UPageCard title="Tailwind CSS" description="Nitro UI integrates with latest Tailwind CSS, bringing significant improvements." icon="i-simple-icons-tailwindcss" />
</template>
```

### Link

Você pode passar qualquer propriedade do componente [`<NuxtLink>`](https://nuxt.com/docs/api/components/nuxt-link){rel="&#x22;nofollow&#x22;"}, como `to`, `target`, `rel`, etc.

```vue
<template>
  <UPageCard title="Tailwind CSS" description="Nitro UI integrates with latest Tailwind CSS, bringing significant improvements." icon="i-simple-icons-tailwindcss" to="https://tailwindcss.com/docs/v4-beta" target="_blank" />
</template>
```

### Variante

Use a prop `variant` para alterar o estilo do card.

```vue
<template>
  <UPageCard title="Tailwind CSS" description="Nitro UI integrates with latest Tailwind CSS, bringing significant improvements." icon="i-simple-icons-tailwindcss" to="https://tailwindcss.com/docs/v4-beta" target="_blank" variant="soft" />
</template>
```

> \[!TIP]
>
> Você pode aplicar a classe `light` ou `dark` ao slot `links` ao usar a variante `solid` para inverter as cores.

### Orientação

Use a prop `orientation` para alterar a orientação com o slot padrão. O padrão é `vertical`.

```vue
<template>
  <UPageCard title="Tailwind CSS" description="Nitro UI integrates with latest Tailwind CSS, bringing significant improvements." icon="i-simple-icons-tailwindcss" orientation="horizontal">
    <img src="/tailwindcss-v4.svg" alt="Tailwind CSS" class="w-full" />
  </UPageCard>
</template>
```

### Invertido

Use a prop `reverse` para inverter a orientação do slot padrão.

```vue
<template>
  <UPageCard title="Tailwind CSS" description="Nitro UI integrates with latest Tailwind CSS, bringing significant improvements." icon="i-simple-icons-tailwindcss" orientation="horizontal" reverse>
    <img src="/tailwindcss-v4.svg" alt="Tailwind CSS" class="w-full" />
  </UPageCard>
</template>
```

### Destaque

Use as props `highlight` e `highlight-color` para exibir uma borda destacada ao redor do card.

```vue
<template>
  <UPageCard title="Tailwind CSS" description="Nitro UI integrates with latest Tailwind CSS, bringing significant improvements." icon="i-simple-icons-tailwindcss" orientation="horizontal" highlight highlight-color="primary">
    <img src="/tailwindcss-v4.svg" alt="Tailwind CSS" class="w-full" />
  </UPageCard>
</template>
```

### Destaque

Use as props `spotlight` e `spotlight-color` para exibir um efeito de holofote que acompanha o cursor do mouse e destaca as bordas no hover.

> \[!NOTE]
>
> O efeito de holofote assume o lugar dos efeitos de hover ao usar uma prop `to`. É melhor usá-lo com a variante `outline`.

```vue
<template>
  <UPageCard title="Tailwind CSS" description="Nitro UI integrates with latest Tailwind CSS, bringing significant improvements." icon="i-simple-icons-tailwindcss" orientation="horizontal" spotlight spotlight-color="primary">
    <img src="/tailwindcss-v4.svg" alt="Tailwind CSS" class="w-full" />
  </UPageCard>
</template>
```

> \[!TIP]
>
> Você também pode personalizar a cor e o tamanho usando as variáveis CSS `--spotlight-color` e `--spotlight-size`:
>
> ```vue
> <template>
>   <NPageCard spotlight class="[--spotlight-color:var(--ui-error)] [--spotlight-size:200px]" />
> </template>
> ```

## Exemplos

### Como depoimento

Use o componente [User](https://ui.nitro.news/docs/components/user) no slot `header` ou `footer` para dar ao card a aparência de um depoimento.

:component-example{name="page-card-testimonial-example"}

> \[!TIP]
> See: /docs/components/page-columns
>
> Você pode usar o componente `PageColumns` para exibir vários PageCard em um layout de múltiplas colunas.

## API

### Props

```ts
/**
 * Props for the PageCard component
 */
interface PageCardProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  /**
   * The icon displayed above the title.
   */
  icon?: any;
  title?: string | undefined;
  description?: string | undefined;
  /**
   * The orientation of the page card.
   * @default "\"vertical\""
   */
  orientation?: "vertical" | "horizontal" | undefined;
  /**
   * Reverse the order of the default slot.
   */
  reverse?: boolean | undefined;
  /**
   * Display a line around the page card.
   */
  highlight?: boolean | undefined;
  highlightColor?: "error" | "primary" | "secondary" | "accent" | "success" | "info" | "warning" | "neutral" | undefined;
  /**
   * Display a spotlight effect that follows your mouse cursor and highlights borders on hover.
   */
  spotlight?: boolean | undefined;
  spotlightColor?: "error" | "primary" | "secondary" | "accent" | "success" | "info" | "warning" | "neutral" | undefined;
  variant?: "solid" | "outline" | "soft" | "subtle" | "ghost" | "naked" | undefined;
  to?: string | it | et | undefined;
  target?: "_blank" | "_parent" | "_self" | "_top" | (string & {}) | null | undefined;
  onClick?: ((event: MouseEvent) => void) | undefined;
  ui?: { root?: SlotClass; spotlight?: SlotClass; container?: SlotClass; wrapper?: SlotClass; header?: SlotClass; body?: SlotClass; footer?: SlotClass; leading?: SlotClass; leadingIcon?: SlotClass; title?: SlotClass; description?: SlotClass; } | undefined;
}
```

### Slots

```ts
/**
 * Slots for the PageCard component
 */
interface PageCardSlots {
  header(): any;
  body(): any;
  leading(): any;
  title(): any;
  description(): any;
  footer(): any;
  default(): any;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    pageCard: {
      slots: {
        root: 'relative flex rounded-lg',
        spotlight: 'absolute inset-0 rounded-[inherit] pointer-events-none bg-default/90',
        container: 'relative flex flex-col flex-1 lg:grid gap-x-8 gap-y-4 p-4 sm:p-6',
        wrapper: 'flex flex-col flex-1 items-start',
        header: 'mb-4',
        body: 'flex-1',
        footer: 'pt-4 mt-auto',
        leading: 'inline-flex items-center mb-2.5',
        leadingIcon: 'size-5 shrink-0 text-primary',
        title: 'text-base text-pretty font-semibold text-highlighted',
        description: 'text-[15px] text-pretty'
      },
      variants: {
        orientation: {
          horizontal: {
            container: 'lg:grid-cols-2 lg:items-center'
          },
          vertical: {
            container: ''
          }
        },
        reverse: {
          true: {
            wrapper: 'order-last'
          }
        },
        variant: {
          solid: {
            root: 'bg-inverted text-inverted',
            title: 'text-inverted',
            description: 'text-dimmed'
          },
          outline: {
            root: 'bg-default ring ring-default',
            description: 'text-muted'
          },
          soft: {
            root: 'bg-elevated/50',
            description: 'text-toned'
          },
          subtle: {
            root: 'bg-elevated/50 ring ring-default',
            description: 'text-toned'
          },
          ghost: {
            description: 'text-muted'
          },
          naked: {
            container: 'p-0 sm:p-0',
            description: 'text-muted'
          }
        },
        to: {
          true: {
            root: [
              'outline-primary/25 has-[>a:focus-visible]:outline-3',
              'transition'
            ]
          }
        },
        title: {
          true: {
            description: 'mt-1'
          }
        },
        highlight: {
          true: {
            root: 'ring-2'
          }
        },
        highlightColor: {
          primary: '',
          secondary: '',
          accent: '',
          success: '',
          info: '',
          warning: '',
          error: '',
          neutral: ''
        },
        spotlight: {
          true: {
            root: '[--spotlight-size:400px] before:absolute before:-inset-px before:pointer-events-none before:rounded-[inherit] before:bg-[radial-gradient(var(--spotlight-size)_var(--spotlight-size)_at_calc(var(--spotlight-x,0px))_calc(var(--spotlight-y,0px)),var(--spotlight-color),transparent_70%)]'
          }
        },
        spotlightColor: {
          primary: '',
          secondary: '',
          accent: '',
          success: '',
          info: '',
          warning: '',
          error: '',
          neutral: ''
        }
      },
      compoundVariants: [
        {
          variant: 'solid',
          to: true,
          class: {
            root: 'hover:bg-inverted/90'
          }
        },
        {
          variant: 'outline',
          to: true,
          class: {
            root: 'hover:bg-elevated/50'
          }
        },
        {
          variant: 'soft',
          to: true,
          class: {
            root: 'hover:bg-elevated'
          }
        },
        {
          variant: 'subtle',
          to: true,
          class: {
            root: 'hover:bg-elevated'
          }
        },
        {
          variant: 'subtle',
          to: true,
          highlight: false,
          class: {
            root: 'hover:ring-accented'
          }
        },
        {
          variant: [
            'outline',
            'subtle'
          ],
          to: true,
          highlight: false,
          class: {
            root: 'has-[>a:focus-visible]:ring-primary'
          }
        },
        {
          variant: 'ghost',
          to: true,
          class: {
            root: 'hover:bg-elevated/50'
          }
        },
        {
          highlightColor: 'primary',
          highlight: true,
          class: {
            root: 'ring-primary'
          }
        },
        {
          highlightColor: 'secondary',
          highlight: true,
          class: {
            root: 'ring-secondary'
          }
        },
        {
          highlightColor: 'accent',
          highlight: true,
          class: {
            root: 'ring-accent'
          }
        },
        {
          highlightColor: 'success',
          highlight: true,
          class: {
            root: 'ring-success'
          }
        },
        {
          highlightColor: 'info',
          highlight: true,
          class: {
            root: 'ring-info'
          }
        },
        {
          highlightColor: 'warning',
          highlight: true,
          class: {
            root: 'ring-warning'
          }
        },
        {
          highlightColor: 'error',
          highlight: true,
          class: {
            root: 'ring-error'
          }
        },
        {
          highlightColor: 'neutral',
          highlight: true,
          class: {
            root: 'ring-inverted'
          }
        },
        {
          spotlightColor: 'primary',
          spotlight: true,
          class: {
            root: '[--spotlight-color:var(--ui-primary)]'
          }
        },
        {
          spotlightColor: 'secondary',
          spotlight: true,
          class: {
            root: '[--spotlight-color:var(--ui-secondary)]'
          }
        },
        {
          spotlightColor: 'accent',
          spotlight: true,
          class: {
            root: '[--spotlight-color:var(--ui-accent)]'
          }
        },
        {
          spotlightColor: 'success',
          spotlight: true,
          class: {
            root: '[--spotlight-color:var(--ui-success)]'
          }
        },
        {
          spotlightColor: 'info',
          spotlight: true,
          class: {
            root: '[--spotlight-color:var(--ui-info)]'
          }
        },
        {
          spotlightColor: 'warning',
          spotlight: true,
          class: {
            root: '[--spotlight-color:var(--ui-warning)]'
          }
        },
        {
          spotlightColor: 'error',
          spotlight: true,
          class: {
            root: '[--spotlight-color:var(--ui-error)]'
          }
        },
        {
          spotlightColor: 'neutral',
          spotlight: true,
          class: {
            root: '[--spotlight-color:var(--ui-bg-inverted)]'
          }
        }
      ],
      defaultVariants: {
        variant: 'outline',
        highlightColor: 'primary',
        spotlightColor: 'primary'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/PageCard.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/page-card.ts).


# PageColumns

## Uso

O componente PageColumns exibe conteúdo em um layout responsivo de múltiplas colunas. Ele funciona bem com componentes [PageCard](https://ui.nitro.news/docs/components/page-card) ou quaisquer outros elementos, adaptando-se de uma única coluna no mobile para várias colunas em telas maiores.

::component-example{.p-8 collapse name="page-columns-example"}
::

## API

### Props

```ts
/**
 * Props for the PageColumns component
 */
interface PageColumnsProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  ui?: { base?: any; } | undefined;
}
```

### Slots

```ts
/**
 * Slots for the PageColumns component
 */
interface PageColumnsSlots {
  default(): any;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    pageColumns: {
      base: 'relative column-1 md:columns-2 lg:columns-3 gap-8 space-y-8 *:break-inside-avoid-column *:will-change-transform'
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/PageColumns.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/page-columns.ts).


# PageCTA

## Uso

O componente PageCTA oferece uma maneira flexível de exibir uma chamada para ação nas suas páginas, com uma ilustração no slot padrão.

```vue
<template>
  <n-page-c-t-a :links=[{"label":"Get started","color":"neutral"},{"label":"Learn more","color":"neutral","variant":"subtle","trailingIcon":"i-lucide-arrow-right"}] description=Conheça a versão mais recente do Tailwind CSS e comece a usar o Nitro UI. orientation=horizontal title=Com a confiança e o apoio da nossa incrível comunidade>
  <img alt=Illustration src=https://picsum.photos/640/616 /></n-page-c-t-a>
</template>
```

Use-o dentro de um componente [PageSection](https://ui.nitro.news/docs/components/page-section) ou diretamente na sua página:

```vue {4,8-10}
<template>
  <NPageHero />

  <NPageCTA class="rounded-none" />

  <NPageSection />

  <NPageSection :ui="{ container: 'px-0' }">
    <NPageCTA class="rounded-none sm:rounded-xl" />
  </NPageSection>

  <NPageSection />
</template>
```

> \[!TIP]
>
> Use as classes `px-0` e `rounded-none` para fazer o CTA preencher até a borda da página no mobile.

### Título

Use a prop `title` para definir o título do CTA.

```vue
<template>
  <UPageCTA title="Trusted and supported by our amazing community" />
</template>
```

### Descrição

Use a prop `description` para definir a descrição do CTA.

```vue
<template>
  <UPageCTA title="Trusted and supported by our amazing community" description="We've built a strong, lasting partnership. Their trust is our driving force, propelling us towards shared success." />
</template>
```

### Links

Use a prop `links` para exibir uma lista de [Button](https://ui.nitro.news/docs/components/button) abaixo da descrição.

```vue
<script setup lang="ts">
import type { ButtonProps } from '@nitro/ui'

const links = ref<ButtonProps[]>([
  {
    label: "Get started",
    color: "neutral"
  },
  {
    label: "Learn more",
    color: "neutral",
    variant: "subtle",
    trailingIcon: "i-lucide-arrow-right"
  }
])
</script>

<template>
  <UPageCTA title="Trusted and supported by our amazing community" description="We've built a strong, lasting partnership. Their trust is our driving force, propelling us towards shared success." :links="links" />
</template>
```

### Variante

Use a prop `variant` para alterar o estilo do CTA.

```vue
<script setup lang="ts">
import type { ButtonProps } from '@nitro/ui'

const links = ref<ButtonProps[]>([
  {
    label: "Get started",
    color: "neutral"
  },
  {
    label: "Learn more",
    color: "neutral",
    variant: "subtle",
    trailingIcon: "i-lucide-arrow-right"
  }
])
</script>

<template>
  <UPageCTA title="Trusted and supported by our amazing community" description="We've built a strong, lasting partnership. Their trust is our driving force, propelling us towards shared success." variant="soft" :links="links" />
</template>
```

> \[!TIP]
>
> Você pode aplicar a classe `light` ou `dark` ao slot `links` ao usar a variante `solid` para inverter as cores.

### Orientação

Use a prop `orientation` para alterar a orientação com o slot padrão. O padrão é `vertical`.

```vue
<script setup lang="ts">
import type { ButtonProps } from '@nitro/ui'

const links = ref<ButtonProps[]>([
  {
    label: "Get started",
    color: "neutral"
  },
  {
    label: "Learn more",
    color: "neutral",
    variant: "subtle",
    trailingIcon: "i-lucide-arrow-right"
  }
])
</script>

<template>
  <UPageCTA title="Trusted and supported by our amazing community" description="We've built a strong, lasting partnership. Their trust is our driving force, propelling us towards shared success." orientation="horizontal" :links="links">
    <img src="https://picsum.photos/640/728" width="320" height="364" alt="Illustration" class="w-full rounded-lg" loading="lazy" />
  </UPageCTA>
</template>
```

### Invertido

Use a prop `reverse` para inverter a orientação do slot padrão.

```vue
<script setup lang="ts">
import type { ButtonProps } from '@nitro/ui'

const links = ref<ButtonProps[]>([
  {
    label: "Get started",
    color: "neutral"
  },
  {
    label: "Learn more",
    color: "neutral",
    variant: "subtle",
    trailingIcon: "i-lucide-arrow-right"
  }
])
</script>

<template>
  <UPageCTA title="Trusted and supported by our amazing community" description="We've built a strong, lasting partnership. Their trust is our driving force, propelling us towards shared success." orientation="horizontal" reverse :links="links">
    <img src="https://picsum.photos/640/728" width="320" height="364" alt="Illustration" class="w-full rounded-lg" loading="lazy" />
  </UPageCTA>
</template>
```

## API

### Props

```ts
/**
 * Props for the PageCTA component
 */
interface PageCTAProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  title?: string | undefined;
  description?: string | undefined;
  /**
   * The orientation of the page cta.
   * @default "\"vertical\""
   */
  orientation?: "vertical" | "horizontal" | undefined;
  /**
   * Reverse the order of the default slot.
   * @default "false"
   */
  reverse?: boolean | undefined;
  variant?: "outline" | "solid" | "soft" | "subtle" | "naked" | undefined;
  /**
   * Display a list of Button under the description.
   * `{ size: 'lg' }`{lang="ts-type"}
   */
  links?: ButtonProps[] | undefined;
  ui?: { root?: SlotClass; container?: SlotClass; wrapper?: SlotClass; header?: SlotClass; title?: SlotClass; description?: SlotClass; body?: SlotClass; footer?: SlotClass; links?: SlotClass; } | undefined;
}
```

### Slots

```ts
/**
 * Slots for the PageCTA component
 */
interface PageCTASlots {
  top(): any;
  header(): any;
  title(): any;
  description(): any;
  body(): any;
  footer(): any;
  links(): any;
  default(): any;
  bottom(): any;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    pageCTA: {
      slots: {
        root: 'relative isolate rounded-xl overflow-hidden',
        container: 'flex flex-col lg:grid px-6 py-12 sm:px-12 sm:py-24 lg:px-16 lg:py-24 gap-8 sm:gap-16',
        wrapper: '',
        header: '',
        title: 'text-3xl sm:text-4xl text-pretty tracking-tight font-bold text-highlighted',
        description: 'text-base sm:text-lg text-muted',
        body: 'mt-8',
        footer: 'mt-8',
        links: 'flex flex-wrap gap-x-6 gap-y-3'
      },
      variants: {
        orientation: {
          horizontal: {
            container: 'lg:grid-cols-2 lg:items-center',
            description: 'text-pretty'
          },
          vertical: {
            container: '',
            title: 'text-center',
            description: 'text-center text-balance',
            links: 'justify-center'
          }
        },
        reverse: {
          true: {
            wrapper: 'order-last'
          }
        },
        variant: {
          solid: {
            root: 'bg-inverted text-inverted',
            title: 'text-inverted',
            description: 'text-dimmed'
          },
          outline: {
            root: 'bg-default ring ring-default',
            description: 'text-muted'
          },
          soft: {
            root: 'bg-elevated/50',
            description: 'text-toned'
          },
          subtle: {
            root: 'bg-elevated/50 ring ring-default',
            description: 'text-toned'
          },
          naked: {
            description: 'text-muted'
          }
        },
        title: {
          true: {
            description: 'mt-6'
          }
        }
      },
      defaultVariants: {
        variant: 'outline'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/PageCTA.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/page-cta.ts).


# PageFeature

## Uso

O componente PageFeature é usado pelo componente [PageSection](https://ui.nitro.news/docs/components/page-section) para exibir [recursos](https://ui.nitro.news/docs/components/page-section#features).

### Título

Use a prop `title` para definir o título do recurso.

```vue
<template>
  <UPageFeature title="Theme" />
</template>
```

### Descrição

Use a prop `description` para definir a descrição do recurso.

```vue
<template>
  <UPageFeature title="Theme" description="Customize Nitro UI with your own colors, fonts, and more." />
</template>
```

### Ícone

Use a prop `icon` para definir o ícone do recurso.

```vue
<template>
  <UPageFeature title="Theme" description="Customize Nitro UI with your own colors, fonts, and more." icon="i-lucide-swatch-book" />
</template>
```

### Link

Você pode passar qualquer propriedade do componente [`<NuxtLink>`](https://nuxt.com/docs/api/components/nuxt-link){rel="&#x22;nofollow&#x22;"}, como `to`, `target`, `rel`, etc.

```vue
<template>
  <UPageFeature title="Theme" description="Customize Nitro UI with your own colors, fonts, and more." icon="i-lucide-swatch-book" to="/docs/getting-started/theme/design-system" target="_blank" />
</template>
```

### Orientação

Use a prop `orientation` para alterar a orientação do recurso. O padrão é `horizontal`.

```vue
<template>
  <UPageFeature orientation="vertical" title="Theme" description="Customize Nitro UI with your own colors, fonts, and more." icon="i-lucide-swatch-book" />
</template>
```

## API

### Props

```ts
/**
 * Props for the PageFeature component
 */
interface PageFeatureProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  /**
   * The icon displayed next to the title when `orientation` is `horizontal` and above the title when `orientation` is `vertical`.
   */
  icon?: any;
  title?: string | undefined;
  description?: string | undefined;
  /**
   * The orientation of the page feature.
   * @default "\"horizontal\""
   */
  orientation?: "horizontal" | "vertical" | undefined;
  to?: string | it | et | undefined;
  target?: "_blank" | "_parent" | "_self" | "_top" | (string & {}) | null | undefined;
  onClick?: ((event: MouseEvent) => void) | undefined;
  ui?: { root?: SlotClass; wrapper?: SlotClass; leading?: SlotClass; leadingIcon?: SlotClass; title?: SlotClass; description?: SlotClass; } | undefined;
}
```

### Slots

```ts
/**
 * Slots for the PageFeature component
 */
interface PageFeatureSlots {
  leading(): any;
  title(): any;
  description(): any;
  default(): any;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    pageFeature: {
      slots: {
        root: 'relative rounded-sm',
        wrapper: '',
        leading: 'inline-flex items-center justify-center',
        leadingIcon: 'size-5 shrink-0 text-primary',
        title: 'text-base text-pretty font-semibold text-highlighted',
        description: 'text-[15px] text-pretty text-muted'
      },
      variants: {
        orientation: {
          horizontal: {
            root: 'flex items-start gap-2.5',
            leading: 'p-0.5'
          },
          vertical: {
            leading: 'mb-2.5'
          }
        },
        to: {
          true: {
            root: [
              'outline-primary/25 has-focus-visible:outline-3',
              'transition'
            ]
          }
        },
        title: {
          true: {
            description: 'mt-1'
          }
        }
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/PageFeature.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/page-feature.ts).


# PageGrid

## Uso

O componente PageGrid oferece um layout de grade responsivo para exibir componentes [PageCard](https://ui.nitro.news/docs/components/page-card) ou quaisquer outros elementos, ajustando-se automaticamente de 1 a 3 colunas com base no tamanho da tela.

:component-example{.p-8 name="page-grid-example"}

Você também pode usá-lo para exibir uma lista de cards em um layout estilo bento usando as classes utilitárias `col-span-*` e `row-span-*`.

::component-example{.p-8 collapse name="page-grid-bento-example"}
::

## API

### Props

```ts
/**
 * Props for the PageGrid component
 */
interface PageGridProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  ui?: { base?: any; } | undefined;
}
```

### Slots

```ts
/**
 * Slots for the PageGrid component
 */
interface PageGridSlots {
  default(): any;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    pageGrid: {
      base: 'relative grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-8'
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/PageGrid.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/page-grid.ts).


# PageHeader

## Uso

O componente PageHeader exibe um cabeçalho para a sua página.

Use-o dentro do slot padrão do componente [Page](https://ui.nitro.news/docs/components/page), antes do componente [PageBody](https://ui.nitro.news/docs/components/page-body):

```vue {3}
<template>
  <NPage>
    <NPageHeader />

    <NPageBody />
  </NPage>
</template>
```

### Título

Use a prop `title` para exibir um título no cabeçalho.

```vue
<template>
  <UPageHeader title="PageHeader" />
</template>
```

### Descrição

Use a prop `description` para exibir uma descrição no cabeçalho.

```vue
<template>
  <UPageHeader title="PageHeader" description="A responsive page header with title, description and actions." />
</template>
```

### Título

Use a prop `headline` para exibir uma manchete no cabeçalho.

```vue
<template>
  <UPageHeader title="PageHeader" description="A responsive page header with title, description and actions." headline="Components" />
</template>
```

### Links

Use a prop `links` para exibir uma lista de [Button](https://ui.nitro.news/docs/components/button) no cabeçalho.

```vue
<script setup lang="ts">
import type { ButtonProps } from '@nitro/ui'

const links = ref<ButtonProps[]>([
  {
    label: "GitHub",
    icon: "i-simple-icons-gitlab",
    to: "https://gitlab.nitro.news/nitro/ui/-/tree/main/src/runtime/components/PageHeader.vue",
    target: "_blank"
  }
])
</script>

<template>
  <UPageHeader title="PageHeader" description="A responsive page header with title, description and actions." headline="Components" :links="links" />
</template>
```

## Exemplos

> \[!NOTE]
>
> Embora estes exemplos usem o [Nuxt Content](https://content.nuxt.com){rel="&#x22;nofollow&#x22;"}, os componentes podem ser integrados a qualquer sistema de gerenciamento de conteúdo.

### Dentro de uma página

Use o componente PageHeader em uma página para exibir o cabeçalho da página:

```vue [pages/[...slug\\].vue] {19-24}
<script setup lang="ts">
const route = useRoute()

definePageMeta({
  layout: 'docs'
})

const { data: page } = await useAsyncData(route.path, () => {
  return queryCollection('docs').path(route.path).first()
})

const { data: surround } = await useAsyncData(`${route.path}-surround`, () => {
  return queryCollectionItemSurroundings('content', route.path)
})
</script>

<template>
  <NPage>
    <NPageHeader
      :title="page.title"
      :description="page.description"
      :headline="page.headline"
      :links="page.links"
    />

    <NPageBody>
      <ContentRenderer :value="page" />

      <NSeparator />

      <NContentSurround :surround="surround" />
    </NPageBody>

    <template #right>
      <NContentToc :links="page.body.toc.links" />
    </template>
  </NPage>
</template>
```

## API

### Props

```ts
/**
 * Props for the PageHeader component
 */
interface PageHeaderProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  headline?: string | undefined;
  title?: string | undefined;
  description?: string | undefined;
  /**
   * Display a list of Button next to the title.
   * `{ color: 'neutral', variant: 'outline' }`{lang="ts-type"}
   */
  links?: ButtonProps[] | undefined;
  ui?: { root?: SlotClass; container?: SlotClass; wrapper?: SlotClass; headline?: SlotClass; title?: SlotClass; description?: SlotClass; links?: SlotClass; } | undefined;
}
```

### Slots

```ts
/**
 * Slots for the PageHeader component
 */
interface PageHeaderSlots {
  headline(): any;
  title(): any;
  description(): any;
  links(): any;
  default(): any;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    pageHeader: {
      slots: {
        root: 'relative border-b border-default py-8',
        container: '',
        wrapper: 'flex flex-col lg:flex-row lg:items-center lg:justify-between gap-4',
        headline: 'mb-2.5 text-sm font-semibold text-primary flex items-center gap-1.5',
        title: 'text-3xl sm:text-4xl text-pretty font-bold text-highlighted',
        description: 'text-lg text-pretty text-muted',
        links: 'flex flex-wrap items-center gap-1.5'
      },
      variants: {
        title: {
          true: {
            description: 'mt-4'
          }
        }
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/PageHeader.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/page-header.ts).


# PageHero

## Uso

O componente PageHero envolve o seu conteúdo em um [Container](https://ui.nitro.news/docs/components/container) mantendo a flexibilidade de largura total, facilitando a adição de cores de fundo, imagens ou padrões. Ele oferece uma maneira flexível de exibir conteúdo com uma ilustração no slot padrão.

```vue
<template>
  <n-page-hero description=Uma biblioteca de UI integrada ao Nuxt/Vue que oferece um rico conjunto de componentes totalmente estilizados, acessíveis e altamente personalizáveis para construir aplicações web modernas. title=A melhor biblioteca de UI para Vue>
  <n-page-card variant=subtle>
  <p>
  <img alt=App screenshot src=/blocks/image4.png /></p></n-page-card></n-page-hero>
</template>
```

### Título

Use a prop `title` para definir o título do hero.

```vue
<template>
  <UPageHero title="Ultimate Vue UI library" />
</template>
```

### Descrição

Use a prop `description` para definir a descrição do hero.

```vue
<template>
  <UPageHero title="Ultimate Vue UI library" description="A Nuxt/Vue-integrated UI library providing a rich set of fully-styled, accessible and highly customizable components for building modern web applications." />
</template>
```

### Título

Use a prop `headline` para definir a manchete do hero.

```vue
<template>
  <UPageHero title="Ultimate Vue UI library" description="A Nuxt/Vue-integrated UI library providing a rich set of fully-styled, accessible and highly customizable components for building modern web applications." headline="New release" />
</template>
```

### Links

Use a prop `links` para exibir uma lista de [Button](https://ui.nitro.news/docs/components/button) abaixo da descrição.

```vue
<script setup lang="ts">
import type { ButtonProps } from '@nitro/ui'

const links = ref<ButtonProps[]>([
  {
    label: "Get started",
    to: "/docs/getting-started",
    icon: "i-lucide-square-play"
  },
  {
    label: "Learn more",
    to: "/docs/getting-started/theme/design-system",
    color: "neutral",
    variant: "subtle",
    trailingIcon: "i-lucide-arrow-right"
  }
])
</script>

<template>
  <UPageHero title="Ultimate Vue UI library" description="A Nuxt/Vue-integrated UI library providing a rich set of fully-styled, accessible and highly customizable components for building modern web applications." :links="links" />
</template>
```

### Orientação

Use a prop `orientation` para alterar a orientação com o slot padrão. O padrão é `vertical`.

```vue
<script setup lang="ts">
import type { ButtonProps } from '@nitro/ui'

const links = ref<ButtonProps[]>([
  {
    label: "Get started",
    to: "/docs/getting-started",
    icon: "i-lucide-square-play"
  },
  {
    label: "Learn more",
    to: "/docs/getting-started/theme/design-system",
    color: "neutral",
    variant: "subtle",
    trailingIcon: "i-lucide-arrow-right"
  }
])
</script>

<template>
  <UPageHero title="Ultimate Vue UI library" description="A Nuxt/Vue-integrated UI library providing a rich set of fully-styled, accessible and highly customizable components for building modern web applications." headline="New release" orientation="horizontal" :links="links">
    <img src="/blocks/image4.png" alt="App screenshot" class="rounded-lg shadow-2xl ring ring-default" />
  </UPageHero>
</template>
```

### Invertido

Use a prop `reverse` para inverter a orientação do slot padrão.

```vue
<script setup lang="ts">
import type { ButtonProps } from '@nitro/ui'

const links = ref<ButtonProps[]>([
  {
    label: "Get started",
    to: "/docs/getting-started",
    icon: "i-lucide-square-play"
  },
  {
    label: "Learn more",
    to: "/docs/getting-started/theme/design-system",
    color: "neutral",
    variant: "subtle",
    trailingIcon: "i-lucide-arrow-right"
  }
])
</script>

<template>
  <UPageHero title="Ultimate Vue UI library" description="A Nuxt/Vue-integrated UI library providing a rich set of fully-styled, accessible and highly customizable components for building modern web applications." headline="New release" orientation="horizontal" reverse :links="links">
    <img src="/blocks/image4.png" alt="App screenshot" class="rounded-lg shadow-2xl ring ring-default" />
  </UPageHero>
</template>
```

## API

### Props

```ts
/**
 * Props for the PageHero component
 */
interface PageHeroProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  headline?: string | undefined;
  title?: string | undefined;
  description?: string | undefined;
  /**
   * Display a list of Button under the description.
   * `{ size: 'xl' }`{lang="ts-type"}
   */
  links?: ButtonProps[] | undefined;
  /**
   * The orientation of the page hero.
   * @default "\"vertical\""
   */
  orientation?: "horizontal" | "vertical" | undefined;
  /**
   * Reverse the order of the default slot.
   */
  reverse?: boolean | undefined;
  ui?: { root?: SlotClass; container?: SlotClass; wrapper?: SlotClass; header?: SlotClass; headline?: SlotClass; title?: SlotClass; description?: SlotClass; body?: SlotClass; footer?: SlotClass; links?: SlotClass; } | undefined;
}
```

### Slots

```ts
/**
 * Slots for the PageHero component
 */
interface PageHeroSlots {
  top(): any;
  header(): any;
  headline(): any;
  title(): any;
  description(): any;
  body(): any;
  footer(): any;
  links(): any;
  default(): any;
  bottom(): any;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    pageHero: {
      slots: {
        root: 'relative isolate',
        container: 'flex flex-col lg:grid py-24 sm:py-32 lg:py-40 gap-16 sm:gap-y-24',
        wrapper: '',
        header: '',
        headline: 'mb-4',
        title: 'text-5xl sm:text-7xl text-pretty tracking-tight font-bold text-highlighted',
        description: 'text-lg sm:text-xl/8 text-muted',
        body: 'mt-10',
        footer: 'mt-10',
        links: 'flex flex-wrap gap-x-6 gap-y-3'
      },
      variants: {
        orientation: {
          horizontal: {
            container: 'lg:grid-cols-2 lg:items-center',
            description: 'text-pretty'
          },
          vertical: {
            container: '',
            headline: 'justify-center',
            wrapper: 'text-center',
            description: 'text-balance',
            links: 'justify-center'
          }
        },
        reverse: {
          true: {
            wrapper: 'order-last'
          }
        },
        headline: {
          true: {
            headline: 'font-semibold text-primary flex items-center gap-1.5'
          }
        },
        title: {
          true: {
            description: 'mt-6'
          }
        }
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/PageHero.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/page-hero.ts).


# PageLinks

## Uso

Use o componente PageLinks para exibir uma lista de links.

```vue
<script setup lang="ts">
import type { PageLink } from '@nitro/ui'

const links = ref<PageLink[]>([
  {
    label: "Edit this page",
    icon: "i-lucide-file-pen",
    to: "https://gitlab.nitro.news/nitro/ui/-/blob/main/docs/content/3.components/page-links.md"
  },
  {
    label: "Star on GitHub",
    icon: "i-lucide-star",
    to: "https://github.com/nuxt/ui"
  },
  {
    label: "Releases",
    icon: "i-lucide-rocket",
    to: "https://github.com/nuxt/ui/releases"
  }
])
</script>

<template>
  <UPageLinks :links="links" />
</template>
```

### Links

Use a prop `links` como um array de objetos com as seguintes propriedades:

- `label: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `icon?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `class?: any`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `ui?: { item?: ClassNameValue, link?: ClassNameValue, linkLabel?: ClassNameValue, linkLabelExternalIcon?: ClassNameValue, linkLeadingIcon?: ClassNameValue }`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Você pode passar qualquer propriedade do componente [Link](https://ui.nitro.news/docs/components/link#props), como `to`, `target`, etc.

```vue
<script setup lang="ts">
import type { PageLink } from '@nitro/ui'

const links = ref<PageLink[]>([
  {
    label: "Edit this page",
    icon: "i-lucide-file-pen",
    to: "https://gitlab.nitro.news/nitro/ui/-/blob/main/docs/content/3.components/page-links.md"
  },
  {
    label: "Star on GitHub",
    icon: "i-lucide-star",
    to: "https://github.com/nuxt/ui"
  },
  {
    label: "Releases",
    icon: "i-lucide-rocket",
    to: "https://github.com/nuxt/ui/releases"
  }
])
</script>

<template>
  <UPageLinks :links="links" />
</template>
```

### Título

Use a prop `title` para exibir um título acima dos links.

```vue
<script setup lang="ts">
import type { PageLink } from '@nitro/ui'

const links = ref<PageLink[]>([
  {
    label: "Edit this page",
    icon: "i-lucide-file-pen",
    to: "https://gitlab.nitro.news/nitro/ui/-/blob/main/docs/content/3.components/page-links.md"
  },
  {
    label: "Star on GitHub",
    icon: "i-lucide-star",
    to: "https://github.com/nuxt/ui"
  },
  {
    label: "Releases",
    icon: "i-lucide-rocket",
    to: "https://github.com/nuxt/ui/releases"
  }
])
</script>

<template>
  <UPageLinks title="Community" :links="links" />
</template>
```

## Exemplos

> \[!NOTE]
>
> Embora estes exemplos usem o [Nuxt Content](https://content.nuxt.com){rel="&#x22;nofollow&#x22;"}, os componentes podem ser integrados a qualquer sistema de gerenciamento de conteúdo.

### Dentro de uma página

Use o componente PageLinks no slot `bottom` do componente ContentToc para exibir uma lista de links abaixo do sumário.

```vue [pages/[...slug\\].vue] {48-52}
<script setup lang="ts">
import type { PageLink } from '@nitro/ui'

const route = useRoute()

definePageMeta({
  layout: 'docs'
})

const { data: page } = await useAsyncData(route.path, () => {
  return queryCollection('docs').path(route.path).first()
})

const { data: surround } = await useAsyncData(`${route.path}-surround`, () => {
  return queryCollectionItemSurroundings('content', route.path)
})

const links = computed<PageLink[]>(() => [{
  icon: 'i-lucide-file-pen',
  label: 'Edit this page',
  to: `https://github.com/nuxt/ui/edit/v4/docs/content/${page?.value?.stem}.md`,
  target: '_blank'
}, {
  icon: 'i-lucide-star',
  label: 'Star on GitHub',
  to: 'https://github.com/nuxt/ui',
  target: '_blank'
}, {
  label: 'Releases',
  icon: 'i-lucide-rocket',
  to: 'https://github.com/nuxt/ui/releases'
}])
</script>

<template>
  <NPage>
    <NPageHeader :title="page.title" :description="page.description" />

    <NPageBody>
      <ContentRenderer :value="page" />

      <NSeparator />

      <NContentSurround :surround="surround" />
    </NPageBody>

    <template #right>
      <NContentToc :links="page.body.toc.links">
        <template #bottom>
          <NSeparator type="dashed" />

          <NPageLinks title="Community" :links="links" />
        </template>
      </NContentToc>
    </template>
  </NPage>
</template>
```

## API

### Props

```ts
/**
 * Props for the PageLinks component
 */
interface PageLinksProps {
  /**
   * The element or component this component should render as.
   * @default "\"nav\""
   */
  as?: any;
  title?: string | undefined;
  links?: T[] | undefined;
  ui?: { root?: SlotClass; title?: SlotClass; list?: SlotClass; item?: SlotClass; link?: SlotClass; linkLeadingIcon?: SlotClass; linkLabel?: SlotClass; linkLabelExternalIcon?: SlotClass; } | undefined;
}
```

### Slots

```ts
/**
 * Slots for the PageLinks component
 */
interface PageLinksSlots {
  title(): any;
  link(): any;
  link-leading(): any;
  link-label(): any;
  link-trailing(): any;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    pageLinks: {
      slots: {
        root: 'flex flex-col gap-3',
        title: 'text-sm font-semibold flex items-center gap-1.5',
        list: 'flex flex-col gap-2',
        item: 'relative',
        link: 'group text-sm flex items-center gap-1.5 rounded-sm outline-primary/25 focus-visible:outline-3',
        linkLeadingIcon: 'size-5 shrink-0',
        linkLabel: 'truncate',
        linkLabelExternalIcon: 'size-3 absolute top-0 text-dimmed'
      },
      variants: {
        active: {
          true: {
            link: 'text-primary font-medium'
          },
          false: {
            link: [
              'text-muted hover:text-default',
              'transition-colors'
            ]
          }
        }
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/PageLinks.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/page-links.ts).


# PageList

## Uso

O componente PageList oferece uma maneira flexível de exibir conteúdo em um layout de lista vertical. Ele é perfeito para criar listas empilhadas de componentes [PageCard](https://ui.nitro.news/docs/components/page-card) ou quaisquer outros elementos, com divisórias opcionais entre os itens.

::component-example
---
collapse: true
props:
  class: w-full
name: page-list-example
---
::

### Divisória

Use a prop `divide` para adicionar uma divisória entre cada elemento filho.

::component-example
---
collapse: true
props:
  class: w-full
name: page-list-divide-example
---
::

## API

### Props

```ts
/**
 * Props for the PageList component
 */
interface PageListProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  /**
   * @default "false"
   */
  divide?: boolean | undefined;
  ui?: { base?: any; } | undefined;
}
```

### Slots

```ts
/**
 * Slots for the PageList component
 */
interface PageListSlots {
  default(): any;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    pageList: {
      base: 'relative flex flex-col',
      variants: {
        divide: {
          true: '*:not-last:after:absolute *:not-last:after:inset-x-1 *:not-last:after:bottom-0 *:not-last:after:bg-border *:not-last:after:h-px'
        }
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/PageList.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/page-list.ts).


# PageLogos

## Uso

O componente PageLogos oferece uma maneira flexível de exibir uma lista de logos ou imagens nas suas páginas.

```vue
<template>
  <UPageLogos :items="[
  'i-simple-icons-github',
  'i-simple-icons-discord',
  'i-simple-icons-x',
  'i-simple-icons-instagram',
  'i-simple-icons-linkedin',
  'i-simple-icons-facebook'
]" />
</template>
```

### Título

Use a prop `title` para definir o título acima dos logos.

```vue
<template>
  <UPageLogos title="Trusted by the best front-end teams" :items="[
  'i-simple-icons-github',
  'i-simple-icons-discord',
  'i-simple-icons-x',
  'i-simple-icons-instagram',
  'i-simple-icons-linkedin',
  'i-simple-icons-facebook'
]" />
</template>
```

### Itens

Você pode exibir os logos de duas maneiras:

1. Usando a prop `items` para fornecer uma lista de logos. Cada item pode ser:

- An icon name (e.g., `i-simple-icons-github`)
- An object containing `src` and `alt` properties for images, which will be utilized in a `UAvatar` component

2. Usando o slot padrão para ter controle total sobre o conteúdo

### Marquee

Use a prop `marquee` para habilitar um efeito de marquee para os logos.

```vue
<template>
  <UPageLogos title="Trusted by the best front-end teams" marquee :items="[
  'i-simple-icons-github',
  'i-simple-icons-discord',
  'i-simple-icons-x',
  'i-simple-icons-instagram',
  'i-simple-icons-linkedin',
  'i-simple-icons-facebook'
]" />
</template>
```

> \[!NOTE]
> See: /docs/components/marquee
>
> Ao usar o modo `marquee`, você pode personalizar o comportamento dele passando props. Para mais informações, confira o componente `Marquee`.

## API

### Props

```ts
/**
 * Props for the PageLogos component
 */
interface PageLogosProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  title?: string | undefined;
  items?: PageLogosItem[] | undefined;
  /**
   * @default "false"
   */
  marquee?: boolean | MarqueeProps | undefined;
  ui?: { root?: SlotClass; title?: SlotClass; logos?: SlotClass; logo?: SlotClass; } | undefined;
}
```

### Slots

```ts
/**
 * Slots for the PageLogos component
 */
interface PageLogosSlots {
  default(): any;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    pageLogos: {
      slots: {
        root: 'relative overflow-hidden',
        title: 'text-lg text-center font-semibold text-highlighted',
        logos: 'mt-10',
        logo: 'size-10 shrink-0'
      },
      variants: {
        marquee: {
          false: {
            logos: 'flex items-center shrink-0 justify-around gap-(--gap) [--gap:--spacing(16)]'
          }
        }
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/PageLogos.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/page-logos.ts).


# PageSection

## Uso

O componente PageSection envolve o seu conteúdo em um [Container](https://ui.nitro.news/docs/components/container) mantendo a flexibilidade de largura total, facilitando a adição de cores de fundo, imagens ou padrões. Ele oferece uma maneira flexível de exibir conteúdo com uma ilustração no slot padrão.

```vue
<template>
  <n-page-section :features=[{"title":"Icons","description":"Nitro UI integrates with Nuxt Icon to access over 200,000+ icons from Iconify.","icon":"i-lucide-smile","to":"/docs/getting-started/integrations/icons"},{"title":"Fonts","description":"Nitro UI integrates with Nuxt Fonts to provide plug-and-play font optimization.","icon":"i-lucide-a-large-small","to":"/docs/getting-started/integrations/fonts"},{"title":"Color Mode","description":"Nitro UI integrates with Nuxt Color Mode to switch between light and dark.","icon":"i-lucide-sun-moon","to":"/docs/getting-started/integrations/color-mode"}] description=O Nitro UI oferece um conjunto completo de componentes e utilitários para ajudar você a construir aplicações web bonitas e acessíveis com Vue e Nuxt. headline=Features title=Belos componentes de UI para Vue />
</template>
```

Use-o após um componente [PageHero](https://ui.nitro.news/docs/components/page-hero):

```vue {4}
<template>
  <NPageHero />

  <NPageSection />
</template>
```

### Título

Use a prop `title` para definir o título da seção.

```vue
<template>
  <UPageSection title="Beautiful Vue UI components" />
</template>
```

### Descrição

Use a prop `description` para definir a descrição da seção.

```vue
<template>
  <UPageSection title="Beautiful Vue UI components" description="Nitro UI provides a comprehensive suite of components and utilities to help you build beautiful and accessible web applications with Vue and Nuxt." />
</template>
```

### Título

Use a prop `headline` para definir a manchete da seção.

```vue
<template>
  <UPageSection title="Beautiful Vue UI components" description="Nitro UI provides a comprehensive suite of components and utilities to help you build beautiful and accessible web applications with Vue and Nuxt." headline="Features" />
</template>
```

### Ícone

Use a prop `icon` para definir o ícone da seção.

```vue
<template>
  <UPageSection title="Beautiful Vue UI components" description="Nitro UI provides a comprehensive suite of components and utilities to help you build beautiful and accessible web applications with Vue and Nuxt." icon="i-lucide-rocket" />
</template>
```

### Recursos

Use a prop `features` para exibir uma lista de [PageFeature](https://ui.nitro.news/docs/components/page-feature) abaixo da descrição como um array de objetos com as seguintes propriedades:

- `title?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `description?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `icon?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `orientation?: 'horizontal' | 'vertical'`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Você pode passar qualquer propriedade do componente [Link](https://ui.nitro.news/docs/components/link#props), como `to`, `target`, etc.

```vue
<script setup lang="ts">
import type { PageFeatureProps } from '@nitro/ui'

const features = ref<PageFeatureProps[]>([
  {
    title: "Icons",
    description: "Nitro UI integrates with Nuxt Icon to access over 200,000+ icons from Iconify.",
    icon: "i-lucide-smile",
    to: "/docs/getting-started/integrations/icons"
  },
  {
    title: "Fonts",
    description: "Nitro UI integrates with Nuxt Fonts to provide plug-and-play font optimization.",
    icon: "i-lucide-a-large-small",
    to: "/docs/getting-started/integrations/fonts"
  },
  {
    title: "Color Mode",
    description: "Nitro UI integrates with Nuxt Color Mode to switch between light and dark.",
    icon: "i-lucide-sun-moon",
    to: "/docs/getting-started/integrations/color-mode"
  }
])
</script>

<template>
  <UPageSection title="Beautiful Vue UI components" description="Nitro UI provides a comprehensive suite of components and utilities to help you build beautiful and accessible web applications with Vue and Nuxt." :features="features" />
</template>
```

### Links

Use a prop `links` para exibir uma lista de [Button](https://ui.nitro.news/docs/components/button) abaixo da descrição.

```vue
<script setup lang="ts">
import type { ButtonProps } from '@nitro/ui'

const links = ref<ButtonProps[]>([
  {
    label: "Get started",
    to: "/docs/getting-started",
    icon: "i-lucide-square-play",
    color: "neutral"
  },
  {
    label: "Explore components",
    to: "/docs/components/app",
    color: "neutral",
    variant: "subtle",
    trailingIcon: "i-lucide-arrow-right"
  }
])
</script>

<template>
  <UPageSection title="Beautiful Vue UI components" description="Nitro UI provides a comprehensive suite of components and utilities to help you build beautiful and accessible web applications with Vue and Nuxt." :links="links" />
</template>
```

### Orientação

Use a prop `orientation` para alterar a orientação com o slot padrão. O padrão é `vertical`.

```vue
<script setup lang="ts">
import type { PageFeatureProps, ButtonProps } from '@nitro/ui'

const features = ref<PageFeatureProps[]>([
  {
    title: "Icons",
    description: "Nitro UI integrates with Nuxt Icon to access over 200,000+ icons from Iconify.",
    icon: "i-lucide-smile",
    to: "/docs/getting-started/integrations/icons"
  },
  {
    title: "Fonts",
    description: "Nitro UI integrates with Nuxt Fonts to provide plug-and-play font optimization.",
    icon: "i-lucide-a-large-small",
    to: "/docs/getting-started/integrations/fonts"
  },
  {
    title: "Color Mode",
    description: "Nitro UI integrates with Nuxt Color Mode to switch between light and dark.",
    icon: "i-lucide-sun-moon",
    to: "/docs/getting-started/integrations/color-mode"
  }
])
const links = ref<ButtonProps[]>([
  {
    label: "Explore components",
    to: "/docs/components/app",
    color: "neutral",
    variant: "subtle",
    trailingIcon: "i-lucide-arrow-right"
  }
])
</script>

<template>
  <UPageSection title="Beautiful Vue UI components" description="Nitro UI provides a comprehensive suite of components and utilities to help you build beautiful and accessible web applications with Vue and Nuxt." icon="i-lucide-rocket" orientation="horizontal" :features="features" :links="links">
    <img src="https://picsum.photos/704/1294" width="352" height="647" alt="Illustration" class="w-full rounded-lg" loading="lazy" />
  </UPageSection>
</template>
```

### Invertido

Use a prop `reverse` para inverter a orientação do slot padrão.

```vue
<script setup lang="ts">
import type { PageFeatureProps, ButtonProps } from '@nitro/ui'

const features = ref<PageFeatureProps[]>([
  {
    title: "Icons",
    description: "Nitro UI integrates with Nuxt Icon to access over 200,000+ icons from Iconify.",
    icon: "i-lucide-smile",
    to: "/docs/getting-started/integrations/icons"
  },
  {
    title: "Fonts",
    description: "Nitro UI integrates with Nuxt Fonts to provide plug-and-play font optimization.",
    icon: "i-lucide-a-large-small",
    to: "/docs/getting-started/integrations/fonts"
  },
  {
    title: "Color Mode",
    description: "Nitro UI integrates with Nuxt Color Mode to switch between light and dark.",
    icon: "i-lucide-sun-moon",
    to: "/docs/getting-started/integrations/color-mode"
  }
])
const links = ref<ButtonProps[]>([
  {
    label: "Explore components",
    to: "/docs/components/app",
    color: "neutral",
    variant: "subtle",
    trailingIcon: "i-lucide-arrow-right"
  }
])
</script>

<template>
  <UPageSection title="Beautiful Vue UI components" description="Nitro UI provides a comprehensive suite of components and utilities to help you build beautiful and accessible web applications with Vue and Nuxt." icon="i-lucide-rocket" orientation="horizontal" reverse :features="features" :links="links">
    <img src="https://picsum.photos/704/1294" width="352" height="647" alt="Illustration" class="w-full rounded-lg" loading="lazy" />
  </UPageSection>
</template>
```

## API

### Props

```ts
/**
 * Props for the PageSection component
 */
interface PageSectionProps {
  /**
   * The element or component this component should render as.
   * @default "\"section\""
   */
  as?: any;
  /**
   * The headline displayed above the title.
   */
  headline?: string | undefined;
  /**
   * The icon displayed above the title.
   */
  icon?: any;
  title?: string | undefined;
  description?: string | undefined;
  /**
   * Display a list of Button under the description.
   * `{ size: 'lg' }`{lang="ts-type"}
   */
  links?: ButtonProps[] | undefined;
  /**
   * Display a list of PageFeature under the description.
   */
  features?: PageFeatureProps[] | undefined;
  /**
   * The orientation of the section.
   * @default "\"vertical\""
   */
  orientation?: "vertical" | "horizontal" | undefined;
  /**
   * Reverse the order of the default slot.
   */
  reverse?: boolean | undefined;
  ui?: { root?: SlotClass; container?: SlotClass; wrapper?: SlotClass; header?: SlotClass; leading?: SlotClass; leadingIcon?: SlotClass; headline?: SlotClass; title?: SlotClass; description?: SlotClass; body?: SlotClass; features?: SlotClass; footer?: SlotClass; links?: SlotClass; } | undefined;
}
```

### Slots

```ts
/**
 * Slots for the PageSection component
 */
interface PageSectionSlots {
  top(): any;
  header(): any;
  leading(): any;
  headline(): any;
  title(): any;
  description(): any;
  body(): any;
  features(): any;
  footer(): any;
  links(): any;
  default(): any;
  bottom(): any;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    pageSection: {
      slots: {
        root: 'relative isolate',
        container: 'flex flex-col lg:grid py-16 sm:py-24 lg:py-32 gap-8 sm:gap-16',
        wrapper: '',
        header: '',
        leading: 'flex items-center mb-6',
        leadingIcon: 'size-10 shrink-0 text-primary',
        headline: 'mb-3',
        title: 'text-3xl sm:text-4xl lg:text-5xl text-pretty tracking-tight font-bold text-highlighted',
        description: 'text-base sm:text-lg text-muted',
        body: 'mt-8',
        features: 'grid',
        footer: 'mt-8',
        links: 'flex flex-wrap gap-x-6 gap-y-3'
      },
      variants: {
        orientation: {
          horizontal: {
            container: 'lg:grid-cols-2 lg:items-center',
            description: 'text-pretty',
            features: 'gap-4'
          },
          vertical: {
            container: '',
            headline: 'justify-center',
            leading: 'justify-center',
            title: 'text-center',
            description: 'text-center text-balance',
            links: 'justify-center',
            features: 'sm:grid-cols-2 lg:grid-cols-3 gap-8'
          }
        },
        reverse: {
          true: {
            wrapper: 'order-last'
          }
        },
        headline: {
          true: {
            headline: 'font-semibold text-primary flex items-center gap-1.5'
          }
        },
        title: {
          true: {
            description: 'mt-6'
          }
        },
        description: {
          true: ''
        },
        body: {
          true: ''
        }
      },
      compoundVariants: [
        {
          orientation: 'vertical',
          title: true,
          class: {
            body: 'mt-16'
          }
        },
        {
          orientation: 'vertical',
          description: true,
          class: {
            body: 'mt-16'
          }
        },
        {
          orientation: 'vertical',
          body: true,
          class: {
            footer: 'mt-16'
          }
        }
      ]
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/PageSection.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/page-section.ts).


# Pagination

## Uso

Use a prop `default-page` ou a diretiva `v-model:page` para controlar a página atual.

```vue
<script setup lang="ts">
const page = ref(5)
</script>

<template>
  <UPagination v-model:page="page" :total="100" />
</template>
```

> \[!NOTE]
>
> O componente Pagination usa alguns [`Button`](https://ui.nitro.news/docs/components/button) para exibir as páginas; use as props [`color`](https://ui.nitro.news/#color), [`variant`](https://ui.nitro.news/#variant) e [`size`](https://ui.nitro.news/#size) para estilizá-los.

### Total

Use a prop `total` para definir o número total de itens na lista.

```vue
<script setup lang="ts">
const page = ref(5)
</script>

<template>
  <UPagination v-model:page="page" :total="100" />
</template>
```

### Itens por página

Use a prop `items-per-page` para definir o número de itens por página. O padrão é `10`.

```vue
<script setup lang="ts">
const page = ref(5)
</script>

<template>
  <UPagination v-model:page="page" :items-per-page="20" :total="100" />
</template>
```

### Contagem de irmãos

Use a prop `sibling-count` para definir o número de irmãos a exibir. O padrão é `2`.

```vue
<script setup lang="ts">
const page = ref(5)
</script>

<template>
  <UPagination v-model:page="page" :sibling-count="1" :total="100" />
</template>
```

### Exibir extremidades

Use a prop `show-edges` para sempre exibir as reticências e as primeiras e últimas páginas. O padrão é `false`.

```vue
<script setup lang="ts">
const page = ref(5)
</script>

<template>
  <UPagination v-model:page="page" show-edges :sibling-count="1" :total="100" />
</template>
```

### Exibir controles

Use a prop `show-controls` para exibir os botões de primeira, anterior, próxima e última. O padrão é `true`.

```vue
<script setup lang="ts">
const page = ref(5)
</script>

<template>
  <UPagination v-model:page="page" :show-controls="false" show-edges :total="100" />
</template>
```

### Cor

Use a prop `color` para definir a cor dos controles inativos. O padrão é `neutral`.

```vue
<script setup lang="ts">
const page = ref(5)
</script>

<template>
  <UPagination v-model:page="page" color="primary" :total="100" />
</template>
```

### Variante

Use a prop `variant` para definir a variante dos controles inativos. O padrão é `outline`.

```vue
<script setup lang="ts">
const page = ref(5)
</script>

<template>
  <UPagination v-model:page="page" color="neutral" variant="subtle" :total="100" />
</template>
```

### Cor ativa

Use a prop `active-color` para definir a cor do controle ativo. O padrão é `primary`.

```vue
<script setup lang="ts">
const page = ref(5)
</script>

<template>
  <UPagination v-model:page="page" active-color="neutral" :total="100" />
</template>
```

### Variante ativa

Use a prop `active-variant` para definir a variante do controle ativo. O padrão é `solid`.

```vue
<script setup lang="ts">
const page = ref(5)
</script>

<template>
  <UPagination v-model:page="page" active-color="primary" active-variant="subtle" :total="100" />
</template>
```

### Tamanho

Use a prop `size` para definir o tamanho dos controles. O padrão é `md`.

```vue
<script setup lang="ts">
const page = ref(5)
</script>

<template>
  <UPagination v-model:page="page" size="xl" :total="100" />
</template>
```

### Desabilitado

Use a prop `disabled` para desabilitar os controles de paginação.

```vue
<script setup lang="ts">
const page = ref(5)
</script>

<template>
  <UPagination v-model:page="page" :total="100" disabled />
</template>
```

## Exemplos

### Com links

Use a prop `to` para transformar os botões em links. Passe uma função que recebe o número da página e retorna um destino de rota.

:component-example{name="pagination-links-example"}

> \[!NOTE]
>
> Neste exemplo, adicionamos o hash `#with-links` para evitar ir ao topo da página.

## API

### Props

```ts
/**
 * Props for the Pagination component
 */
interface PaginationProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  /**
   * The icon to use for the first page control.
   */
  firstIcon?: any;
  /**
   * The icon to use for the previous page control.
   */
  prevIcon?: any;
  /**
   * The icon to use for the next page control.
   */
  nextIcon?: any;
  /**
   * The icon to use for the last page control.
   */
  lastIcon?: any;
  /**
   * The icon to use for the ellipsis control.
   */
  ellipsisIcon?: any;
  /**
   * The color of the pagination controls.
   * @default "\"neutral\""
   */
  color?: "error" | "neutral" | "primary" | "secondary" | "accent" | "success" | "info" | "warning" | undefined;
  /**
   * The variant of the pagination controls.
   * @default "\"outline\""
   */
  variant?: "outline" | "solid" | "soft" | "subtle" | "ghost" | "link" | undefined;
  /**
   * The color of the active pagination control.
   * @default "\"primary\""
   */
  activeColor?: "error" | "neutral" | "primary" | "secondary" | "accent" | "success" | "info" | "warning" | undefined;
  /**
   * The variant of the active pagination control.
   * @default "\"solid\""
   */
  activeVariant?: "outline" | "solid" | "soft" | "subtle" | "ghost" | "link" | undefined;
  /**
   * Whether to show the first, previous, next, and last controls.
   * @default "true"
   */
  showControls?: boolean | undefined;
  size?: "xs" | "sm" | "md" | "lg" | "xl" | undefined;
  /**
   * A function to render page controls as links.
   */
  to?: ((page: number) => string | it | et | undefined) | undefined;
  ui?: { root?: SlotClass; list?: SlotClass; ellipsis?: SlotClass; label?: SlotClass; first?: SlotClass; prev?: SlotClass; item?: SlotClass; next?: SlotClass; last?: SlotClass; } | undefined;
  /**
   * The value of the page that should be active when initially rendered.
   * 
   * Use when you do not need to control the value state.
   */
  defaultPage?: number | undefined;
  /**
   * When `true`, prevents the user from interacting with item
   */
  disabled?: boolean | undefined;
  /**
   * Number of items per page
   * @default "10"
   */
  itemsPerPage?: number | undefined;
  /**
   * The controlled value of the current page. Can be binded as `v-model:page`.
   */
  page?: number | undefined;
  /**
   * When `true`, always show first page, last page, and ellipsis
   * @default "false"
   */
  showEdges?: boolean | undefined;
  /**
   * Number of sibling should be shown around the current page
   * @default "2"
   */
  siblingCount?: number | undefined;
  /**
   * Number of items in your list
   * @default "0"
   */
  total?: number | undefined;
}
```

### Slots

```ts
/**
 * Slots for the Pagination component
 */
interface PaginationSlots {
  first(): any;
  prev(): any;
  next(): any;
  last(): any;
  ellipsis(): any;
  item(): any;
}
```

### Emits

```ts
/**
 * Emitted events for the Pagination component
 */
interface PaginationEmits {
  update:page: (payload: [value: number]) => void;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    pagination: {
      slots: {
        root: '',
        list: 'flex items-center gap-1',
        ellipsis: 'pointer-events-none',
        label: 'min-w-5 text-center',
        first: '',
        prev: '',
        item: '',
        next: '',
        last: ''
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/Pagination.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/pagination.ts).


# PinInput

## Uso

Use a diretiva `v-model` para controlar o valor do PinInput.

```vue
<script setup lang="ts">
const value = ref([])
</script>

<template>
  <UPinInput v-model="value" />
</template>
```

Use a prop `default-value` para definir o valor inicial quando você não precisa controlar o estado.

```vue
<template>
  <UPinInput :default-value="[
  '1',
  '2',
  '3'
]" />
</template>
```

### Tipo

Use a prop `type` para alterar o tipo do input. O padrão é `text`.

```vue
<template>
  <UPinInput type="number" />
</template>
```

> \[!NOTE]
>
> Quando `type` é definido como `number`, ele só aceita caracteres numéricos.

### Máscara

Use a prop `mask` para tratar o input como uma senha.

```vue
<template>
  <UPinInput mask :default-value="[
  '1',
  '2',
  '3',
  '4',
  '5'
]" />
</template>
```

### OTP

Use a prop `otp` para habilitar a funcionalidade de senha de uso único (One-Time Password). Quando habilitada, os dispositivos móveis podem detectar e preencher automaticamente os códigos OTP de mensagens SMS ou do conteúdo da área de transferência, com suporte a autocomplete.

```vue
<template>
  <UPinInput otp />
</template>
```

### Placeholder

Use a prop `placeholder` para definir um texto de placeholder.

```vue
<template>
  <UPinInput placeholder="○" />
</template>
```

### Comprimento

Use a prop `length` para alterar a quantidade de inputs.

```vue
<template>
  <UPinInput :length="6" placeholder="○" />
</template>
```

### Separador `4.9+`

Use a prop `separator` para inserir um separador entre grupos de inputs. Passe um número para inserir um após cada N-ésimo input.

```vue
<template>
  <UPinInput :length="6" :separator="3" placeholder="○" />
</template>
```

Você também pode passar um array de posições para inserir separadores após inputs específicos.

```vue
<template>
  <UPinInput :length="7" :separator="[
  3,
  4
]" placeholder="○" />
</template>
```

### Cor

Use a prop `color` para alterar a cor do ring quando o PinInput está em foco.

```vue
<template>
  <UPinInput color="neutral" highlight placeholder="○" />
</template>
```

> \[!NOTE]
>
> A prop `highlight` é usada aqui para mostrar o estado de foco. Ela é usada internamente quando ocorre um erro de validação.

### Variante

Use a prop `variant` para alterar a variante do PinInput.

```vue
<template>
  <UPinInput color="neutral" variant="subtle" :highlight="false" placeholder="○" />
</template>
```

### Tamanho

Use a prop `size` para alterar o tamanho do PinInput.

```vue
<template>
  <UPinInput size="xl" placeholder="○" />
</template>
```

### Desabilitado

Use a prop `disabled` para desabilitar o PinInput.

```vue
<template>
  <UPinInput disabled placeholder="○" />
</template>
```

## Exemplos

### Com slot de separador `4.9+`

Use o slot `separator` para personalizar a aparência do separador.

:component-example{name="pin-input-separator-slot-example"}

## API

### Props

```ts
/**
 * Props for the PinInput component
 */
interface PinInputProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  color?: "primary" | "secondary" | "accent" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
  variant?: "outline" | "soft" | "subtle" | "ghost" | "none" | undefined;
  size?: "xs" | "sm" | "md" | "lg" | "xl" | undefined;
  /**
   * The number of input fields.
   * @default "5"
   */
  length?: string | number | undefined;
  autofocus?: boolean | undefined;
  /**
   * @default "0"
   */
  autofocusDelay?: number | undefined;
  highlight?: boolean | undefined;
  /**
   * Keep the mobile text size on all breakpoints.
   */
  fixed?: boolean | undefined;
  /**
   * Group inputs by inserting a separator between them.
   * Pass a number to insert one after every Nth input, or an array of positions to insert after specific inputs.
   */
  separator?: number | number[] | undefined;
  ui?: { root?: SlotClass; base?: SlotClass; separator?: SlotClass; } | undefined;
  /**
   * The default value of the pin inputs when it is initially rendered. Use when you do not need to control its checked state.
   */
  defaultValue?: PinInputValue<T> | undefined;
  /**
   * When `true`, prevents the user from interacting with the pin input
   */
  disabled?: boolean | undefined;
  /**
   * Id of the element
   */
  id?: string | undefined;
  /**
   * When `true`, pin inputs will be treated as password.
   */
  mask?: boolean | undefined;
  /**
   * The controlled checked state of the pin input. Can be binded as `v-model`.
   */
  modelValue?: PinInputValue<T> | null | undefined;
  /**
   * The name of the field. Submitted with its owning form as part of a name/value pair.
   */
  name?: string | undefined;
  /**
   * When `true`, mobile devices will autodetect the OTP from messages or clipboard, and enable the autocomplete field.
   */
  otp?: boolean | undefined;
  /**
   * The placeholder character to use for empty pin-inputs.
   */
  placeholder?: string | undefined;
  /**
   * When `true`, indicates that the user must set the value before the owning form can be submitted.
   */
  required?: boolean | undefined;
  /**
   * Input type for the inputs.
   * @default "\"text\" as never"
   */
  type?: T | undefined;
}
```

### Slots

```ts
/**
 * Slots for the PinInput component
 */
interface PinInputSlots {
  separator(): any;
}
```

### Emits

```ts
/**
 * Emitted events for the PinInput component
 */
interface PinInputEmits {
  update:modelValue: (payload: [value: PinInputValue<T>]) => void;
  complete: (payload: [value: PinInputValue<T>]) => void;
  change: (payload: [event: Event]) => void;
  blur: (payload: [event: Event]) => void;
}
```

### Expose

Ao acessar o componente por meio de um template ref, você pode usar o seguinte:

| Name                                                                                                                            | Type                                                                                                                                                 |
| ------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `inputsRef`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | `Ref<ComponentPublicInstance[]>`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} |

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    pinInput: {
      slots: {
        root: 'relative inline-flex items-center gap-1.5',
        base: [
          'rounded-md border-0 placeholder:text-dimmed text-center focus:outline-none disabled:cursor-not-allowed disabled:opacity-75',
          'transition-colors'
        ],
        separator: 'text-dimmed flex items-center justify-center'
      },
      variants: {
        size: {
          xs: {
            base: 'size-6 text-xs'
          },
          sm: {
            base: 'size-7 text-xs'
          },
          md: {
            base: 'size-8 text-sm'
          },
          lg: {
            base: 'size-9 text-sm'
          },
          xl: {
            base: 'size-10 text-base'
          }
        },
        variant: {
          outline: 'text-highlighted bg-default ring ring-inset ring-accented',
          soft: 'text-highlighted bg-elevated/50 hover:bg-elevated focus:bg-elevated disabled:bg-elevated/50',
          subtle: 'text-highlighted bg-elevated ring ring-inset ring-accented',
          ghost: 'text-highlighted bg-transparent hover:bg-elevated focus:bg-elevated disabled:bg-transparent dark:disabled:bg-transparent',
          none: 'text-highlighted bg-transparent'
        },
        color: {
          primary: '',
          secondary: '',
          accent: '',
          success: '',
          info: '',
          warning: '',
          error: '',
          neutral: ''
        },
        highlight: {
          true: ''
        },
        fixed: {
          false: ''
        }
      },
      compoundVariants: [
        {
          color: 'primary',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-primary'
        },
        {
          color: 'secondary',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-secondary'
        },
        {
          color: 'accent',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-accent'
        },
        {
          color: 'success',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-success'
        },
        {
          color: 'info',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-info'
        },
        {
          color: 'warning',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-warning'
        },
        {
          color: 'error',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-error'
        },
        {
          color: 'primary',
          highlight: true,
          class: 'ring ring-inset ring-primary'
        },
        {
          color: 'secondary',
          highlight: true,
          class: 'ring ring-inset ring-secondary'
        },
        {
          color: 'accent',
          highlight: true,
          class: 'ring ring-inset ring-accent'
        },
        {
          color: 'success',
          highlight: true,
          class: 'ring ring-inset ring-success'
        },
        {
          color: 'info',
          highlight: true,
          class: 'ring ring-inset ring-info'
        },
        {
          color: 'warning',
          highlight: true,
          class: 'ring ring-inset ring-warning'
        },
        {
          color: 'error',
          highlight: true,
          class: 'ring ring-inset ring-error'
        },
        {
          color: 'neutral',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-inverted'
        },
        {
          color: 'neutral',
          highlight: true,
          class: 'ring ring-inset ring-inverted'
        },
        {
          fixed: false,
          size: 'xs',
          class: 'md:text-xs'
        },
        {
          fixed: false,
          size: 'sm',
          class: 'md:text-xs'
        },
        {
          fixed: false,
          size: 'md',
          class: 'md:text-sm'
        },
        {
          fixed: false,
          size: 'lg',
          class: 'md:text-sm'
        }
      ],
      defaultVariants: {
        size: 'md',
        color: 'primary',
        variant: 'outline'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/PinInput.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/pin-input.ts).


# Popover

## Uso

Use a [Button](https://ui.nitro.news/docs/components/button) or any other component in the default slot of the Popover.

Depois, use o slot `#content` para adicionar o conteúdo exibido quando o Popover está aberto.

```vue
<template>
  <UPopover>
    <NButton label="Open" color="neutral" variant="subtle" />
  
    <template #content>
      <Placeholder class="size-48 m-4 inline-flex" />
    </template></UPopover>
</template>
```

### Modo

Use a prop `mode` para alterar o modo do Popover. O padrão é `click`.

> \[!TIP]
>
> No modo `hover`, defina a prop `enable-touch` para permitir que os usuários abram e fechem o Popover tocando no gatilho em dispositivos de toque, ou use o modo `click` para gatilhos feitos para serem tocados.

```vue
<template>
  <UPopover mode="hover" enable-touch>
    <NButton label="Open" color="neutral" variant="subtle" />
  
    <template #content>
      <Placeholder class="size-48 m-4 inline-flex" />
    </template></UPopover>
</template>
```

> \[!NOTE]
>
> Ao usar o modo `hover`, o componente [`HoverCard`](https://reka-ui.com/docs/components/hover-card){rel="&#x22;nofollow&#x22;"} do Reka UI é usado em vez do [`Popover`](https://reka-ui.com/docs/components/popover){rel="&#x22;nofollow&#x22;"}.

### Atraso

Ao usar o modo `hover`, você pode usar as props `open-delay` e `close-delay` para controlar o atraso antes de o Popover ser aberto ou fechado.

```vue
<template>
  <UPopover mode="hover" :open-delay="500" :close-delay="300">
    <NButton label="Open" color="neutral" variant="subtle" />
  
    <template #content>
      <Placeholder class="size-48 m-4 inline-flex" />
    </template></UPopover>
</template>
```

### Conteúdo

Use a prop `content` para controlar como o conteúdo do Popover é renderizado, como seu `align` ou `side`, por exemplo.

```vue
<template>
  <UPopover :content="{
  align: 'center',
  side: 'bottom',
  sideOffset: 8
}">
    <NButton label="Open" color="neutral" variant="subtle" />
  
    <template #content>
      <Placeholder class="size-48 m-4 inline-flex" />
    </template></UPopover>
</template>
```

### Seta

Use a prop `arrow` para exibir uma seta no Popover.

```vue
<template>
  <UPopover arrow>
    <NButton label="Open" color="neutral" variant="subtle" />
  
    <template #content>
      <Placeholder class="size-48 m-4 inline-flex" />
    </template></UPopover>
</template>
```

### Modal

Use a prop `modal` para controlar se o Popover bloqueia a interação com o conteúdo externo. O padrão é `false`.

```vue
<template>
  <UPopover modal>
    <NButton label="Open" color="neutral" variant="subtle" />
  
    <template #content>
      <Placeholder class="size-48 m-4 inline-flex" />
    </template></UPopover>
</template>
```

### Dispensável

Use a prop `dismissible` para controlar se o Popover pode ser dispensado ao clicar fora dele ou pressionar escape. O padrão é `true`.

> \[!NOTE]
>
> Um evento `close:prevent` será emitido quando o usuário tentar fechá-lo.

:component-example{name="popover-dismissible-example"}

## Exemplos

### Controlar o estado de abertura

Você pode controlar o estado de abertura usando a prop `default-open` ou a diretiva `v-model:open`.

:component-example{name="popover-open-example"}

> \[!NOTE]
>
> Neste exemplo, aproveitando o [`defineShortcuts`](https://ui.nitro.news/docs/composables/define-shortcuts), você pode abrir e fechar o Popover pressionando :kbd{value="O"}.

### Com paleta de comandos

Você pode usar um componente [CommandPalette](https://ui.nitro.news/docs/components/command-palette) dentro do conteúdo do Popover.

::component-example{collapse name="popover-command-palette-example"}
::

### Com cursor que acompanha

Você pode fazer o Popover acompanhar o cursor ao passar o mouse sobre um elemento usando a prop [`reference`](https://reka-ui.com/docs/components/tooltip#trigger){rel="&#x22;nofollow&#x22;"}:

:component-example{name="popover-cursor-example"}

### Com slot de âncora

Você pode usar o slot `#anchor` para posicionar o Popover em relação a um elemento personalizado.

> \[!WARNING]
>
> Este slot só funciona quando o `mode` é `click`.

::component-example{collapse name="popover-anchor-slot-example"}
::

## API

### Props

```ts
/**
 * Props for the Popover component
 */
interface PopoverProps {
  /**
   * The display mode of the popover.
   * @default "\"click\" as never"
   */
  mode?: M | undefined;
  /**
   * The content of the popover.
   */
  content?: (Omit<PopoverContentProps, "as" | "asChild" | "forceMount"> & Partial<EmitsToProps<PopoverContentImplEmits>>) | undefined;
  /**
   * Display an arrow alongside the popover.
   */
  arrow?: boolean | Omit<PopoverArrowProps, "as" | "asChild"> | undefined;
  /**
   * Render the popover in a portal.
   * @default "true"
   */
  portal?: string | boolean | HTMLElement | undefined;
  /**
   * The reference (or anchor) element that is being referred to for positioning.
   * 
   * If not provided will use the current component as anchor.
   */
  reference?: ReferenceElement | undefined;
  /**
   * When `false`, the popover will not close when clicking outside or pressing escape.
   * @default "true"
   */
  dismissible?: boolean | undefined;
  ui?: { content?: SlotClass; arrow?: SlotClass; } | undefined;
  /**
   * The open state of the popover when it is initially rendered. Use when you do not need to control its open state.
   */
  defaultOpen?: boolean | undefined;
  /**
   * The controlled open state of the popover.
   */
  open?: boolean | undefined;
  /**
   * The modality of the popover. When set to true, interaction with outside elements will be disabled and only popover content will be visible to screen readers.
   */
  modal?: boolean | undefined;
  /**
   * The duration from when the mouse enters the trigger until the hover card opens.
   * @default "0"
   */
  openDelay?: number | undefined;
  /**
   * The duration from when the mouse leaves the trigger or content until the hover card closes.
   * @default "0"
   */
  closeDelay?: number | undefined;
}
```

### Slots

```ts
/**
 * Slots for the Popover component
 */
interface PopoverSlots {
  default(): any;
  content(): any;
  anchor(): any;
}
```

> \[!NOTE]
>
> A função `close` só está disponível quando o `mode` é definido como `click`, porque o Reka UI a expõe para o [`Popover`](https://reka-ui.com/docs/components/popover#close-using-slot-props){rel="&#x22;nofollow&#x22;"}, mas não para o [`HoverCard`](https://reka-ui.com/docs/components/hover-card){rel="&#x22;nofollow&#x22;"}.

### Emits

```ts
/**
 * Emitted events for the Popover component
 */
interface PopoverEmits {
  close:prevent: (payload: []) => void;
  update:open: (payload: [value: boolean]) => void;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    popover: {
      slots: {
        content: 'bg-default shadow-lg rounded-md ring ring-default data-[state=open]:animate-[scale-in_100ms_ease-out] data-[state=closed]:animate-[scale-out_100ms_ease-in] origin-(--reka-popover-content-transform-origin) focus:outline-none pointer-events-auto',
        arrow: 'fill-default'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/Popover.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/popover.ts).


# PricingPlan

## Uso

O componente PricingPlan oferece uma maneira flexível de exibir um plano de preços com conteúdo personalizável, incluindo título, descrição, preço, recursos, etc.

```vue
<template>
  <n-pricing-plan :button={"label":"Buy now"} :features=["One developer","Unlimited projects","Access to GitHub repository","Unlimited patch & minor updates","Lifetime access"] badge=Most popular billing-cycle=/month description=Para bootstrappers e indie hackers. discount=$199 price=$249 title=Solo />
</template>
```

> \[!TIP]
> See: /docs/components/pricing-plans
>
> Use o componente `PricingPlans` para exibir vários planos de preços em um layout de grade responsivo.

### Título

Use a prop `title` para definir o título do PricingPlan.

```vue
<template>
  <UPricingPlan title="Solo" class="w-96" />
</template>
```

### Descrição

Use a prop `description` para definir a descrição do PricingPlan.

```vue
<template>
  <UPricingPlan title="Solo" description="For bootstrappers and indie hackers." />
</template>
```

### Badge

Use a prop `badge` para exibir um [Badge](https://ui.nitro.news/docs/components/badge) ao lado do título do PricingPlan.

```vue
<template>
  <UPricingPlan title="Solo" description="For bootstrappers and indie hackers." badge="Most popular" />
</template>
```

Você pode passar qualquer propriedade do componente [Badge](https://ui.nitro.news/docs/components/badge#props) para personalizá-lo.

```vue
<template>
  <UPricingPlan title="Solo" description="For bootstrappers and indie hackers." :badge="{
  label: 'Most popular',
  color: 'neutral',
  variant: 'solid'
}" />
</template>
```

### Preço

Use a prop `price` para definir o preço do PricingPlan.

```vue
<template>
  <UPricingPlan title="Solo" description="For bootstrappers and indie hackers." price="$249" />
</template>
```

### Desconto

Use a prop `discount` para definir um preço com desconto que será exibido ao lado do preço original (que aparecerá riscado).

```vue
<template>
  <UPricingPlan title="Solo" description="For bootstrappers and indie hackers." price="$249" discount="$199" />
</template>
```

### Cobrança

Use as props `billing-cycle` e/ou `billing-period` para exibir as informações de cobrança do PricingPlan.

```vue
<template>
  <UPricingPlan title="Solo" description="For bootstrappers and indie hackers." price="$9" billing-cycle="/month" billing-period="billed annually" />
</template>
```

### Recursos

Use a prop `features` como um array de strings para exibir uma lista de recursos no PricingPlan:

```vue
<template>
  <UPricingPlan title="Solo" description="For bootstrappers and indie hackers." price="$249" :features="[
  'One developer',
  'Unlimited projects',
  'Access to GitHub repository',
  'Unlimited patch & minor updates',
  'Lifetime access'
]" />
</template>
```

**Nuxt:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/nuxt#theme
>
> Você pode personalizar esse ícone globalmente no seu `app.config.ts` na chave `ui.icons.success`.

**Vue:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/vue#theme
>
> Você pode personalizar esse ícone globalmente no seu `vite.config.ts` na chave `ui.icons.success`.

Você também pode passar um array de objetos com as seguintes propriedades:

- `title: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `icon?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

```vue
<script setup lang="ts">
import type { PricingPlanFeature } from '@nitro/ui'

const features = ref<PricingPlanFeature[]>([
  {
    title: "One developer",
    icon: "i-lucide-user"
  },
  {
    title: "Unlimited projects",
    icon: "i-lucide-infinity"
  },
  {
    title: "Access to GitHub repository",
    icon: "i-lucide-github"
  },
  {
    title: "Unlimited patch & minor updates",
    icon: "i-lucide-refresh-cw"
  },
  {
    title: "Lifetime access",
    icon: "i-lucide-clock"
  }
])
</script>

<template>
  <UPricingPlan title="Solo" description="For bootstrappers and indie hackers." price="$249" :features="features" />
</template>
```

### Button

Use a prop `button` com qualquer propriedade do componente [Button](https://ui.nitro.news/docs/components/button) para exibir um botão na parte inferior do PricingPlan.

```vue
<template>
  <UPricingPlan title="Solo" description="For bootstrappers and indie hackers." price="$249" :features="[
  'One developer',
  'Unlimited projects',
  'Access to GitHub repository',
  'Unlimited patch & minor updates',
  'Lifetime access'
]" :button="{
  label: 'Buy now'
}" />
</template>
```

> \[!TIP]
>
> Use o campo `onClick` para adicionar um handler de clique que dispara a compra do plano.

### Variante

Use a prop `variant` para alterar a variante do PricingPlan.

```vue
<template>
  <UPricingPlan title="Solo" description="For bootstrappers and indie hackers." price="$249" :features="[
  'One developer',
  'Unlimited projects',
  'Access to GitHub repository',
  'Unlimited patch & minor updates',
  'Lifetime access'
]" :button="{
  label: 'Buy now'
}" variant="subtle" />
</template>
```

### Orientação

Use a prop `orientation` para alterar a orientação do PricingPlan. O padrão é `vertical`.

```vue
<template>
  <UPricingPlan title="Solo" description="For bootstrappers and indie hackers." price="$249" :features="[
  'One developer',
  'Unlimited projects',
  'Access to GitHub repository',
  'Lifetime access'
]" :button="{
  label: 'Buy now'
}" orientation="horizontal" variant="outline" />
</template>
```

### Slogan

Use a prop `tagline` para exibir um texto de slogan acima do preço.

```vue
<template>
  <UPricingPlan title="Solo" description="For bootstrappers and indie hackers." price="$249" :features="[
  'One developer',
  'Unlimited projects',
  'Access to GitHub repository',
  'Lifetime access'
]" :button="{
  label: 'Buy now'
}" orientation="horizontal" tagline="Pay once, own it forever" />
</template>
```

### Termos

Use a prop `terms` para exibir os termos abaixo do preço.

```vue
<template>
  <UPricingPlan title="Solo" description="For bootstrappers and indie hackers." price="$249" :features="[
  'One developer',
  'Unlimited projects',
  'Access to GitHub repository',
  'Lifetime access'
]" :button="{
  label: 'Buy now'
}" orientation="horizontal" tagline="Pay once, own it forever" terms="Invoices and receipts available." />
</template>
```

### Destaque

Use a prop `highlight` para exibir uma borda destacada ao redor do PricingPlan.

```vue
<template>
  <UPricingPlan title="Solo" description="For bootstrappers and indie hackers." price="$249" :features="[
  'One developer',
  'Unlimited projects',
  'Access to GitHub repository',
  'Unlimited patch & minor updates',
  'Lifetime access'
]" :button="{
  label: 'Buy now'
}" highlight />
</template>
```

### Escala

Use a prop `scale` para tornar um PricingPlan maior que os outros.

> \[!NOTE]
> See: /docs/components/pricing-plans#scale
>
> Confira o exemplo `scale` do PricingPlans para ver como funciona, já que é difícil demonstrar isoladamente.

## API

### Props

```ts
/**
 * Props for the PricingPlan component
 */
interface PricingPlanProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  title?: string | undefined;
  description?: string | undefined;
  /**
   * Display a badge next to the title.
   * Can be a string or an object.
   * `{ color: 'primary', variant: 'subtle' }`{lang="ts-type"}
   */
  badge?: string | BadgeProps | undefined;
  /**
   * The unit price period that appears next to the price.
   * Typically used to show the recurring interval.
   */
  billingCycle?: string | undefined;
  /**
   * Additional billing context that appears above the billing cycle.
   * Typically used to show the actual billing frequency.
   */
  billingPeriod?: string | undefined;
  /**
   * The current price of the plan.
   * When used with `discount`, this becomes the original price.
   */
  price?: string | undefined;
  /**
   * The discounted price of the plan.
   * When provided, the `price` prop will be displayed as strikethrough.
   */
  discount?: string | undefined;
  /**
   * Display a list of features under the price.
   * Can be an array of strings or an array of objects.
   */
  features?: string[] | PricingPlanFeature[] | undefined;
  /**
   * Display a buy button at the bottom.
   * `{ size: 'lg', block: true }`{lang="ts-type"}
   * Use the `onClick` field to add a click handler.
   */
  button?: ButtonProps | undefined;
  /**
   * Display a tagline highlighting the pricing value proposition.
   */
  tagline?: string | undefined;
  /**
   * Display terms at the bottom.
   */
  terms?: string | undefined;
  /**
   * The orientation of the pricing plan.
   * @default "\"vertical\""
   */
  orientation?: "vertical" | "horizontal" | undefined;
  variant?: "soft" | "solid" | "outline" | "subtle" | undefined;
  /**
   * Display a ring around the pricing plan to highlight it.
   */
  highlight?: boolean | undefined;
  /**
   * Enlarge the plan to make it more prominent.
   */
  scale?: boolean | undefined;
  ui?: { root?: SlotClass; header?: SlotClass; body?: SlotClass; footer?: SlotClass; titleWrapper?: SlotClass; title?: SlotClass; description?: SlotClass; priceWrapper?: SlotClass; price?: SlotClass; discount?: SlotClass; billing?: SlotClass; billingPeriod?: SlotClass; billingCycle?: SlotClass; features?: SlotClass; feature?: SlotClass; featureIcon?: SlotClass; featureTitle?: SlotClass; badge?: SlotClass; button?: SlotClass; tagline?: SlotClass; terms?: SlotClass; } | undefined;
}
```

### Slots

```ts
/**
 * Slots for the PricingPlan component
 */
interface PricingPlanSlots {
  badge(): any;
  title(): any;
  description(): any;
  price(): any;
  discount(): any;
  billing(): any;
  features(): any;
  button(): any;
  header(): any;
  body(): any;
  footer(): any;
  tagline(): any;
  terms(): any;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    pricingPlan: {
      slots: {
        root: 'relative grid rounded-lg p-6 lg:p-8 xl:p-10 gap-6',
        header: '',
        body: 'flex flex-col min-w-0',
        footer: 'flex flex-col gap-6 items-center',
        titleWrapper: 'flex items-center gap-3',
        title: 'text-highlighted truncate text-2xl sm:text-3xl text-pretty font-semibold',
        description: 'text-muted text-base text-pretty mt-2',
        priceWrapper: 'flex items-center gap-1',
        price: 'text-highlighted text-3xl sm:text-4xl font-semibold',
        discount: 'text-muted line-through text-xl sm:text-2xl',
        billing: 'flex flex-col justify-between min-w-0',
        billingPeriod: 'text-toned truncate text-xs font-medium',
        billingCycle: 'text-muted truncate text-xs font-medium',
        features: 'flex flex-col gap-3 flex-1 mt-6 grow-0',
        feature: 'flex items-center gap-2 min-w-0',
        featureIcon: 'size-5 shrink-0 text-primary',
        featureTitle: 'text-muted text-sm truncate',
        badge: '',
        button: '',
        tagline: 'text-base font-semibold text-default',
        terms: 'text-xs/5 text-muted text-center text-balance'
      },
      variants: {
        orientation: {
          horizontal: {
            root: 'grid-cols-1 lg:grid-cols-3 justify-between divide-y lg:divide-y-0 lg:divide-x divide-default',
            body: 'lg:col-span-2 pb-6 lg:pb-0 lg:pr-6 justify-center',
            footer: 'lg:justify-center lg:items-center lg:p-6 lg:max-w-xs lg:w-full lg:mx-auto',
            features: 'lg:grid lg:grid-cols-2 lg:mt-12'
          },
          vertical: {
            footer: 'justify-end',
            priceWrapper: 'mt-6'
          }
        },
        variant: {
          solid: {
            root: 'bg-inverted',
            title: 'text-inverted',
            description: 'text-dimmed',
            price: 'text-inverted',
            discount: 'text-dimmed',
            billingCycle: 'text-dimmed',
            billingPeriod: 'text-dimmed',
            featureTitle: 'text-dimmed'
          },
          outline: {
            root: 'bg-default ring ring-default'
          },
          soft: {
            root: 'bg-elevated/50'
          },
          subtle: {
            root: 'bg-elevated/50 ring ring-default'
          }
        },
        highlight: {
          true: {
            root: 'ring-2 ring-inset ring-primary'
          }
        },
        scale: {
          true: {
            root: 'lg:scale-[1.1] lg:z-1'
          }
        }
      },
      compoundVariants: [
        {
          orientation: 'horizontal',
          variant: 'soft',
          class: {
            root: 'divide-accented'
          }
        },
        {
          orientation: 'horizontal',
          variant: 'subtle',
          class: {
            root: 'divide-accented'
          }
        }
      ],
      defaultVariants: {
        variant: 'outline'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/PricingPlan.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/pricing-plan.ts).


# PricingPlans

## Uso

O componente PricingPlans oferece um layout flexível para exibir uma lista de componentes [PricingPlan](https://ui.nitro.news/docs/components/pricing-plan) usando o slot padrão ou a prop `plans`.

```vue {2,8}
<template>
  <NPricingPlans>
    <NPricingPlan
      v-for="(plan, index) in plans"
      :key="index"
      v-bind="plan"
    />
  </NPricingPlans>
</template>
```

> \[!TIP]
>
> As colunas da grade são calculadas automaticamente com base no número de planos; isso funciona com a prop `plans`, mas também com o slot padrão.

### Planos

Use a prop `plans` como um array de objetos com as propriedades do componente [PricingPlan](https://ui.nitro.news/docs/components/pricing-plan#props).

```vue
<script setup lang="ts">
import type { PricingPlanProps } from '@nitro/ui'

const plans = ref<PricingPlanProps[]>([
  {
    title: "Solo",
    description: "Tailored for indie hackers.",
    price: "$249",
    features: [
      "One developer",
      "Lifetime access"
    ],
    button: {
      label: "Buy now"
    }
  },
  {
    title: "Startup",
    description: "Best suited for small teams.",
    price: "$499",
    features: [
      "Up to 5 developers",
      "Everything in Solo"
    ],
    button: {
      label: "Buy now"
    }
  },
  {
    title: "Organization",
    description: "Ideal for larger teams and organizations.",
    price: "$999",
    features: [
      "Up to 20 developers",
      "Everything in Startup"
    ],
    button: {
      label: "Buy now"
    }
  }
])
</script>

<template>
  <UPricingPlans :plans="plans" />
</template>
```

### Orientação

Use a prop `orientation` para alterar a orientação do PricingPlans. O padrão é `horizontal`.

```vue
<script setup lang="ts">
import type { PricingPlanProps } from '@nitro/ui'

const plans = ref<PricingPlanProps[]>([
  {
    title: "Solo",
    description: "Tailored for indie hackers.",
    price: "$249",
    features: [
      "One developer",
      "Lifetime access"
    ],
    button: {
      label: "Buy now"
    }
  },
  {
    title: "Startup",
    description: "Best suited for small teams.",
    price: "$499",
    features: [
      "Up to 5 developers",
      "Everything in Solo"
    ],
    button: {
      label: "Buy now"
    }
  },
  {
    title: "Organization",
    description: "Ideal for larger teams and organizations.",
    price: "$999",
    features: [
      "Up to 20 developers",
      "Everything in Startup"
    ],
    button: {
      label: "Buy now"
    }
  }
])
</script>

<template>
  <UPricingPlans orientation="vertical" :plans="plans" />
</template>
```

> \[!TIP]
>
> Ao usar a prop `plans` em vez do slot padrão, a `orientation` dos planos é invertida automaticamente, de `horizontal` para `vertical` e vice-versa.

### Compacto

Use a prop `compact` para reduzir o espaçamento entre os planos quando um deles está escalado, para um melhor equilíbrio visual.

```vue
<script setup lang="ts">
import type { PricingPlanProps } from '@nitro/ui'

const plans = ref<PricingPlanProps[]>([
  {
    title: "Solo",
    description: "Tailored for indie hackers.",
    price: "$249",
    features: [
      "One developer",
      "Lifetime access"
    ],
    button: {
      label: "Buy now"
    }
  },
  {
    title: "Startup",
    description: "Best suited for small teams.",
    price: "$499",
    scale: true,
    features: [
      "Up to 5 developers",
      "Everything in Solo"
    ],
    button: {
      label: "Buy now"
    }
  },
  {
    title: "Organization",
    description: "Ideal for larger teams and organizations.",
    price: "$999",
    features: [
      "Up to 20 developers",
      "Everything in Startup"
    ],
    button: {
      label: "Buy now"
    }
  }
])
</script>

<template>
  <UPricingPlans compact :plans="plans" />
</template>
```

### Escala

Use a prop `scale` para ajustar o espaçamento entre os planos quando um deles está escalado, para um melhor equilíbrio visual.

```vue
<script setup lang="ts">
import type { PricingPlanProps } from '@nitro/ui'

const plans = ref<PricingPlanProps[]>([
  {
    title: "Solo",
    description: "Tailored for indie hackers.",
    price: "$249",
    features: [
      "One developer",
      "Lifetime access"
    ],
    button: {
      label: "Buy now"
    }
  },
  {
    title: "Startup",
    description: "Best suited for small teams.",
    price: "$499",
    scale: true,
    features: [
      "Up to 5 developers",
      "Everything in Solo"
    ],
    button: {
      label: "Buy now"
    }
  },
  {
    title: "Organization",
    description: "Ideal for larger teams and organizations.",
    price: "$999",
    features: [
      "Up to 20 developers",
      "Everything in Startup"
    ],
    button: {
      label: "Buy now"
    }
  }
])
</script>

<template>
  <UPricingPlans scale :plans="plans" />
</template>
```

## Exemplos

> \[!NOTE]
>
> Embora estes exemplos usem o [Nuxt Content](https://content.nuxt.com){rel="&#x22;nofollow&#x22;"}, os componentes podem ser integrados a qualquer sistema de gerenciamento de conteúdo.

### Dentro de uma página

Use o componente PricingPlans em uma página para criar uma página de preços:

```vue [pages/pricing/index.vue] {11}
<script setup lang="ts">
const { data: plans } = await useAsyncData('plans', () => queryCollection('plans').all())
</script>

<template>
  <NPage>
    <NPageHero title="Pricing" />

    <NPageBody>
      <NContainer>
        <NPricingPlans :plans="plans" />
      </NContainer>
    </NPageBody>
  </NPage>
</template>
```

> \[!NOTE]
>
> Neste exemplo, os `plans` são buscados usando `queryCollection` do módulo `@nuxt/content`.

## API

### Props

```ts
/**
 * Props for the PricingPlans component
 */
interface PricingPlansProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  plans?: PricingPlanProps[] | undefined;
  /**
   * The orientation of the pricing plans.
   * @default "\"horizontal\""
   */
  orientation?: "horizontal" | "vertical" | undefined;
  /**
   * When `true`, the plans will be displayed without gap.
   * @default "false"
   */
  compact?: boolean | undefined;
  /**
   * When `true`, the plans will be displayed with a larger gap.
   * Useful when one plan is scaled. Doesn't work with `compact`.
   * @default "false"
   */
  scale?: boolean | undefined;
  ui?: { base?: any; } | undefined;
}
```

### Slots

```ts
/**
 * Slots for the PricingPlans component
 */
interface PricingPlansSlots {
  badge(): any;
  title(): any;
  description(): any;
  price(): any;
  discount(): any;
  billing(): any;
  features(): any;
  button(): any;
  header(): any;
  body(): any;
  footer(): any;
  tagline(): any;
  terms(): any;
  default(): any;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    pricingPlans: {
      base: 'flex flex-col gap-y-8',
      variants: {
        orientation: {
          horizontal: 'lg:grid lg:grid-cols-[repeat(var(--count),minmax(0,1fr))]',
          vertical: ''
        },
        compact: {
          false: 'gap-x-8'
        },
        scale: {
          true: ''
        }
      },
      compoundVariants: [
        {
          compact: false,
          scale: true,
          class: 'lg:gap-x-13'
        }
      ]
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/PricingPlans.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/pricing-plans.ts).


# PricingTable

## Uso

O componente PricingTable oferece uma maneira responsiva e personalizável de exibir planos de preços em formato de tabela, alternando automaticamente entre um layout de tabela horizontal no desktop para facilitar a comparação e um layout de card vertical no mobile para uma melhor legibilidade.

```vue
<template>
  <n-pricing-table :sections=[{"title":"Features","features":[{"title":"Number of developers","tiers":{"solo":"1","team":"5","enterprise":"Unlimited"}},{"title":"Projects","tiers":{"solo":true,"team":true,"enterprise":true}},{"title":"GitHub repository access","tiers":{"solo":true,"team":true,"enterprise":true}},{"title":"Updates","tiers":{"solo":"Patch & minor","team":"All updates","enterprise":"All updates"}},{"title":"Support","tiers":{"solo":"Community","team":"Priority","enterprise":"24/7"}}]},{"title":"Security","features":[{"title":"SSO","tiers":{"solo":false,"team":true,"enterprise":true}},{"title":"Audit logs","tiers":{"solo":false,"team":true,"enterprise":true}},{"title":"Custom security review","tiers":{"solo":false,"team":false,"enterprise":true}}]}] :tiers=[{"id":"solo","title":"Solo","description":"For indie hackers.","price":"$249","billingCycle":"/month","billingPeriod":"billed annually","badge":"Most popular","button":{"label":"Buy now","variant":"subtle"}},{"id":"team","title":"Team","description":"For growing teams.","price":"$499","billingCycle":"/month","billingPeriod":"billed annually","button":{"label":"Buy now"},"highlight":true},{"id":"enterprise","title":"Enterprise","description":"For large organizations.","price":"Custom","button":{"label":"Contact sales","color":"neutral"}}] />
</template>
```

### Níveis

Use a prop `tiers` como um array de objetos para definir os seus planos de preços. Cada objeto de tier suporta as seguintes propriedades:

- `id: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} - Unique identifier for the tier (required)
- `title?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} - Name of the pricing plan
- `description?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} - Short description of the plan
- `price?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} - The current price of the plan (e.g., "$99", "€99", "Free")
- `discount?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} - The discounted price that will display the `price` with strikethrough (e.g., "$79", "€79")
- `billingCycle?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} - The unit price period that appears next to the price (e.g., "/month", "/seat/month")
- `billingPeriod?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} - Additional billing context that appears above the billing cycle (e.g., "billed monthly")
- `badge?: string | BadgeProps`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} - Display a badge next to the title `{ color: 'primary', variant: 'subtle' }`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `button?: ButtonProps`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} - Configure the CTA button `{ size: 'lg', block: true }`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `highlight?: boolean`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} - Whether to visually emphasize this tier as the recommended option

```vue
<script setup lang="ts">
import type { PricingTableTier } from '@nitro/ui'

const tiers = ref<PricingTableTier[]>([
  {
    id: "solo",
    title: "Solo",
    description: "For indie hackers.",
    price: "$249",
    billingCycle: "/month",
    billingPeriod: "billed annually",
    badge: "Most popular",
    button: {
      label: "Buy now",
      variant: "subtle"
    }
  },
  {
    id: "team",
    title: "Team",
    description: "For growing teams.",
    price: "$499",
    billingCycle: "/month",
    billingPeriod: "billed annually",
    button: {
      label: "Buy now"
    },
    highlight: true
  },
  {
    id: "enterprise",
    title: "Enterprise",
    description: "For large organizations.",
    price: "Custom",
    button: {
      label: "Contact sales",
      color: "neutral"
    }
  }
])
</script>

<template>
  <UPricingTable :tiers="tiers" />
</template>
```

### Seções

Use a prop `sections` para organizar os recursos em grupos lógicos. Cada seção representa uma categoria de recursos que você quer comparar entre os diferentes tiers de preço.

- `title: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} - The heading for the feature section
- `features: PricingTableSectionFeature[]`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}- An array of features with their availability in each tier:
  - Each feature requires a `title` and a `tiers` object mapping tier IDs to values
  - Boolean values (`true`/`false`) will display as checkmarks (✓) or minus icons (-)
  - String values will be shown as text (e.g., "Unlimited", "Up to 5 users")
  - Numeric values will be displayed as is (e.g., 10, 100)

```vue
<script setup lang="ts">
import type { PricingTableTier, PricingTableSection } from '@nitro/ui'

const tiers = ref<PricingTableTier[]>([
  {
    id: "solo",
    title: "Solo",
    price: "$249",
    description: "For indie hackers.",
    billingCycle: "/month",
    button: {
      label: "Buy now",
      variant: "subtle"
    }
  },
  {
    id: "team",
    title: "Team",
    price: "$499",
    description: "For growing teams.",
    billingCycle: "/month",
    button: {
      label: "Buy now"
    }
  },
  {
    id: "enterprise",
    title: "Enterprise",
    price: "Custom",
    description: "For large organizations.",
    button: {
      label: "Contact sales",
      color: "neutral"
    }
  }
])
const sections = ref<PricingTableSection[]>([
  {
    title: "Features",
    features: [
      {
        title: "Number of developers",
        tiers: {
          solo: "1",
          team: "5",
          enterprise: "Unlimited"
        }
      },
      {
        title: "Projects",
        tiers: {
          solo: true,
          team: true,
          enterprise: true
        }
      }
    ]
  },
  {
    title: "Security",
    features: [
      {
        title: "SSO",
        tiers: {
          solo: false,
          team: true,
          enterprise: true
        }
      }
    ]
  }
])
</script>

<template>
  <UPricingTable :tiers="tiers" :sections="sections" />
</template>
```

## Exemplos

### Com slots

O componente PricingTable oferece poderosas opções de personalização de slots para ajustar a exibição do seu conteúdo. Você pode personalizar elementos individuais usando slots genéricos ou mirar itens específicos usando os IDs deles.

::component-example{collapse prettier name="pricing-table-slots-example"}
::

O componente suporta vários tipos de slot para máxima flexibilidade de personalização:

| Slot Type         | Pattern                                       | Description              | Example                      |
| ----------------- | --------------------------------------------- | ------------------------ | ---------------------------- |
| **Tier slots**    | `#{tier-id}-{element}`                        | Target specific tiers    | `#team-title`, `#solo-price` |
| **Section slots** | `#section-{id|formatted-title}-title`         | Target specific sections | `#section-features-title`    |
| **Feature slots** | `#feature-{id|formatted-title}-{title|value}` | Target specific features | `#feature-developers-title`  |
| **Generic slots** | `#tier-title`, `#section-title`, etc.         | Apply to all items       | `#feature-value`             |

> \[!NOTE]
>
> Quando nenhum `id` é fornecido, o nome do slot é gerado automaticamente a partir do título (ex.: "Premium Features!" vira `#section-premium-features-title`).

## API

### Props

```ts
/**
 * Props for the PricingTable component
 */
interface PricingTableProps {
  /**
   * The pricing tiers to display in the table.
   * Each tier represents a pricing plan with its own title, description, price, and features.
   */
  tiers: T[];
  /**
   * The sections of features to display in the table.
   * Each section contains a title and a list of features with their availability in each tier.
   */
  sections: PricingTableSection<T>[];
  /**
   * The element or component this component should render as.
   */
  as?: any;
  /**
   * The caption to display above the table.
   */
  caption?: string | undefined;
  ui?: { root?: SlotClass; table?: SlotClass; list?: SlotClass; item?: SlotClass; caption?: SlotClass; thead?: SlotClass; tbody?: SlotClass; tr?: SlotClass; th?: SlotClass; td?: SlotClass; tier?: SlotClass; tierWrapper?: SlotClass; tierTitleWrapper?: SlotClass; tierTitle?: SlotClass; tierDescription?: SlotClass; tierBadge?: SlotClass; tierPriceWrapper?: SlotClass; tierPrice?: SlotClass; tierDiscount?: SlotClass; tierBilling?: SlotClass; tierBillingPeriod?: SlotClass; tierBillingCycle?: SlotClass; tierButton?: SlotClass; tierFeatureIcon?: SlotClass; section?: SlotClass; sectionTitle?: SlotClass; feature?: SlotClass; featureTitle?: SlotClass; featureValue?: SlotClass; } | undefined;
}
```

### Slots

```ts
/**
 * Slots for the PricingTable component
 */
interface PricingTableSlots {
  caption(): any;
  tier(): any;
  tier-title(): any;
  tier-description(): any;
  tier-badge(): any;
  tier-button(): any;
  tier-billing(): any;
  tier-discount(): any;
  tier-price(): any;
  section-title(): any;
  feature-title(): any;
  feature-value(): any;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    pricingTable: {
      slots: {
        root: 'w-full relative',
        table: 'w-full table-fixed border-separate border-spacing-x-0 hidden md:table h-fit',
        list: 'md:hidden flex flex-col gap-6 w-full',
        item: 'p-6 flex flex-col border border-default rounded-lg',
        caption: 'sr-only',
        thead: '',
        tbody: '',
        tr: '',
        th: 'py-4 font-normal text-left rtl:text-right border-b border-default',
        td: 'px-6 py-4 text-center border-b border-default',
        tier: 'p-6 text-left rtl:text-right font-normal align-top h-full',
        tierWrapper: 'flex flex-col md:h-full',
        tierTitleWrapper: 'flex items-center gap-3',
        tierTitle: 'text-lg font-semibold text-highlighted',
        tierDescription: 'text-sm font-normal text-muted mt-1',
        tierBadge: 'truncate',
        tierPriceWrapper: 'flex items-center gap-1 mt-4',
        tierPrice: 'text-highlighted text-3xl sm:text-4xl font-semibold',
        tierDiscount: 'text-muted line-through text-xl sm:text-2xl',
        tierBilling: 'flex flex-col justify-between min-w-0',
        tierBillingPeriod: 'text-toned truncate text-xs font-medium',
        tierBillingCycle: 'text-muted truncate text-xs font-medium',
        tierButton: 'mt-6 md:mt-auto md:pt-6',
        tierFeatureIcon: 'size-5 shrink-0',
        section: 'mt-6 flex flex-col gap-2',
        sectionTitle: 'font-semibold text-sm text-highlighted',
        feature: 'flex items-center justify-between gap-1',
        featureTitle: 'text-sm text-default',
        featureValue: 'text-sm text-muted flex justify-center min-w-5'
      },
      variants: {
        section: {
          true: {
            tr: '*:pt-8'
          }
        },
        active: {
          true: {
            tierFeatureIcon: 'text-primary'
          }
        },
        highlight: {
          true: {
            tier: 'bg-elevated/50 border-x border-t border-default rounded-t-lg',
            td: 'bg-elevated/50 border-x border-default',
            item: 'bg-elevated/50'
          }
        }
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/PricingTable.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/pricing-table.ts).


# Progress

## Uso

Use a diretiva `v-model` para controlar o valor do Progress.

```vue
<script setup lang="ts">
const value = ref(50)
</script>

<template>
  <UProgress v-model="value" />
</template>
```

### Máximo

Use a prop `max` para definir o valor máximo do Progress.

```vue
<script setup lang="ts">
const value = ref(3)
</script>

<template>
  <UProgress v-model="value" :max="4" />
</template>
```

Use a prop `max` com um array de strings para exibir a etapa ativa sob a barra; o valor máximo do Progress é o comprimento do array.

```vue
<script setup lang="ts">
const value = ref(3)
</script>

<template>
  <UProgress v-model="value" :max="[
  'Waiting...',
  'Cloning...',
  'Migrating...',
  'Deploying...',
  'Done!'
]" />
</template>
```

### Status

Use a prop `status` para exibir o valor atual do Progress acima da barra.

```vue
<script setup lang="ts">
const value = ref(50)
</script>

<template>
  <UProgress v-model="value" status />
</template>
```

### Indeterminado

Quando nenhum `v-model` é definido ou o valor é `null`, o Progress se torna *indeterminado*. A barra de progresso é animada como um `carousel`, mas você pode alterá-la usando a prop [`animation`](https://ui.nitro.news/#animation).

```vue
<script setup lang="ts">
const value = ref(null)
</script>

<template>
  <UProgress />
</template>
```

### Animação

Use a prop `animation` para alterar a animação do Progress para um carousel inverso, uma barra oscilante ou uma barra elástica. O padrão é `carousel`.

```vue
<template>
  <UProgress animation="swing" />
</template>
```

### Orientação

Use a prop `orientation` para alterar a orientação do Progress. O padrão é `horizontal`.

```vue
<template>
  <UProgress orientation="vertical" class="h-48" />
</template>
```

### Cor

Use a prop `color` para alterar a cor do Slider.

```vue
<template>
  <UProgress color="neutral" />
</template>
```

### Tamanho

Use a prop `size` para alterar o tamanho do Slider.

```vue
<template>
  <UProgress size="xl" />
</template>
```

### Invertido

Use a prop `inverted` para inverter visualmente o Progress.

```vue
<template>
  <UProgress inverted v-model="value" />
</template>
```

## API

### Props

```ts
/**
 * Props for the Progress component
 */
interface ProgressProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  /**
   * The maximum progress value.
   */
  max?: number | any[] | undefined;
  /**
   * Display the current progress value.
   */
  status?: boolean | undefined;
  /**
   * Whether the progress is visually inverted.
   * @default "false"
   */
  inverted?: boolean | undefined;
  size?: "2xs" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | undefined;
  color?: "error" | "primary" | "secondary" | "accent" | "success" | "info" | "warning" | "neutral" | undefined;
  /**
   * The orientation of the progress bar.
   * @default "\"horizontal\""
   */
  orientation?: "horizontal" | "vertical" | undefined;
  /**
   * The animation of the progress bar.
   */
  animation?: "carousel" | "carousel-inverse" | "swing" | "elastic" | undefined;
  ui?: { root?: SlotClass; base?: SlotClass; indicator?: SlotClass; status?: SlotClass; steps?: SlotClass; step?: SlotClass; } | undefined;
  /**
   * A function to get the accessible label text in a human-readable format.
   * 
   *  If not provided, the value label will be read as the numeric value as a percentage of the max value.
   */
  getValueLabel?: ((value: number | null | undefined, max: number) => string | undefined) | undefined;
  /**
   * A function to get the accessible value text representing the current value in a human-readable format.
   */
  getValueText?: ((value: number | null | undefined, max: number) => string | undefined) | undefined;
  /**
   * The progress value. Can be bind as `v-model`.
   * @default "null"
   */
  modelValue?: number | null | undefined;
}
```

### Slots

```ts
/**
 * Slots for the Progress component
 */
interface ProgressSlots {
  status(): any;
}
```

### Emits

```ts
/**
 * Emitted events for the Progress component
 */
interface ProgressEmits {
  update:modelValue: (payload: [value: string[] | undefined]) => void;
  update:max: (payload: [value: number]) => void;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    progress: {
      slots: {
        root: 'gap-2',
        base: 'relative overflow-hidden rounded-full bg-accented',
        indicator: 'rounded-full size-full transition-transform duration-200 ease-out',
        status: 'flex text-dimmed transition-[width] duration-200',
        steps: 'grid items-end',
        step: 'truncate text-end row-start-1 col-start-1 transition-opacity'
      },
      variants: {
        animation: {
          carousel: '',
          'carousel-inverse': '',
          swing: '',
          elastic: ''
        },
        color: {
          primary: {
            indicator: 'bg-primary',
            steps: 'text-primary'
          },
          secondary: {
            indicator: 'bg-secondary',
            steps: 'text-secondary'
          },
          accent: {
            indicator: 'bg-accent',
            steps: 'text-accent'
          },
          success: {
            indicator: 'bg-success',
            steps: 'text-success'
          },
          info: {
            indicator: 'bg-info',
            steps: 'text-info'
          },
          warning: {
            indicator: 'bg-warning',
            steps: 'text-warning'
          },
          error: {
            indicator: 'bg-error',
            steps: 'text-error'
          },
          neutral: {
            indicator: 'bg-inverted',
            steps: 'text-inverted'
          }
        },
        size: {
          '2xs': {
            status: 'text-xs',
            steps: 'text-xs'
          },
          xs: {
            status: 'text-xs',
            steps: 'text-xs'
          },
          sm: {
            status: 'text-sm',
            steps: 'text-sm'
          },
          md: {
            status: 'text-sm',
            steps: 'text-sm'
          },
          lg: {
            status: 'text-sm',
            steps: 'text-sm'
          },
          xl: {
            status: 'text-base',
            steps: 'text-base'
          },
          '2xl': {
            status: 'text-base',
            steps: 'text-base'
          }
        },
        step: {
          active: {
            step: 'opacity-100'
          },
          first: {
            step: 'opacity-100 text-muted'
          },
          other: {
            step: 'opacity-0'
          },
          last: {
            step: ''
          }
        },
        orientation: {
          horizontal: {
            root: 'w-full flex flex-col',
            base: 'w-full',
            status: 'flex-row items-center justify-end min-w-fit'
          },
          vertical: {
            root: 'h-full flex flex-row-reverse',
            base: 'h-full',
            status: 'flex-col justify-end min-h-fit'
          }
        },
        inverted: {
          true: {
            status: 'self-end'
          }
        }
      },
      compoundVariants: [
        {
          inverted: true,
          orientation: 'horizontal',
          class: {
            step: 'text-start',
            status: 'flex-row-reverse'
          }
        },
        {
          inverted: true,
          orientation: 'vertical',
          class: {
            steps: 'items-start',
            status: 'flex-col-reverse'
          }
        },
        {
          orientation: 'horizontal',
          size: '2xs',
          class: 'h-px'
        },
        {
          orientation: 'horizontal',
          size: 'xs',
          class: 'h-0.5'
        },
        {
          orientation: 'horizontal',
          size: 'sm',
          class: 'h-1'
        },
        {
          orientation: 'horizontal',
          size: 'md',
          class: 'h-2'
        },
        {
          orientation: 'horizontal',
          size: 'lg',
          class: 'h-3'
        },
        {
          orientation: 'horizontal',
          size: 'xl',
          class: 'h-4'
        },
        {
          orientation: 'horizontal',
          size: '2xl',
          class: 'h-5'
        },
        {
          orientation: 'vertical',
          size: '2xs',
          class: 'w-px'
        },
        {
          orientation: 'vertical',
          size: 'xs',
          class: 'w-0.5'
        },
        {
          orientation: 'vertical',
          size: 'sm',
          class: 'w-1'
        },
        {
          orientation: 'vertical',
          size: 'md',
          class: 'w-2'
        },
        {
          orientation: 'vertical',
          size: 'lg',
          class: 'w-3'
        },
        {
          orientation: 'vertical',
          size: 'xl',
          class: 'w-4'
        },
        {
          orientation: 'vertical',
          size: '2xl',
          class: 'w-5'
        },
        {
          orientation: 'horizontal',
          animation: 'carousel',
          class: {
            indicator: 'data-[state=indeterminate]:animate-[carousel_2s_ease-in-out_infinite] data-[state=indeterminate]:rtl:animate-[carousel-rtl_2s_ease-in-out_infinite]'
          }
        },
        {
          orientation: 'vertical',
          animation: 'carousel',
          class: {
            indicator: 'data-[state=indeterminate]:animate-[carousel-vertical_2s_ease-in-out_infinite]'
          }
        },
        {
          orientation: 'horizontal',
          animation: 'carousel-inverse',
          class: {
            indicator: 'data-[state=indeterminate]:animate-[carousel-inverse_2s_ease-in-out_infinite] data-[state=indeterminate]:rtl:animate-[carousel-inverse-rtl_2s_ease-in-out_infinite]'
          }
        },
        {
          orientation: 'vertical',
          animation: 'carousel-inverse',
          class: {
            indicator: 'data-[state=indeterminate]:animate-[carousel-inverse-vertical_2s_ease-in-out_infinite]'
          }
        },
        {
          orientation: 'horizontal',
          animation: 'swing',
          class: {
            indicator: 'data-[state=indeterminate]:animate-[swing_2s_ease-in-out_infinite]'
          }
        },
        {
          orientation: 'vertical',
          animation: 'swing',
          class: {
            indicator: 'data-[state=indeterminate]:animate-[swing-vertical_2s_ease-in-out_infinite]'
          }
        },
        {
          orientation: 'horizontal',
          animation: 'elastic',
          class: {
            indicator: 'data-[state=indeterminate]:animate-[elastic_2s_ease-in-out_infinite]'
          }
        },
        {
          orientation: 'vertical',
          animation: 'elastic',
          class: {
            indicator: 'data-[state=indeterminate]:animate-[elastic-vertical_2s_ease-in-out_infinite]'
          }
        }
      ],
      defaultVariants: {
        animation: 'carousel',
        color: 'primary',
        size: 'md'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/Progress.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/progress.ts).


# RadioGroup

## Uso

Use a diretiva `v-model` para controlar o valor do RadioGroup ou a prop `default-value` para definir o valor inicial quando você não precisa controlar o estado.

```vue
<script setup lang="ts">
const items = ref([
  "System",
  "Light",
  "Dark"
])
const value = ref("System")
</script>

<template>
  <URadioGroup v-model="value" :items="items" />
</template>
```

### Itens

Use a prop `items` como um array de strings ou números:

```vue
<script setup lang="ts">
const items = ref([
  "System",
  "Light",
  "Dark"
])
const value = ref("System")
</script>

<template>
  <URadioGroup v-model="value" :items="items" />
</template>
```

Você também pode passar um array de objetos com as seguintes propriedades:

- `label?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `description?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- [`value?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}](https://ui.nitro.news/#value-key)
- `disabled?: boolean`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `class?: any`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `ui?: { item?: ClassNameValue, container?: ClassNameValue, base?: ClassNameValue, 'indicator'?: ClassNameValue, wrapper?: ClassNameValue, label?: ClassNameValue, description?: ClassNameValue }`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

```vue
<script setup lang="ts">
import type { RadioGroupItem } from '@nitro/ui'

const items = ref<RadioGroupItem[]>([
  {
    label: "System",
    description: "This is the first option.",
    value: "system"
  },
  {
    label: "Light",
    description: "This is the second option.",
    value: "light"
  },
  {
    label: "Dark",
    description: "This is the third option.",
    value: "dark"
  }
])
const value = ref("system")
</script>

<template>
  <URadioGroup v-model="value" :items="items" />
</template>
```

> \[!CAUTION]
>
> Ao usar objetos, você precisa referenciar a propriedade `value` do objeto na diretiva `v-model` ou na prop `default-value`.

### Chave de valor

Você pode alterar a propriedade usada para definir o valor usando a prop `value-key`. O padrão é `value`.

```vue
<script setup lang="ts">
import type { RadioGroupItem } from '@nitro/ui'

const items = ref<RadioGroupItem[]>([
  {
    label: "System",
    description: "This is the first option.",
    id: "system"
  },
  {
    label: "Light",
    description: "This is the second option.",
    id: "light"
  },
  {
    label: "Dark",
    description: "This is the third option.",
    id: "dark"
  }
])
const value = ref("light")
</script>

<template>
  <URadioGroup v-model="value" value-key="id" :items="items" />
</template>
```

### Legenda

Use a prop `legend` para definir a legenda do RadioGroup.

```vue
<script setup lang="ts">
const items = ref([
  "System",
  "Light",
  "Dark"
])
</script>

<template>
  <URadioGroup legend="Theme" default-value="System" :items="items" />
</template>
```

### Cor

Use a prop `color` para alterar a cor do RadioGroup.

```vue
<script setup lang="ts">
const items = ref([
  "System",
  "Light",
  "Dark"
])
</script>

<template>
  <URadioGroup color="neutral" default-value="System" :items="items" />
</template>
```

### Variante

Use a prop `variant` para alterar a variante do RadioGroup.

```vue
<script setup lang="ts">
import type { RadioGroupItem } from '@nitro/ui'

const items = ref<RadioGroupItem[]>([
  {
    label: "Pro",
    value: "pro",
    description: "Tailored for indie hackers, freelancers and solo founders."
  },
  {
    label: "Startup",
    value: "startup",
    description: "Best suited for small teams, startups and agencies."
  },
  {
    label: "Enterprise",
    value: "enterprise",
    description: "Ideal for larger teams and organizations."
  }
])
</script>

<template>
  <URadioGroup color="primary" variant="table" default-value="pro" :items="items" />
</template>
```

### Tamanho

Use a prop `size` para alterar o tamanho do RadioGroup.

```vue
<script setup lang="ts">
const items = ref([
  "System",
  "Light",
  "Dark"
])
</script>

<template>
  <URadioGroup size="xl" variant="list" default-value="System" :items="items" />
</template>
```

### Orientação

Use a prop `orientation` para alterar a orientação do RadioGroup. O padrão é `vertical`.

```vue
<script setup lang="ts">
const items = ref([
  "System",
  "Light",
  "Dark"
])
</script>

<template>
  <URadioGroup orientation="horizontal" variant="list" default-value="System" :items="items" />
</template>
```

### Indicador

Use a prop `indicator` para alterar a posição ou ocultar o indicador. O padrão é `start`.

```vue
<script setup lang="ts">
const items = ref([
  "System",
  "Light",
  "Dark"
])
</script>

<template>
  <URadioGroup indicator="end" variant="card" default-value="System" :items="items" />
</template>
```

### Desabilitado

Use a prop `disabled` para desabilitar o RadioGroup.

```vue
<script setup lang="ts">
const items = ref([
  "System",
  "Light",
  "Dark"
])
</script>

<template>
  <URadioGroup disabled default-value="System" :items="items" />
</template>
```

## API

### Props

```ts
/**
 * Props for the RadioGroup component
 */
interface RadioGroupProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  legend?: string | undefined;
  /**
   * When `items` is an array of objects, select the field to use as the value.
   * @default "\"value\" as never"
   */
  valueKey?: VK | undefined;
  /**
   * When `items` is an array of objects, select the field to use as the label.
   * @default "\"label\""
   */
  labelKey?: GetItemKeys<T> | undefined;
  /**
   * When `items` is an array of objects, select the field to use as the description.
   * @default "\"description\""
   */
  descriptionKey?: GetItemKeys<T> | undefined;
  items?: T | undefined;
  /**
   * The controlled value of the RadioGroup. Can be bind as `v-model`.
   */
  modelValue?: GetItemValue<T, VK, undefined, NestedItem<T>> | undefined;
  /**
   * The value of the RadioGroup when initially rendered. Use when you do not need to control the state of the RadioGroup.
   */
  defaultValue?: GetItemValue<T, VK, undefined, NestedItem<T>> | undefined;
  size?: "xs" | "sm" | "md" | "lg" | "xl" | undefined;
  variant?: "card" | "list" | "table" | undefined;
  color?: "primary" | "secondary" | "accent" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
  /**
   * Highlight the ring color like a focus state.
   */
  highlight?: boolean | undefined;
  /**
   * The orientation the radio buttons are laid out.
   * @default "\"vertical\""
   */
  orientation?: "horizontal" | "vertical" | undefined;
  /**
   * Position of the indicator.
   */
  indicator?: "start" | "end" | "hidden" | undefined;
  ui?: { root?: SlotClass; fieldset?: SlotClass; legend?: SlotClass; item?: SlotClass; container?: SlotClass; base?: SlotClass; indicator?: SlotClass; wrapper?: SlotClass; label?: SlotClass; description?: SlotClass; icon?: SlotClass; trailing?: SlotClass; } | undefined;
  /**
   * When `true`, prevents the user from interacting with radio items.
   */
  disabled?: boolean | undefined;
  /**
   * When `true`, keyboard navigation will loop from last item to first, and vice versa.
   */
  loop?: boolean | undefined;
  /**
   * The name of the field. Submitted with its owning form as part of a name/value pair.
   */
  name?: string | undefined;
  /**
   * When `true`, indicates that the user must set the value before the owning form can be submitted.
   */
  required?: boolean | undefined;
}
```

### Slots

```ts
/**
 * Slots for the RadioGroup component
 */
interface RadioGroupSlots {
  legend(): any;
  label(): any;
  description(): any;
  trailing(): any;
}
```

### Emits

```ts
/**
 * Emitted events for the RadioGroup component
 */
interface RadioGroupEmits {
  update:modelValue: (payload: [value: GetItemValue<T, VK, undefined, NestedItem<T>>]) => void;
  change: (payload: [event: Event]) => void;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    radioGroup: {
      slots: {
        root: 'relative',
        fieldset: 'flex gap-x-2',
        legend: 'mb-1 block font-medium text-default',
        item: 'flex items-start gap-2',
        container: 'flex items-center',
        base: 'rounded-full ring ring-inset ring-accented overflow-hidden focus-visible:outline-2 focus-visible:outline-offset-2',
        indicator: 'flex items-center justify-center size-full after:bg-default after:rounded-full',
        wrapper: 'w-full',
        label: 'block font-medium text-default',
        description: 'text-muted',
        icon: 'shrink-0',
        trailing: 'ml-auto'
      },
      variants: {
        color: {
          primary: {
            base: 'focus-visible:outline-primary',
            indicator: 'bg-primary'
          },
          secondary: {
            base: 'focus-visible:outline-secondary',
            indicator: 'bg-secondary'
          },
          accent: {
            base: 'focus-visible:outline-accent',
            indicator: 'bg-accent'
          },
          success: {
            base: 'focus-visible:outline-success',
            indicator: 'bg-success'
          },
          info: {
            base: 'focus-visible:outline-info',
            indicator: 'bg-info'
          },
          warning: {
            base: 'focus-visible:outline-warning',
            indicator: 'bg-warning'
          },
          error: {
            base: 'focus-visible:outline-error',
            indicator: 'bg-error'
          },
          neutral: {
            base: 'focus-visible:outline-inverted',
            indicator: 'bg-inverted'
          }
        },
        variant: {
          list: {
            item: ''
          },
          card: {
            item: 'border border-muted rounded-lg'
          },
          table: {
            item: 'border border-muted'
          }
        },
        orientation: {
          horizontal: {
            fieldset: 'flex-row'
          },
          vertical: {
            fieldset: 'flex-col'
          }
        },
        indicator: {
          start: {
            item: 'flex-row'
          },
          end: {
            item: 'flex-row-reverse'
          },
          hidden: {
            base: 'sr-only',
            wrapper: 'text-center'
          }
        },
        size: {
          xs: {
            fieldset: 'gap-y-0.5',
            legend: 'text-xs',
            base: 'size-3',
            item: 'text-xs',
            container: 'h-4',
            indicator: 'after:size-1',
            icon: 'size-4'
          },
          sm: {
            fieldset: 'gap-y-0.5',
            legend: 'text-xs',
            base: 'size-3.5',
            item: 'text-xs',
            container: 'h-4',
            indicator: 'after:size-1',
            icon: 'size-4'
          },
          md: {
            fieldset: 'gap-y-1',
            legend: 'text-sm',
            base: 'size-4',
            item: 'text-sm',
            container: 'h-5',
            indicator: 'after:size-1.5',
            icon: 'size-5'
          },
          lg: {
            fieldset: 'gap-y-1',
            legend: 'text-sm',
            base: 'size-4.5',
            item: 'text-sm',
            container: 'h-5',
            indicator: 'after:size-1.5',
            icon: 'size-5'
          },
          xl: {
            fieldset: 'gap-y-1.5',
            legend: 'text-base',
            base: 'size-5',
            item: 'text-base',
            container: 'h-6',
            indicator: 'after:size-2',
            icon: 'size-6'
          }
        },
        highlight: {
          true: ''
        },
        disabled: {
          true: {
            item: 'opacity-75',
            base: 'cursor-not-allowed',
            label: 'cursor-not-allowed',
            description: 'cursor-not-allowed'
          }
        },
        required: {
          true: {
            legend: "after:content-['*'] after:ms-0.5 after:text-error"
          }
        }
      },
      compoundVariants: [
        {
          size: 'xs',
          variant: [
            'card',
            'table'
          ],
          class: {
            item: 'p-2.5'
          }
        },
        {
          size: 'sm',
          variant: [
            'card',
            'table'
          ],
          class: {
            item: 'p-3'
          }
        },
        {
          size: 'md',
          variant: [
            'card',
            'table'
          ],
          class: {
            item: 'p-3.5'
          }
        },
        {
          size: 'lg',
          variant: [
            'card',
            'table'
          ],
          class: {
            item: 'p-4'
          }
        },
        {
          size: 'xl',
          variant: [
            'card',
            'table'
          ],
          class: {
            item: 'p-4.5'
          }
        },
        {
          orientation: 'horizontal',
          variant: 'table',
          class: {
            item: 'first-of-type:rounded-s-lg last-of-type:rounded-e-lg',
            fieldset: 'gap-0 -space-x-px'
          }
        },
        {
          orientation: 'vertical',
          variant: 'table',
          class: {
            item: 'first-of-type:rounded-t-lg last-of-type:rounded-b-lg',
            fieldset: 'gap-0 -space-y-px'
          }
        },
        {
          color: 'primary',
          variant: 'card',
          class: {
            item: 'has-data-[state=checked]:border-primary'
          }
        },
        {
          color: 'secondary',
          variant: 'card',
          class: {
            item: 'has-data-[state=checked]:border-secondary'
          }
        },
        {
          color: 'accent',
          variant: 'card',
          class: {
            item: 'has-data-[state=checked]:border-accent'
          }
        },
        {
          color: 'success',
          variant: 'card',
          class: {
            item: 'has-data-[state=checked]:border-success'
          }
        },
        {
          color: 'info',
          variant: 'card',
          class: {
            item: 'has-data-[state=checked]:border-info'
          }
        },
        {
          color: 'warning',
          variant: 'card',
          class: {
            item: 'has-data-[state=checked]:border-warning'
          }
        },
        {
          color: 'error',
          variant: 'card',
          class: {
            item: 'has-data-[state=checked]:border-error'
          }
        },
        {
          color: 'neutral',
          variant: 'card',
          class: {
            item: 'has-data-[state=checked]:border-inverted'
          }
        },
        {
          color: 'primary',
          variant: 'table',
          class: {
            item: 'has-data-[state=checked]:bg-primary/10 has-data-[state=checked]:border-primary/50 has-data-[state=checked]:z-[1]'
          }
        },
        {
          color: 'secondary',
          variant: 'table',
          class: {
            item: 'has-data-[state=checked]:bg-secondary/10 has-data-[state=checked]:border-secondary/50 has-data-[state=checked]:z-[1]'
          }
        },
        {
          color: 'accent',
          variant: 'table',
          class: {
            item: 'has-data-[state=checked]:bg-accent/10 has-data-[state=checked]:border-accent/50 has-data-[state=checked]:z-[1]'
          }
        },
        {
          color: 'success',
          variant: 'table',
          class: {
            item: 'has-data-[state=checked]:bg-success/10 has-data-[state=checked]:border-success/50 has-data-[state=checked]:z-[1]'
          }
        },
        {
          color: 'info',
          variant: 'table',
          class: {
            item: 'has-data-[state=checked]:bg-info/10 has-data-[state=checked]:border-info/50 has-data-[state=checked]:z-[1]'
          }
        },
        {
          color: 'warning',
          variant: 'table',
          class: {
            item: 'has-data-[state=checked]:bg-warning/10 has-data-[state=checked]:border-warning/50 has-data-[state=checked]:z-[1]'
          }
        },
        {
          color: 'error',
          variant: 'table',
          class: {
            item: 'has-data-[state=checked]:bg-error/10 has-data-[state=checked]:border-error/50 has-data-[state=checked]:z-[1]'
          }
        },
        {
          color: 'neutral',
          variant: 'table',
          class: {
            item: 'has-data-[state=checked]:bg-elevated has-data-[state=checked]:border-inverted/50 has-data-[state=checked]:z-[1]'
          }
        },
        {
          variant: [
            'card',
            'table'
          ],
          disabled: true,
          class: {
            item: 'cursor-not-allowed'
          }
        },
        {
          color: 'primary',
          highlight: true,
          class: {
            base: 'ring-primary'
          }
        },
        {
          color: 'secondary',
          highlight: true,
          class: {
            base: 'ring-secondary'
          }
        },
        {
          color: 'accent',
          highlight: true,
          class: {
            base: 'ring-accent'
          }
        },
        {
          color: 'success',
          highlight: true,
          class: {
            base: 'ring-success'
          }
        },
        {
          color: 'info',
          highlight: true,
          class: {
            base: 'ring-info'
          }
        },
        {
          color: 'warning',
          highlight: true,
          class: {
            base: 'ring-warning'
          }
        },
        {
          color: 'error',
          highlight: true,
          class: {
            base: 'ring-error'
          }
        },
        {
          color: 'neutral',
          highlight: true,
          class: {
            base: 'ring-inverted'
          }
        }
      ],
      defaultVariants: {
        size: 'md',
        color: 'primary',
        variant: 'list',
        indicator: 'start'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/RadioGroup.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/radio-group.ts).


# ScrollArea

## Uso

O componente ScrollArea cria containers roláveis com virtualização opcional para listas grandes.

::component-example
---
collapse: true
overflowHidden: true
class: "!p-0"
name: scroll-area-example
---
::

### Itens

Use a prop `items` como um array e renderize cada item usando o slot padrão:

::component-example
---
collapse: true
overflowHidden: true
class: "!p-0"
name: scroll-area-items-example
---
::

> \[!TIP]
> See: #with-default-slot
>
> Você também pode usar o slot padrão sem a prop `items` para renderizar conteúdo rolável personalizado diretamente.

### Orientação

Use a prop `orientation` para alterar a direção da rolagem. O padrão é `vertical`.

::component-example
---
collapse: true
options:
  - name: orientation
    label: orientation
    default: horizontal
    items:
      - vertical
      - horizontal
overflowHidden: true
class: "!p-0"
name: scroll-area-orientation-example
---
::

### Virtualizar

Use a prop `virtualize` para renderizar apenas os itens que estão em exibição no momento, melhorando significativamente o desempenho ao trabalhar com grandes conjuntos de dados.

> \[!NOTE]
>
> Quando a virtualização está **habilitada**, personalize o espaçamento por meio das opções da prop `virtualize`, como `gap`, `paddingStart` e `paddingEnd`. Caso contrário, use a prop `ui` para aplicar classes como `gap p-4` no slot `viewport`.

> \[!TIP]
>
> Se todos os seus itens têm a **mesma altura**, defina `skipMeasurement` como `true` na prop `virtualize` para pular a medição de DOM por item e usar o `estimateSize`. Isso melhora significativamente o desempenho em listas grandes e uniformes.

::component-example
---
collapse: true
options:
  - name: orientation
    label: orientation
    default: vertical
    items:
      - vertical
      - horizontal
overflowHidden: true
class: "!p-0"
name: scroll-area-virtualize-example
---
::

### Sombra `4.9+`

Use a prop `shadow` para exibir sombras de esmaecimento nas bordas roláveis, indicando que há mais conteúdo disponível na direção da rolagem. O esmaecimento acompanha automaticamente a `orientation` e só aparece quando o conteúdo transborda.

::component-example{collapse name="scroll-area-shadow-example"}
::

> \[!TIP]
>
> Passe um objeto para a prop `shadow` para configurar o tamanho do esmaecimento, ex.: `:shadow="{ size: 48 }"`.

## Exemplos

### Como layout masonry

Use a prop `virtualize` com as opções `lanes`, `gap` e `estimateSize` para criar layouts masonry no estilo Pinterest com itens de altura variável.

::component-example
---
collapse: true
options:
  - name: orientation
    label: orientation
    default: vertical
    items:
      - vertical
      - horizontal
  - name: lanes
    type: number
    label: lanes
    default: 3
  - name: gap
    type: number
    label: gap
    default: 16
overflowHidden: true
class: "!p-0"
name: scroll-area-masonry-layout-example
---
::

> \[!TIP]
>
> Para um desempenho ideal, defina `estimateSize` próximo da altura média dos seus itens. Aumentar o `overscan` melhora a suavidade da rolagem, mas renderiza mais itens fora da tela.

### Com faixas responsivas

Você pode usar os composables [`useWindowSize`](https://vueuse.org/core/useWindowSize/){rel="&#x22;nofollow&#x22;"} (baseado na viewport) ou [`useElementSize`](https://vueuse.org/core/useElementSize/){rel="&#x22;nofollow&#x22;"} (baseado no container) para tornar as `lanes` reativas.

::component-example
---
collapse: true
overflowHidden: true
class: "!p-0"
name: scroll-area-responsive-lanes-example
---
::

### Com elemento de rolagem externo `Soon`

Passe uma função `getScrollElement` na prop `virtualize` para virtualizar em relação a um container de rolagem ancestral em vez da própria viewport do componente. Defina `scrollMargin` como o deslocamento da lista em relação ao início do elemento de rolagem (ex.: a altura do conteúdo acima dela).

::component-example
---
collapse: true
options:
  - name: orientation
    label: orientation
    default: vertical
    items:
      - vertical
      - horizontal
overflowHidden: true
prettier: true
class: "!p-0"
name: scroll-area-external-scroll-example
---
::

> \[!NOTE]
>
> Como o container controla a rolagem, os botões de busca e "Topo" da barra de ferramentas o rolam diretamente com `container.scrollTo`.

> \[!CAUTION]
>
> A prop `shadow` não tem efeito nesse modo, já que o root não controla mais a rolagem. Em vez disso, aplique o seu próprio esmaecimento ao container de rolagem.

### Com rolagem programática

Você pode usar o `virtualizer` exposto para controlar a posição de rolagem programaticamente.

::component-example
---
collapse: true
overflowHidden: true
class: "!p-0"
name: scroll-area-scroll-to-example
---
::

### Com rolagem infinita

Você pode usar o composable [`useInfiniteScroll`](https://vueuse.org/core/useInfiniteScroll/){rel="&#x22;nofollow&#x22;"} para carregar mais dados conforme o usuário rola.

::component-example
---
collapse: true
overflowHidden: true
prettier: true
class: "!p-0"
name: scroll-area-infinite-scroll-example
---
::

> \[!NOTE]
>
> Este exemplo usa `useLazyFetch` com `server: false` para buscar os dados no cliente sem bloquear a renderização inicial. O estado de carregamento verifica os status `pending` e `idle` para exibir um indicador de carregamento antes e durante a busca. Páginas adicionais são carregadas conforme o usuário rola.

### Com slot padrão

Você pode usar o slot padrão sem a prop `items` para renderizar conteúdo rolável personalizado diretamente.

:component-example{.!p-0 name="scroll-area-default-slot-example"}

## API

### Props

```ts
/**
 * Props for the ScrollArea component
 */
interface ScrollAreaProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  /**
   * The scroll direction.
   * @default "\"vertical\""
   */
  orientation?: "vertical" | "horizontal" | undefined;
  /**
   * Array of items to render.
   */
  items?: T[] | undefined;
  /**
   * Enable virtualization for large lists.
   * @default "false"
   */
  virtualize?: boolean | ScrollAreaVirtualizeOptions | undefined;
  /**
   * Display fade shadows on the scrollable edges to indicate more content.
   * Pass an object to configure the shadow size (in px).
   * @default "false"
   */
  shadow?: boolean | { size?: number | undefined; } | undefined;
  ui?: { root?: SlotClass; viewport?: SlotClass; item?: SlotClass; } | undefined;
}
```

### Slots

```ts
/**
 * Slots for the ScrollArea component
 */
interface ScrollAreaSlots {
  default(): any;
}
```

### Emits

```ts
/**
 * Emitted events for the ScrollArea component
 */
interface ScrollAreaEmits {
  scroll: (payload: [isScrolling: boolean]) => void;
}
```

### Expose

Você pode acessar a instância tipada do componente usando [`useTemplateRef`](https://vuejs.org/api/composition-api-helpers.html#usetemplateref){rel="&#x22;nofollow&#x22;"}.

```vue
<script setup lang="ts">
const scrollArea = useTemplateRef('scrollArea')

// Scroll to a specific item
function scrollToItem(index: number) {
  scrollArea.value?.virtualizer?.scrollToIndex(index, { align: 'center' })
}
</script>

<template>
  <NScrollArea ref="scrollArea" :items="items" virtualize />
</template>
```

Isso dará a você acesso ao seguinte:

| Name                                                                                                                              | Type                                                                                                                                               | Description                                                                                                                                                                    |
| --------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `$el`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"}         | `HTMLElement`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"}                  | The root element of the component.                                                                                                                                             |
| `virtualizer`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | `Ref<Virtualizer> | undefined`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | The [TanStack Virtual](https://tanstack.com/virtual/latest/docs/api/virtualizer){rel="&#x22;nofollow&#x22;"} virtualizer instance (`undefined` if virtualization is disabled). |

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    scrollArea: {
      slots: {
        root: 'relative outline-accent/25 focus-visible:outline-3',
        viewport: 'relative flex',
        item: ''
      },
      variants: {
        orientation: {
          vertical: {
            root: 'overflow-y-auto overflow-x-hidden',
            viewport: 'flex-col',
            item: ''
          },
          horizontal: {
            root: 'overflow-x-auto overflow-y-hidden',
            viewport: 'flex-row',
            item: ''
          }
        },
        externalScroll: {
          true: {
            root: 'overflow-visible'
          }
        }
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/ScrollArea.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/scroll-area.ts).


# Select

## Uso

Use a diretiva `v-model` para controlar o valor do Select ou a prop `default-value` para definir o valor inicial quando você não precisa controlar o estado.

```vue
<script setup lang="ts">
const items = ref([
  "Backlog",
  "Todo",
  "In Progress",
  "Done"
])
const value = ref("Backlog")
</script>

<template>
  <USelect v-model="value" :items="items" />
</template>
```

### Itens

Use a prop `items` como um array de strings, números ou booleanos:

```vue
<script setup lang="ts">
const items = ref([
  "Backlog",
  "Todo",
  "In Progress",
  "Done"
])
const value = ref("Backlog")
</script>

<template>
  <USelect v-model="value" :items="items" class="w-48" />
</template>
```

Você também pode passar um array de objetos com as seguintes propriedades:

- `label?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- [`value?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}](https://ui.nitro.news/#value-key)
- [`type?: "label" | "separator" | "item"`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}](https://ui.nitro.news/#with-items-type)
- [`icon?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}](https://ui.nitro.news/#with-icons-in-items)
- [`avatar?: AvatarProps`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}](https://ui.nitro.news/#with-avatar-in-items)
- [`chip?: ChipProps`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}](https://ui.nitro.news/#with-chip-in-items)
- `disabled?: boolean`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `class?: any`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `ui?: { label?: ClassNameValue, separator?: ClassNameValue, item?: ClassNameValue, itemLeadingIcon?: ClassNameValue, itemLeadingAvatarSize?: ClassNameValue, itemLeadingAvatar?: ClassNameValue, itemLeadingChipSize?: ClassNameValue, itemLeadingChip?: ClassNameValue, itemLabel?: ClassNameValue, itemTrailing?: ClassNameValue, itemTrailingIcon?: ClassNameValue }`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

```vue
<script setup lang="ts">
import type { SelectItem } from '@nitro/ui'

const items = ref<SelectItem[]>([
  {
    label: "Backlog",
    value: "backlog"
  },
  {
    label: "Todo",
    value: "todo"
  },
  {
    label: "In Progress",
    value: "in_progress"
  },
  {
    label: "Done",
    value: "done"
  }
])
const value = ref("backlog")
</script>

<template>
  <USelect v-model="value" :items="items" class="w-48" />
</template>
```

> \[!CAUTION]
>
> Ao usar objetos, você precisa referenciar a propriedade `value` do objeto na diretiva `v-model` ou na prop `default-value`.

Você também pode passar um array de arrays para a prop `items` para exibir grupos separados de itens.

```vue
<script setup lang="ts">
const items = ref([
  [
    "Apple",
    "Banana",
    "Blueberry",
    "Grapes",
    "Pineapple"
  ],
  [
    "Aubergine",
    "Broccoli",
    "Carrot",
    "Courgette",
    "Leek"
  ]
])
const value = ref("Apple")
</script>

<template>
  <USelect v-model="value" :items="items" class="w-48" />
</template>
```

### Chave de valor

Você pode alterar a propriedade usada para definir o valor usando a prop `value-key`. O padrão é `value`.

```vue
<script setup lang="ts">
import type { SelectItem } from '@nitro/ui'

const items = ref<SelectItem[]>([
  {
    label: "Backlog",
    id: "backlog"
  },
  {
    label: "Todo",
    id: "todo"
  },
  {
    label: "In Progress",
    id: "in_progress"
  },
  {
    label: "Done",
    id: "done"
  }
])
const value = ref("backlog")
</script>

<template>
  <USelect v-model="value" value-key="id" :items="items" class="w-48" />
</template>
```

### Múltiplo

Use a prop `multiple` para permitir múltiplas seleções; os itens selecionados serão separados por vírgula no gatilho.

```vue
<script setup lang="ts">
const items = ref([
  "Backlog",
  "Todo",
  "In Progress",
  "Done"
])
const value = ref([
  "Backlog",
  "Todo"
])
</script>

<template>
  <USelect v-model="value" multiple :items="items" class="w-48" />
</template>
```

> \[!CAUTION]
>
> Certifique-se de passar um array para a prop `default-value` ou para a diretiva `v-model`.

### Placeholder

Use a prop `placeholder` para definir um texto de placeholder.

```vue
<script setup lang="ts">
const items = ref([
  "Backlog",
  "Todo",
  "In Progress",
  "Done"
])
</script>

<template>
  <USelect placeholder="Select status" :items="items" class="w-48" />
</template>
```

### Conteúdo

Use a prop `content` para controlar como o conteúdo do Select é renderizado, como seu `align` ou `side`, por exemplo.

```vue
<script setup lang="ts">
const items = ref([
  "Backlog",
  "Todo",
  "In Progress",
  "Done"
])
const value = ref("Backlog")
</script>

<template>
  <USelect v-model="value" :content="{
  align: 'center',
  side: 'bottom',
  sideOffset: 8
}" :items="items" class="w-48" />
</template>
```

> \[!NOTE]
>
> Essas opções só se aplicam quando `content.position` é `popper` (padrão).

### Posição `4.7+`

Use a prop `content.position` para controlar como o conteúdo do Select é posicionado em relação ao gatilho. O padrão é `popper`, que posiciona o conteúdo como outros popovers. Defina-a como `item-aligned` para alinhar o conteúdo com o item selecionado (semelhante a um menu nativo do macOS).

```vue
<script setup lang="ts">
const items = ref([
  "Backlog",
  "Todo",
  "In Progress",
  "Done"
])
const value = ref("Todo")
</script>

<template>
  <USelect v-model="value" :content="{
  position: 'item-aligned'
}" :items="items" class="w-48" />
</template>
```

### Seta

Use a prop `arrow` para exibir uma seta no Select.

```vue
<script setup lang="ts">
const items = ref([
  "Backlog",
  "Todo",
  "In Progress",
  "Done"
])
const value = ref("Backlog")
</script>

<template>
  <USelect v-model="value" arrow :items="items" class="w-48" />
</template>
```

### Cor

Use a prop `color` para alterar a cor do ring quando o Select está em foco.

```vue
<script setup lang="ts">
const items = ref([
  "Backlog",
  "Todo",
  "In Progress",
  "Done"
])
const value = ref("Backlog")
</script>

<template>
  <USelect v-model="value" color="neutral" highlight :items="items" class="w-48" />
</template>
```

> \[!NOTE]
>
> A prop `highlight` é usada aqui para mostrar o estado de foco. Ela é usada internamente quando ocorre um erro de validação.

### Variante

Use a prop `variant` para alterar a variante do Select.

```vue
<script setup lang="ts">
const items = ref([
  "Backlog",
  "Todo",
  "In Progress",
  "Done"
])
const value = ref("Backlog")
</script>

<template>
  <USelect v-model="value" color="neutral" variant="subtle" :highlight="false" :items="items" class="w-48" />
</template>
```

### Tamanho

Use a prop `size` para alterar o tamanho do Select.

```vue
<script setup lang="ts">
const items = ref([
  "Backlog",
  "Todo",
  "In Progress",
  "Done"
])
const value = ref("Backlog")
</script>

<template>
  <USelect v-model="value" size="xl" :items="items" class="w-48" />
</template>
```

### Ícone

Use a prop `icon` para exibir um [Icon](https://ui.nitro.news/docs/components/icon) dentro do Select.

```vue
<script setup lang="ts">
const items = ref([
  "Backlog",
  "Todo",
  "In Progress",
  "Done"
])
const value = ref("Backlog")
</script>

<template>
  <USelect v-model="value" icon="i-lucide-search" size="md" :items="items" class="w-48" />
</template>
```

### Ícone à direita

Use a prop `trailing-icon` para personalizar o [Icon](https://ui.nitro.news/docs/components/icon) à direita. O padrão é `i-lucide-chevron-down`.

```vue
<script setup lang="ts">
const items = ref([
  "Backlog",
  "Todo",
  "In Progress",
  "Done"
])
const value = ref("Backlog")
</script>

<template>
  <USelect v-model="value" trailing-icon="i-lucide-arrow-down" size="md" :items="items" class="w-48" />
</template>
```

**Nuxt:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/nuxt#theme
>
> Você pode personalizar esse ícone globalmente no seu `app.config.ts` na chave `ui.icons.chevronDown`.

**Vue:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/vue#theme
>
> Você pode personalizar esse ícone globalmente no seu `vite.config.ts` na chave `ui.icons.chevronDown`.

### Ícone de selecionado

Use a prop `selected-icon` para personalizar o ícone quando um item é selecionado. O padrão é `i-lucide-check`.

```vue
<script setup lang="ts">
const items = ref([
  "Backlog",
  "Todo",
  "In Progress",
  "Done"
])
const value = ref("Backlog")
</script>

<template>
  <USelect v-model="value" selected-icon="i-lucide-flame" size="md" :items="items" class="w-48" />
</template>
```

**Nuxt:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/nuxt#theme
>
> Você pode personalizar esse ícone globalmente no seu `app.config.ts` na chave `ui.icons.check`.

**Vue:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/vue#theme
>
> Você pode personalizar esse ícone globalmente no seu `vite.config.ts` na chave `ui.icons.check`.

### Avatar

Use a prop `avatar` para exibir um [Avatar](https://ui.nitro.news/docs/components/avatar) dentro do Select.

```vue
<script setup lang="ts">
const items = ref([
  "Nuxt",
  "NuxtHub",
  "NuxtLabs",
  "Nuxt Modules",
  "Nuxt Community"
])
const value = ref("Nuxt")
</script>

<template>
  <USelect v-model="value" :avatar="{
  src: 'https://github.com/nuxt.png',
  loading: 'lazy'
}" :items="items" class="w-48" />
</template>
```

### Carregando

Use a prop `loading` para exibir um ícone de carregamento no Select.

```vue
<script setup lang="ts">
const items = ref([
  "Backlog",
  "Todo",
  "In Progress",
  "Done"
])
const value = ref("Backlog")
</script>

<template>
  <USelect v-model="value" loading :trailing="false" :items="items" class="w-48" />
</template>
```

### Ícone de carregamento

Use a prop `loading-icon` para personalizar o ícone de carregamento. O padrão é `i-lucide-loader-circle`.

```vue
<script setup lang="ts">
const items = ref([
  "Backlog",
  "Todo",
  "In Progress",
  "Done"
])
const value = ref("Backlog")
</script>

<template>
  <USelect v-model="value" loading loading-icon="i-lucide-loader" :items="items" class="w-48" />
</template>
```

**Nuxt:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/nuxt#theme
>
> Você pode personalizar esse ícone globalmente no seu `app.config.ts` na chave `ui.icons.loading`.

**Vue:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/vue#theme
>
> Você pode personalizar esse ícone globalmente no seu `vite.config.ts` na chave `ui.icons.loading`.

### Desabilitado

Use a prop `disabled` para desabilitar o Select.

```vue
<script setup lang="ts">
const items = ref([
  "Backlog",
  "Todo",
  "In Progress",
  "Done"
])
</script>

<template>
  <USelect disabled placeholder="Select status" :items="items" class="w-48" />
</template>
```

## Exemplos

### Com tipo de itens

Você pode usar a propriedade `type` com `separator` para exibir um separador entre os itens ou `label` para exibir um rótulo.

```vue
<script setup lang="ts">
import type { SelectItem } from '@nitro/ui'

const items = ref<SelectItem[]>([
  {
    type: "label",
    label: "Fruits"
  },
  "Apple",
  "Banana",
  "Blueberry",
  "Grapes",
  "Pineapple",
  {
    type: "separator"
  },
  {
    type: "label",
    label: "Vegetables"
  },
  "Aubergine",
  "Broccoli",
  "Carrot",
  "Courgette",
  "Leek"
])
const value = ref("Apple")
</script>

<template>
  <USelect v-model="value" :items="items" class="w-48" />
</template>
```

### Com ícone nos itens

Você pode usar a propriedade `icon` para exibir um [Icon](https://ui.nitro.news/docs/components/icon) dentro dos itens.

::component-example{collapse name="select-items-icon-example"}
::

> \[!NOTE]
>
> Neste exemplo, o ícone é calculado a partir da propriedade `value` do item selecionado.

> \[!TIP]
>
> Você também pode usar o slot `#leading` para exibir o ícone selecionado.

### Com avatar nos itens

Você pode usar a propriedade `avatar` para exibir um [Avatar](https://ui.nitro.news/docs/components/avatar) dentro dos itens.

::component-example{collapse name="select-items-avatar-example"}
::

> \[!NOTE]
>
> Neste exemplo, o avatar é calculado a partir da propriedade `value` do item selecionado.

> \[!TIP]
>
> Você também pode usar o slot `#leading` para exibir o avatar selecionado.

### Com chip nos itens

Você pode usar a propriedade `chip` para exibir um [Chip](https://ui.nitro.news/docs/components/chip) dentro dos itens.

::component-example{collapse name="select-items-chip-example"}
::

> \[!NOTE]
>
> Neste exemplo, o slot `#leading` é usado para exibir o chip selecionado.

### Controlar o estado de abertura

Você pode controlar o estado de abertura usando a prop `default-open` ou a diretiva `v-model:open`.

:component-example{name="select-open-example"}

> \[!NOTE]
>
> Neste exemplo, aproveitando o [`defineShortcuts`](https://ui.nitro.news/docs/composables/define-shortcuts), você pode abrir e fechar o Select pressionando :kbd{value="O"}.

### Com ícone rotativo

Aqui está um exemplo com um ícone rotativo que indica o estado de abertura do Select.

:component-example{name="select-icon-example"}

### Com itens buscados

Você pode buscar itens de uma API e usá-los no Select.

::component-example{collapse name="select-fetch-example"}
::

> \[!NOTE]
>
> Este exemplo usa `useLazyFetch` com `immediate: false` para buscar os dados apenas quando o menu abre, evitando chamadas de API desnecessárias no carregamento da página.

### Com rolagem infinita `4.4+`

Você pode usar o composable [`useInfiniteScroll`](https://vueuse.org/core/useInfiniteScroll/){rel="&#x22;nofollow&#x22;"} para carregar mais dados conforme o usuário rola.

::component-example
---
collapse: true
highlights:
  - 41
  - 51
overflowHidden: true
prettier: true
name: select-infinite-scroll-example
---
::

> \[!NOTE]
>
> Este exemplo usa `useLazyFetch` com `immediate: false`, então os dados só são carregados conforme o usuário rola.

### Com largura total do conteúdo

Você pode expandir o conteúdo até a largura total dos seus itens adicionando a classe `min-w-fit` no slot `ui.content`.

::component-example{collapse name="select-content-width-example"}
::

> \[!TIP]
>
> Você também pode alterar a largura do conteúdo globalmente no seu `app.config.ts`:
>
> ```text
> export default defineAppConfig({
>   ui: {
>     select: {
>       slots: {
>         content: 'min-w-fit'
>       }
>     }
>   }
> })
> ```

## API

### Props

```ts
/**
 * Props for the Select component
 */
interface SelectProps {
  id?: string | undefined;
  /**
   * The placeholder text when the select is empty.
   */
  placeholder?: string | undefined;
  color?: "primary" | "secondary" | "accent" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
  variant?: "outline" | "soft" | "subtle" | "ghost" | "none" | undefined;
  size?: "sm" | "md" | "xs" | "lg" | "xl" | undefined;
  /**
   * The icon displayed to open the menu.
   */
  trailingIcon?: any;
  /**
   * The icon displayed when an item is selected.
   */
  selectedIcon?: any;
  /**
   * The content of the menu.
   */
  content?: (Omit<SelectContentProps, "as" | "asChild" | "forceMount"> & Partial<EmitsToProps<SelectContentImplEmits>>) | undefined;
  /**
   * Display an arrow alongside the menu.
   * `{ rounded: true }`{lang="ts-type"}
   */
  arrow?: boolean | Omit<SelectArrowProps, "as" | "asChild"> | undefined;
  /**
   * Render the menu in a portal.
   * @default "true"
   */
  portal?: string | boolean | HTMLElement | undefined;
  /**
   * When `items` is an array of objects, select the field to use as the value.
   * @default "\"value\" as never"
   */
  valueKey?: VK | undefined;
  /**
   * When `items` is an array of objects, select the field to use as the label.
   * @default "\"label\""
   */
  labelKey?: GetItemKeys<T> | undefined;
  /**
   * When `items` is an array of objects, select the field to use as the description.
   * @default "\"description\""
   */
  descriptionKey?: GetItemKeys<T> | undefined;
  items?: T | undefined;
  /**
   * The value of the Select when initially rendered. Use when you do not need to control the state of the Select.
   */
  defaultValue?: _Number<_Optional<_Nullable<GetModelValue<T, VK, M, ExcludeItem>, Mod>, Mod>, Mod> | undefined;
  /**
   * The controlled value of the Select. Can be bind as `v-model`.
   */
  modelValue?: _Number<_Optional<_Nullable<GetModelValue<T, VK, M, ExcludeItem>, Mod>, Mod>, Mod> | undefined;
  modelModifiers?: Mod | undefined;
  /**
   * Whether multiple options can be selected or not.
   */
  multiple?: M | undefined;
  /**
   * Highlight the ring color like a focus state.
   */
  highlight?: boolean | undefined;
  autofocus?: boolean | undefined;
  /**
   * @default "0"
   */
  autofocusDelay?: number | undefined;
  ui?: { base?: SlotClass; leading?: SlotClass; leadingIcon?: SlotClass; leadingAvatar?: SlotClass; leadingAvatarSize?: SlotClass; trailing?: SlotClass; trailingIcon?: SlotClass; value?: SlotClass; placeholder?: SlotClass; arrow?: SlotClass; content?: SlotClass; viewport?: SlotClass; group?: SlotClass; empty?: SlotClass; label?: SlotClass; separator?: SlotClass; item?: SlotClass; itemLeadingIcon?: SlotClass; itemLeadingAvatar?: SlotClass; itemLeadingAvatarSize?: SlotClass; itemLeadingChip?: SlotClass; itemLeadingChipSize?: SlotClass; itemTrailing?: SlotClass; itemTrailingIcon?: SlotClass; itemWrapper?: SlotClass; itemLabel?: SlotClass; itemDescription?: SlotClass; } | undefined;
  /**
   * When `true`, prevents the user from interacting with Select
   */
  disabled?: boolean | undefined;
  /**
   * The controlled open state of the Select. Can be bind as `v-model:open`.
   */
  open?: boolean | undefined;
  /**
   * The open state of the select when it is initially rendered. Use when you do not need to control its open state.
   */
  defaultOpen?: boolean | undefined;
  /**
   * The value of the hidden native select option when the model value is nullish.
   */
  nullableValue?: string | undefined;
  /**
   * Native html input `autocomplete` attribute.
   */
  autocomplete?: string | undefined;
  /**
   * The name of the field. Submitted with its owning form as part of a name/value pair.
   */
  name?: string | undefined;
  /**
   * When `true`, indicates that the user must set the value before the owning form can be submitted.
   */
  required?: boolean | undefined;
  /**
   * Display an icon based on the `leading` and `trailing` props.
   */
  icon?: any;
  /**
   * Display an avatar on the left side.
   */
  avatar?: AvatarProps | undefined;
  /**
   * When `true`, the icon will be displayed on the left side.
   */
  leading?: boolean | undefined;
  /**
   * Display an icon on the left side.
   */
  leadingIcon?: any;
  /**
   * When `true`, the icon will be displayed on the right side.
   */
  trailing?: boolean | undefined;
  /**
   * When `true`, the loading icon will be displayed.
   */
  loading?: boolean | undefined;
  /**
   * The icon when the `loading` prop is `true`.
   */
  loadingIcon?: any;
  form?: string | undefined;
  formaction?: string | undefined;
  formenctype?: string | undefined;
  formmethod?: string | undefined;
  formnovalidate?: Booleanish | undefined;
  formtarget?: string | undefined;
}
```

> \[!NOTE]
> See: https\://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attributes
>
> Este componente também suporta todos os atributos HTML nativos de `<button>`.

### Slots

```ts
/**
 * Slots for the Select component
 */
interface SelectSlots {
  leading(): any;
  default(): any;
  trailing(): any;
  item(): any;
  item-leading(): any;
  item-label(): any;
  item-description(): any;
  item-trailing(): any;
  content-top(): any;
  content-bottom(): any;
}
```

### Emits

```ts
/**
 * Emitted events for the Select component
 */
interface SelectEmits {
  update:modelValue: (payload: [value: _Number<_Optional<_Nullable<GetModelValue<T, VK, M, ExcludeItem>, Mod>, Mod>, Mod>]) => void;
  update:open: (payload: [value: boolean]) => void;
  change: (payload: [event: Event]) => void;
  blur: (payload: [event: FocusEvent]) => void;
  focus: (payload: [event: FocusEvent]) => void;
}
```

### Expose

Ao acessar o componente por meio de um template ref, você pode usar o seguinte:

| Name                                                                                                                              | Type                                                                                                                                                |
| --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `triggerRef`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"}  | `Ref<HTMLButtonElement | null>`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} |
| `viewportRef`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | `Ref<HTMLDivElement | null>`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"}    |

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    select: {
      slots: {
        base: [
          'relative group rounded-md inline-flex items-center disabled:cursor-not-allowed disabled:opacity-75',
          'transition-colors'
        ],
        leading: 'absolute inset-y-0 start-0 flex items-center',
        leadingIcon: 'shrink-0 text-dimmed',
        leadingAvatar: 'shrink-0',
        leadingAvatarSize: '',
        trailing: 'absolute inset-y-0 end-0 flex items-center',
        trailingIcon: 'shrink-0 text-dimmed',
        value: 'truncate pointer-events-none',
        placeholder: 'truncate text-dimmed',
        arrow: 'fill-bg stroke-default',
        content: 'max-h-[min(15rem,var(--reka-select-content-available-height,15rem))] w-(--reka-select-trigger-width) bg-default shadow-lg rounded-md ring ring-default overflow-hidden origin-(--reka-select-content-transform-origin) pointer-events-auto flex flex-col',
        viewport: 'relative divide-y divide-default scroll-py-1 overflow-y-auto flex-1',
        group: 'p-1 isolate',
        empty: 'text-center text-muted',
        label: 'font-semibold text-highlighted',
        separator: '-mx-1 my-1 h-px bg-border',
        item: [
          'group relative w-full flex items-start select-none outline-none before:absolute before:z-[-1] before:inset-px before:rounded-md data-disabled:cursor-not-allowed data-disabled:opacity-75 text-default data-highlighted:not-data-disabled:text-highlighted data-highlighted:not-data-disabled:before:bg-elevated/50',
          'transition-colors before:transition-colors'
        ],
        itemLeadingIcon: [
          'shrink-0 text-dimmed group-data-highlighted:not-group-data-disabled:text-default',
          'transition-colors'
        ],
        itemLeadingAvatar: 'shrink-0',
        itemLeadingAvatarSize: '',
        itemLeadingChip: 'shrink-0',
        itemLeadingChipSize: '',
        itemTrailing: 'ms-auto inline-flex gap-1.5 items-center',
        itemTrailingIcon: 'shrink-0',
        itemWrapper: 'flex-1 flex flex-col min-w-0',
        itemLabel: 'truncate',
        itemDescription: 'truncate text-muted'
      },
      variants: {
        fieldGroup: {
          horizontal: 'not-only:first:rounded-e-none not-only:last:rounded-s-none not-last:not-first:rounded-none focus-visible:z-[1]',
          vertical: 'not-only:first:rounded-b-none not-only:last:rounded-t-none not-last:not-first:rounded-none focus-visible:z-[1]'
        },
        size: {
          xs: {
            base: 'px-2 py-1 text-xs gap-1',
            leading: 'ps-2',
            trailing: 'pe-2',
            leadingIcon: 'size-4',
            leadingAvatarSize: '3xs',
            trailingIcon: 'size-4',
            label: 'p-1 text-[10px]/3 gap-1',
            item: 'p-1 text-xs gap-1',
            itemLeadingIcon: 'size-4',
            itemLeadingAvatarSize: '3xs',
            itemLeadingChip: 'size-4',
            itemLeadingChipSize: 'sm',
            itemTrailingIcon: 'size-4',
            empty: 'p-2 text-xs'
          },
          sm: {
            base: 'px-2.5 py-1.5 text-xs gap-1.5',
            leading: 'ps-2.5',
            trailing: 'pe-2.5',
            leadingIcon: 'size-4',
            leadingAvatarSize: '3xs',
            trailingIcon: 'size-4',
            label: 'p-1.5 text-[10px]/3 gap-1.5',
            item: 'p-1.5 text-xs gap-1.5',
            itemLeadingIcon: 'size-4',
            itemLeadingAvatarSize: '3xs',
            itemLeadingChip: 'size-4',
            itemLeadingChipSize: 'sm',
            itemTrailingIcon: 'size-4',
            empty: 'p-2.5 text-xs'
          },
          md: {
            base: 'px-2.5 py-1.5 text-sm gap-1.5',
            leading: 'ps-2.5',
            trailing: 'pe-2.5',
            leadingIcon: 'size-5',
            leadingAvatarSize: '2xs',
            trailingIcon: 'size-5',
            label: 'p-1.5 text-xs gap-1.5',
            item: 'p-1.5 text-sm gap-1.5',
            itemLeadingIcon: 'size-5',
            itemLeadingAvatarSize: '2xs',
            itemLeadingChip: 'size-5',
            itemLeadingChipSize: 'md',
            itemTrailingIcon: 'size-5',
            empty: 'p-2.5 text-sm'
          },
          lg: {
            base: 'px-3 py-2 text-sm gap-2',
            leading: 'ps-3',
            trailing: 'pe-3',
            leadingIcon: 'size-5',
            leadingAvatarSize: '2xs',
            trailingIcon: 'size-5',
            label: 'p-2 text-xs gap-2',
            item: 'p-2 text-sm gap-2',
            itemLeadingIcon: 'size-5',
            itemLeadingAvatarSize: '2xs',
            itemLeadingChip: 'size-5',
            itemLeadingChipSize: 'md',
            itemTrailingIcon: 'size-5',
            empty: 'p-3 text-sm'
          },
          xl: {
            base: 'px-3 py-2 text-base gap-2',
            leading: 'ps-3',
            trailing: 'pe-3',
            leadingIcon: 'size-6',
            leadingAvatarSize: 'xs',
            trailingIcon: 'size-6',
            label: 'p-2 text-sm gap-2',
            item: 'p-2 text-base gap-2',
            itemLeadingIcon: 'size-6',
            itemLeadingAvatarSize: 'xs',
            itemLeadingChip: 'size-6',
            itemLeadingChipSize: 'lg',
            itemTrailingIcon: 'size-6',
            empty: 'p-3 text-base'
          }
        },
        variant: {
          outline: 'text-highlighted bg-default ring ring-inset ring-accented hover:bg-elevated disabled:bg-default',
          soft: 'text-highlighted bg-elevated/50 hover:bg-elevated focus:bg-elevated disabled:bg-elevated/50',
          subtle: 'text-highlighted bg-elevated ring ring-inset ring-accented hover:bg-accented/75 disabled:bg-elevated',
          ghost: 'text-highlighted bg-transparent hover:bg-elevated focus:bg-elevated disabled:bg-transparent dark:disabled:bg-transparent',
          none: 'text-highlighted bg-transparent focus:outline-none'
        },
        color: {
          primary: '',
          secondary: '',
          accent: '',
          success: '',
          info: '',
          warning: '',
          error: '',
          neutral: ''
        },
        leading: {
          true: ''
        },
        trailing: {
          true: ''
        },
        loading: {
          true: ''
        },
        highlight: {
          true: ''
        },
        fixed: {
          false: ''
        },
        type: {
          file: 'file:me-1.5 file:font-medium file:text-muted file:outline-none'
        },
        position: {
          popper: {
            content: 'data-[state=open]:animate-[scale-in_100ms_ease-out] data-[state=closed]:animate-[scale-out_100ms_ease-in]'
          },
          'item-aligned': {
            content: ''
          }
        },
        multiple: {
          true: ''
        }
      },
      compoundVariants: [
        {
          color: 'primary',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-primary/25 focus-visible:outline-3 focus-visible:ring-primary'
        },
        {
          color: 'secondary',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-secondary/25 focus-visible:outline-3 focus-visible:ring-secondary'
        },
        {
          color: 'accent',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-accent/25 focus-visible:outline-3 focus-visible:ring-accent'
        },
        {
          color: 'success',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-success/25 focus-visible:outline-3 focus-visible:ring-success'
        },
        {
          color: 'info',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-info/25 focus-visible:outline-3 focus-visible:ring-info'
        },
        {
          color: 'warning',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-warning/25 focus-visible:outline-3 focus-visible:ring-warning'
        },
        {
          color: 'error',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-error/25 focus-visible:outline-3 focus-visible:ring-error'
        },
        {
          color: 'primary',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-primary/25 focus-visible:outline-3'
        },
        {
          color: 'secondary',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-secondary/25 focus-visible:outline-3'
        },
        {
          color: 'accent',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-accent/25 focus-visible:outline-3'
        },
        {
          color: 'success',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-success/25 focus-visible:outline-3'
        },
        {
          color: 'info',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-info/25 focus-visible:outline-3'
        },
        {
          color: 'warning',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-warning/25 focus-visible:outline-3'
        },
        {
          color: 'error',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-error/25 focus-visible:outline-3'
        },
        {
          color: 'primary',
          highlight: true,
          class: 'ring ring-inset ring-primary'
        },
        {
          color: 'secondary',
          highlight: true,
          class: 'ring ring-inset ring-secondary'
        },
        {
          color: 'accent',
          highlight: true,
          class: 'ring ring-inset ring-accent'
        },
        {
          color: 'success',
          highlight: true,
          class: 'ring ring-inset ring-success'
        },
        {
          color: 'info',
          highlight: true,
          class: 'ring ring-inset ring-info'
        },
        {
          color: 'warning',
          highlight: true,
          class: 'ring ring-inset ring-warning'
        },
        {
          color: 'error',
          highlight: true,
          class: 'ring ring-inset ring-error'
        },
        {
          color: 'neutral',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-inverted/25 focus-visible:outline-3 focus-visible:ring-inverted'
        },
        {
          color: 'neutral',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-inverted/25 focus-visible:outline-3'
        },
        {
          color: 'neutral',
          highlight: true,
          class: 'ring ring-inset ring-inverted'
        },
        {
          leading: true,
          size: 'xs',
          class: 'ps-7'
        },
        {
          leading: true,
          size: 'sm',
          class: 'ps-8'
        },
        {
          leading: true,
          size: 'md',
          class: 'ps-9'
        },
        {
          leading: true,
          size: 'lg',
          class: 'ps-10'
        },
        {
          leading: true,
          size: 'xl',
          class: 'ps-11'
        },
        {
          trailing: true,
          size: 'xs',
          class: 'pe-7'
        },
        {
          trailing: true,
          size: 'sm',
          class: 'pe-8'
        },
        {
          trailing: true,
          size: 'md',
          class: 'pe-9'
        },
        {
          trailing: true,
          size: 'lg',
          class: 'pe-10'
        },
        {
          trailing: true,
          size: 'xl',
          class: 'pe-11'
        },
        {
          loading: true,
          leading: true,
          class: {
            leadingIcon: 'animate-spin'
          }
        },
        {
          loading: true,
          leading: false,
          trailing: true,
          class: {
            trailingIcon: 'animate-spin'
          }
        },
        {
          fixed: false,
          size: 'xs',
          class: 'md:text-xs'
        },
        {
          fixed: false,
          size: 'sm',
          class: 'md:text-xs'
        },
        {
          fixed: false,
          size: 'md',
          class: 'md:text-sm'
        },
        {
          fixed: false,
          size: 'lg',
          class: 'md:text-sm'
        }
      ],
      defaultVariants: {
        size: 'md',
        color: 'accent',
        variant: 'outline',
        position: 'popper'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/Select.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/select.ts).


# SelectMenu

## Uso

Use a diretiva `v-model` para controlar o valor do SelectMenu ou a prop `default-value` para definir o valor inicial quando você não precisa controlar o estado.

```vue
<script setup lang="ts">
const items = ref([
  "Backlog",
  "Todo",
  "In Progress",
  "Done"
])
const value = ref("Backlog")
</script>

<template>
  <USelectMenu v-model="value" :items="items" />
</template>
```

> \[!TIP]
>
> Use este no lugar de um [`Select`](https://ui.nitro.news/docs/components/select) para aproveitar o componente [`Combobox`](https://reka-ui.com/docs/components/combobox){rel="&#x22;nofollow&#x22;"} do Reka UI, que oferece recursos de busca e seleção múltipla.

> \[!NOTE]
>
> Este componente é semelhante ao [`InputMenu`](https://ui.nitro.news/docs/components/input-menu), mas usa um Select em vez de um Input, com a busca dentro do menu.

### Itens

Use a prop `items` como um array de strings, números ou booleanos:

```vue
<script setup lang="ts">
const items = ref([
  "Backlog",
  "Todo",
  "In Progress",
  "Done"
])
const value = ref("Backlog")
</script>

<template>
  <USelectMenu v-model="value" :items="items" class="w-48" />
</template>
```

Você também pode passar um array de objetos com as seguintes propriedades:

- `label?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- [`type?: "label" | "separator" | "item"`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}](https://ui.nitro.news/#with-items-type)
- [`icon?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}](https://ui.nitro.news/#with-icons-in-items)
- [`avatar?: AvatarProps`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}](https://ui.nitro.news/#with-avatar-in-items)
- [`chip?: ChipProps`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}](https://ui.nitro.news/#with-chip-in-items)
- `disabled?: boolean`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `onSelect?: (e: Event) => void`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `class?: any`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `ui?: { label?: ClassNameValue, separator?: ClassNameValue, item?: ClassNameValue, itemLeadingIcon?: ClassNameValue, itemLeadingAvatarSize?: ClassNameValue, itemLeadingAvatar?: ClassNameValue, itemLeadingChipSize?: ClassNameValue, itemLeadingChip?: ClassNameValue, itemLabel?: ClassNameValue, itemTrailing?: ClassNameValue, itemTrailingIcon?: ClassNameValue }`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

```vue
<script setup lang="ts">
import type { SelectMenuItem } from '@nitro/ui'

const items = ref<SelectMenuItem[]>([
  {
    label: "Backlog"
  },
  {
    label: "Todo"
  },
  {
    label: "In Progress"
  },
  {
    label: "Done"
  }
])
const value = ref({
  label: "Todo"
})
</script>

<template>
  <USelectMenu v-model="value" :items="items" class="w-48" />
</template>
```

> \[!CAUTION]
>
> Diferentemente do componente [`Select`](https://ui.nitro.news/docs/components/select), o SelectMenu espera, por padrão, que o objeto inteiro seja passado para a diretiva `v-model` ou para a prop `default-value`.

Você também pode passar um array de arrays para a prop `items` para exibir grupos separados de itens.

```vue
<script setup lang="ts">
const items = ref([
  [
    "Apple",
    "Banana",
    "Blueberry",
    "Grapes",
    "Pineapple"
  ],
  [
    "Aubergine",
    "Broccoli",
    "Carrot",
    "Courgette",
    "Leek"
  ]
])
const value = ref("Apple")
</script>

<template>
  <USelectMenu v-model="value" :items="items" class="w-48" />
</template>
```

### Chave de valor

Você pode optar por vincular uma única propriedade do objeto em vez do objeto inteiro usando a prop `value-key`. O padrão é `undefined`.

```vue
<script setup lang="ts">
import type { SelectMenuItem } from '@nitro/ui'

const items = ref<SelectMenuItem[]>([
  {
    label: "Backlog",
    id: "backlog"
  },
  {
    label: "Todo",
    id: "todo"
  },
  {
    label: "In Progress",
    id: "in_progress"
  },
  {
    label: "Done",
    id: "done"
  }
])
const value = ref("todo")
</script>

<template>
  <USelectMenu v-model="value" value-key="id" :items="items" class="w-48" />
</template>
```

> \[!TIP]
>
> Use a prop `by` para comparar objetos por um campo em vez de por referência quando o `model-value` for um objeto.

### Múltiplo

Use a prop `multiple` para permitir múltiplas seleções; os itens selecionados serão separados por vírgula no gatilho.

```vue
<script setup lang="ts">
const items = ref([
  "Backlog",
  "Todo",
  "In Progress",
  "Done"
])
const value = ref([
  "Backlog",
  "Todo"
])
</script>

<template>
  <USelectMenu v-model="value" multiple :items="items" class="w-48" />
</template>
```

> \[!CAUTION]
>
> Certifique-se de passar um array para a prop `default-value` ou para a diretiva `v-model`.

### Placeholder

Use a prop `placeholder` para definir um texto de placeholder.

```vue
<script setup lang="ts">
const items = ref([
  "Backlog",
  "Todo",
  "In Progress",
  "Done"
])
</script>

<template>
  <USelectMenu placeholder="Select status" :items="items" class="w-48" />
</template>
```

### Campo de busca

Use a prop `search-input` para personalizar ou ocultar o campo de busca (com o valor `false`).

Você pode passar qualquer propriedade do componente [Input](https://ui.nitro.news/docs/components/input) para personalizá-lo.

```vue
<script setup lang="ts">
import type { SelectMenuItem } from '@nitro/ui'

const items = ref<SelectMenuItem[]>([
  {
    label: "Backlog",
    icon: "i-lucide-circle-help"
  },
  {
    label: "Todo",
    icon: "i-lucide-circle-plus"
  },
  {
    label: "In Progress",
    icon: "i-lucide-circle-arrow-up"
  },
  {
    label: "Done",
    icon: "i-lucide-circle-check"
  }
])
const value = ref({
  label: "Backlog",
  icon: "i-lucide-circle-help"
})
</script>

<template>
  <USelectMenu v-model="value" :search-input="{
  placeholder: 'Filter...',
  icon: 'i-lucide-search'
}" :items="items" class="w-48" />
</template>
```

> \[!TIP]
>
> Você pode definir a prop `search-input` como `false` para ocultar o campo de busca.

### Conteúdo

Use a prop `content` para controlar como o conteúdo do SelectMenu é renderizado, como seu `align` ou `side`, por exemplo.

```vue
<script setup lang="ts">
const items = ref([
  "Backlog",
  "Todo",
  "In Progress",
  "Done"
])
const value = ref("Backlog")
</script>

<template>
  <USelectMenu v-model="value" :content="{
  align: 'center',
  side: 'bottom',
  sideOffset: 8
}" :items="items" class="w-48" />
</template>
```

### Seta

Use a prop `arrow` para exibir uma seta no SelectMenu.

```vue
<script setup lang="ts">
const items = ref([
  "Backlog",
  "Todo",
  "In Progress",
  "Done"
])
const value = ref("Backlog")
</script>

<template>
  <USelectMenu v-model="value" arrow :items="items" class="w-48" />
</template>
```

### Cor

Use a prop `color` para alterar a cor do ring quando o SelectMenu está em foco.

```vue
<script setup lang="ts">
const items = ref([
  "Backlog",
  "Todo",
  "In Progress",
  "Done"
])
const value = ref("Backlog")
</script>

<template>
  <USelectMenu v-model="value" color="neutral" highlight :items="items" class="w-48" />
</template>
```

> \[!NOTE]
>
> A prop `highlight` é usada aqui para mostrar o estado de foco. Ela é usada internamente quando ocorre um erro de validação.

### Variante

Use a prop `variant` para alterar a variante do SelectMenu.

```vue
<script setup lang="ts">
const items = ref([
  "Backlog",
  "Todo",
  "In Progress",
  "Done"
])
const value = ref("Backlog")
</script>

<template>
  <USelectMenu v-model="value" color="neutral" variant="subtle" :highlight="false" :items="items" class="w-48" />
</template>
```

### Tamanho

Use a prop `size` para alterar o tamanho do SelectMenu.

```vue
<script setup lang="ts">
const items = ref([
  "Backlog",
  "Todo",
  "In Progress",
  "Done"
])
const value = ref("Backlog")
</script>

<template>
  <USelectMenu v-model="value" size="xl" :items="items" class="w-48" />
</template>
```

### Ícone

Use a prop `icon` para exibir um [Icon](https://ui.nitro.news/docs/components/icon) dentro do SelectMenu.

```vue
<script setup lang="ts">
const items = ref([
  "Backlog",
  "Todo",
  "In Progress",
  "Done"
])
const value = ref("Backlog")
</script>

<template>
  <USelectMenu v-model="value" icon="i-lucide-search" size="md" :items="items" class="w-48" />
</template>
```

### Ícone à direita

Use a prop `trailing-icon` para personalizar o [Icon](https://ui.nitro.news/docs/components/icon) à direita. O padrão é `i-lucide-chevron-down`.

```vue
<script setup lang="ts">
const items = ref([
  "Backlog",
  "Todo",
  "In Progress",
  "Done"
])
const value = ref("Backlog")
</script>

<template>
  <USelectMenu v-model="value" trailing-icon="i-lucide-arrow-down" size="md" :items="items" class="w-48" />
</template>
```

**Nuxt:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/nuxt#theme
>
> Você pode personalizar esse ícone globalmente no seu `app.config.ts` na chave `ui.icons.chevronDown`.

**Vue:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/vue#theme
>
> Você pode personalizar esse ícone globalmente no seu `vite.config.ts` na chave `ui.icons.chevronDown`.

### Ícone de selecionado

Use a prop `selected-icon` para personalizar o ícone quando um item é selecionado. O padrão é `i-lucide-check`.

```vue
<script setup lang="ts">
const items = ref([
  "Backlog",
  "Todo",
  "In Progress",
  "Done"
])
const value = ref("Backlog")
</script>

<template>
  <USelectMenu v-model="value" selected-icon="i-lucide-flame" size="md" :items="items" class="w-48" />
</template>
```

**Nuxt:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/nuxt#theme
>
> Você pode personalizar esse ícone globalmente no seu `app.config.ts` na chave `ui.icons.check`.

**Vue:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/vue#theme
>
> Você pode personalizar esse ícone globalmente no seu `vite.config.ts` na chave `ui.icons.check`.

### Limpar `4.4+`

Use a prop `clear` para exibir um botão de limpar quando um valor está selecionado.

```vue
<script setup lang="ts">
const items = ref([
  "Backlog",
  "Todo",
  "In Progress",
  "Done"
])
const value = ref("Backlog")
</script>

<template>
  <USelectMenu v-model="value" clear :items="items" class="w-48" />
</template>
```

### Ícone de limpar `4.4+`

Use a prop `clear-icon` para personalizar o [Icon](https://ui.nitro.news/docs/components/icon) do botão de limpar. O padrão é `i-lucide-x`.

```vue
<script setup lang="ts">
const items = ref([
  "Backlog",
  "Todo",
  "In Progress",
  "Done"
])
const value = ref("Backlog")
</script>

<template>
  <USelectMenu v-model="value" clear clear-icon="i-lucide-trash" :items="items" class="w-48" />
</template>
```

**Nuxt:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/nuxt#theme
>
> Você pode personalizar esse ícone globalmente no seu `app.config.ts` na chave `ui.icons.close`.

**Vue:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/vue#theme
>
> Você pode personalizar esse ícone globalmente no seu `vite.config.ts` na chave `ui.icons.close`.

### Avatar

Use a prop `avatar` para exibir um [Avatar](https://ui.nitro.news/docs/components/avatar) dentro do SelectMenu.

```vue
<script setup lang="ts">
const items = ref([
  "Nuxt",
  "NuxtHub",
  "NuxtLabs",
  "Nuxt Modules",
  "Nuxt Community"
])
const value = ref("Nuxt")
</script>

<template>
  <USelectMenu v-model="value" :avatar="{
  src: 'https://github.com/nuxt.png',
  loading: 'lazy'
}" :items="items" class="w-48" />
</template>
```

### Carregando

Use a prop `loading` para exibir um ícone de carregamento no SelectMenu.

```vue
<script setup lang="ts">
const items = ref([
  "Backlog",
  "Todo",
  "In Progress",
  "Done"
])
const value = ref("Backlog")
</script>

<template>
  <USelectMenu v-model="value" loading :trailing="false" :items="items" class="w-48" />
</template>
```

### Ícone de carregamento

Use a prop `loading-icon` para personalizar o ícone de carregamento. O padrão é `i-lucide-loader-circle`.

```vue
<script setup lang="ts">
const items = ref([
  "Backlog",
  "Todo",
  "In Progress",
  "Done"
])
const value = ref("Backlog")
</script>

<template>
  <USelectMenu v-model="value" loading loading-icon="i-lucide-loader" :items="items" class="w-48" />
</template>
```

**Nuxt:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/nuxt#theme
>
> Você pode personalizar esse ícone globalmente no seu `app.config.ts` na chave `ui.icons.loading`.

**Vue:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/vue#theme
>
> Você pode personalizar esse ícone globalmente no seu `vite.config.ts` na chave `ui.icons.loading`.

### Desabilitado

Use a prop `disabled` para desabilitar o SelectMenu.

```vue
<script setup lang="ts">
const items = ref([
  "Backlog",
  "Todo",
  "In Progress",
  "Done"
])
</script>

<template>
  <USelectMenu disabled placeholder="Select status" :items="items" class="w-48" />
</template>
```

## Exemplos

### Com tipo de itens

Você pode usar a propriedade `type` com `separator` para exibir um separador entre os itens ou `label` para exibir um rótulo.

```vue
<script setup lang="ts">
import type { SelectMenuItem } from '@nitro/ui'

const items = ref<SelectMenuItem[]>([
  {
    type: "label",
    label: "Fruits"
  },
  "Apple",
  "Banana",
  "Blueberry",
  "Grapes",
  "Pineapple",
  {
    type: "separator"
  },
  {
    type: "label",
    label: "Vegetables"
  },
  "Aubergine",
  "Broccoli",
  "Carrot",
  "Courgette",
  "Leek"
])
const value = ref("Apple")
</script>

<template>
  <USelectMenu v-model="value" :items="items" class="w-48" />
</template>
```

### Com ícone nos itens

Você pode usar a propriedade `icon` para exibir um [Icon](https://ui.nitro.news/docs/components/icon) dentro dos itens.

::component-example{collapse name="select-menu-items-icon-example"}
::

> \[!TIP]
>
> Você também pode usar o slot `#leading` para exibir o ícone selecionado.

### Com avatar nos itens

Você pode usar a propriedade `avatar` para exibir um [Avatar](https://ui.nitro.news/docs/components/avatar) dentro dos itens.

::component-example{collapse name="select-menu-items-avatar-example"}
::

> \[!TIP]
>
> Você também pode usar o slot `#leading` para exibir o avatar selecionado.

### Com chip nos itens

Você pode usar a propriedade `chip` para exibir um [Chip](https://ui.nitro.news/docs/components/chip) dentro dos itens.

::component-example{collapse name="select-menu-items-chip-example"}
::

> \[!NOTE]
>
> Neste exemplo, o slot `#leading` é usado para exibir o chip selecionado.

### Controlar o estado de abertura

Você pode controlar o estado de abertura usando a prop `default-open` ou a diretiva `v-model:open`.

:component-example{name="select-menu-open-example"}

> \[!NOTE]
>
> Neste exemplo, aproveitando o [`defineShortcuts`](https://ui.nitro.news/docs/composables/define-shortcuts), você pode abrir e fechar o SelectMenu pressionando :kbd{value="O"}.

### Controlar o termo de busca

Use a diretiva `v-model:search-term` para controlar o termo de busca.

:component-example{name="select-menu-search-term-example"}

### Com ícone rotativo

Aqui está um exemplo com um ícone rotativo que indica o estado de abertura do SelectMenu.

:component-example{name="select-menu-icon-example"}

### Com criação de item

Use a prop `create-item` para permitir que os usuários adicionem valores personalizados que não estão nas opções predefinidas.

::component-example{collapse name="select-menu-create-item-example"}
::

> \[!NOTE]
>
> A opção de criar aparece quando nenhuma correspondência é encontrada, por padrão. Defina como `always` para exibi-la mesmo quando houver valores semelhantes.

> \[!TIP]
> See: #emits
>
> Use o evento `@create` para tratar a criação do item. Você receberá o evento e o item como argumentos.

### Com itens buscados

Você pode buscar itens de uma API e usá-los no SelectMenu.

::component-example{collapse name="select-menu-fetch-example"}
::

> \[!NOTE]
>
> Este exemplo usa `useLazyFetch` com `immediate: false` para buscar os dados apenas quando o menu abre, evitando chamadas de API desnecessárias no carregamento da página.

### Com filtro ignorado

Defina a prop `ignore-filter` como `true` para desabilitar a busca interna e usar sua própria lógica de busca.

::component-example{collapse name="select-menu-ignore-filter-example"}
::

> \[!NOTE]
>
> Este exemplo usa [`refDebounced`](https://vueuse.org/shared/refDebounced/#refdebounced){rel="&#x22;nofollow&#x22;"} para aplicar debounce nas chamadas de API. A busca é adiada com `immediate: false`, então nenhuma requisição é feita até o menu abrir.

### Com campos de filtro

Use a prop `filter-fields` com um array de campos para filtrar. O padrão é `[labelKey]`.

::component-example{collapse name="select-menu-filter-fields-example"}
::

> \[!NOTE]
>
> Este exemplo usa `useLazyFetch` com `immediate: false` para buscar os dados apenas quando o menu abre, evitando chamadas de API desnecessárias no carregamento da página.

### Com virtualização `4.1+`

Use a prop `virtualize` para habilitar a virtualização em listas grandes, como um booleano ou um objeto com opções como `{ estimateSize: 32, overscan: 12 }`.

> \[!WARNING]
> See: https\://github.com/unovue/reka-ui/issues/1885
>
> Quando habilitado, todos os grupos são achatados em uma única lista devido a uma limitação do Reka UI.

::component-example{prettier name="select-menu-virtualize-example"}
::

### Com rolagem infinita `4.4+`

Você pode usar o composable [`useInfiniteScroll`](https://vueuse.org/core/useInfiniteScroll/){rel="&#x22;nofollow&#x22;"} para carregar mais dados conforme o usuário rola.

::component-example
---
collapse: true
highlights:
  - 41
  - 51
overflowHidden: true
prettier: true
name: select-menu-infinite-scroll-example
---
::

> \[!NOTE]
>
> Este exemplo usa `useLazyFetch` com `immediate: false`, então os dados só são carregados conforme o usuário rola.

### Com largura total do conteúdo

Você pode expandir o conteúdo até a largura total dos seus itens adicionando a classe `min-w-fit` no slot `ui.content`.

::component-example{collapse name="select-menu-content-width-example"}
::

> \[!TIP]
>
> Você também pode alterar a largura do conteúdo globalmente no seu `app.config.ts`:
>
> ```text
> export default defineAppConfig({
>   ui: {
>     selectMenu: {
>       slots: {
>         content: 'min-w-fit'
>       }
>     }
>   }
> })
> ```

### Como seletor de país

Você pode usar o SelectMenu como um seletor de país com carregamento sob demanda. Os países só são buscados quando o menu é aberto pela primeira vez.

::component-example{collapse name="select-menu-countries-example"}
::

> \[!NOTE]
>
> Este exemplo usa `useLazyFetch` com `immediate: false` para carregar os países apenas quando o menu é aberto pela primeira vez.

## API

### Props

```ts
/**
 * Props for the SelectMenu component
 */
interface SelectMenuProps {
  id?: string | undefined;
  /**
   * The placeholder text when the select is empty.
   */
  placeholder?: string | undefined;
  /**
   * Whether to display the search input or not.
   * Can be an object to pass additional props to the input.
   * `{ placeholder: 'Search...', variant: 'none' }`{lang="ts-type"}
   * @default "true"
   */
  searchInput?: boolean | Omit<InputProps<AcceptableValue, ModelModifiers>, "modelValue" | "defaultValue"> | undefined;
  color?: "primary" | "secondary" | "accent" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
  variant?: "outline" | "soft" | "subtle" | "ghost" | "none" | undefined;
  size?: "sm" | "md" | "xs" | "lg" | "xl" | undefined;
  required?: boolean | undefined;
  /**
   * The icon displayed to open the menu.
   */
  trailingIcon?: any;
  /**
   * The icon displayed when an item is selected.
   */
  selectedIcon?: any;
  /**
   * Display a clear button to reset the model value.
   * Can be an object to pass additional props to the Button.
   */
  clear?: (C & boolean) | (C & Partial<Omit<ButtonProps, LinkPropsKeys>>) | undefined;
  /**
   * The icon displayed in the clear button.
   */
  clearIcon?: any;
  /**
   * The content of the menu.
   */
  content?: (Omit<ComboboxContentProps, "asChild" | "as" | "forceMount"> & Partial<EmitsToProps<DismissableLayerEmits>>) | undefined;
  /**
   * Display an arrow alongside the menu.
   * `{ rounded: true }`{lang="ts-type"}
   */
  arrow?: boolean | Omit<ComboboxArrowProps, "asChild" | "as"> | undefined;
  /**
   * Render the menu in a portal.
   * @default "true"
   */
  portal?: string | boolean | HTMLElement | undefined;
  /**
   * Enable virtualization for large lists.
   * Note: when enabled, all groups are flattened into a single list due to a limitation of Reka UI (https://github.com/unovue/reka-ui/issues/1885).
   * @default "false"
   */
  virtualize?: boolean | { overscan?: number | undefined; estimateSize?: number | ((index: number) => number) | undefined; } | undefined;
  /**
   * When `items` is an array of objects, select the field to use as the value instead of the object itself.
   */
  valueKey?: VK | undefined;
  /**
   * When `items` is an array of objects, select the field to use as the label.
   * @default "\"label\""
   */
  labelKey?: GetItemKeys<T> | undefined;
  /**
   * When `items` is an array of objects, select the field to use as the description.
   * @default "\"description\""
   */
  descriptionKey?: GetItemKeys<T> | undefined;
  items?: T | undefined;
  /**
   * The value of the SelectMenu when initially rendered. Use when you do not need to control the state of the SelectMenu.
   */
  defaultValue?: _Number<_Optional<_Nullable<GetModelValue<T, VK, M, ExcludeItem>, Mod>, Mod>, Mod> | IsClearUsed<M, C> | undefined;
  /**
   * The controlled value of the SelectMenu. Can be binded-with with `v-model`.
   */
  modelValue?: _Number<_Optional<_Nullable<GetModelValue<T, VK, M, ExcludeItem>, Mod>, Mod>, Mod> | IsClearUsed<M, C> | undefined;
  modelModifiers?: Mod | undefined;
  /**
   * Whether multiple options can be selected or not.
   */
  multiple?: M | undefined;
  /**
   * Highlight the ring color like a focus state.
   */
  highlight?: boolean | undefined;
  /**
   * Determines if custom user input that does not exist in options can be added.
   */
  createItem?: boolean | "always" | { position?: "top" | "bottom" | undefined; when?: "always" | "empty" | undefined; } | undefined;
  /**
   * Fields to filter items by.
   */
  filterFields?: string[] | undefined;
  /**
   * When `true`, disable the default filters, useful for custom filtering (useAsyncData, useFetch, etc.).
   */
  ignoreFilter?: boolean | undefined;
  autofocus?: boolean | undefined;
  /**
   * @default "0"
   */
  autofocusDelay?: number | undefined;
  ui?: { base?: SlotClass; leading?: SlotClass; leadingIcon?: SlotClass; leadingAvatar?: SlotClass; leadingAvatarSize?: SlotClass; trailing?: SlotClass; trailingIcon?: SlotClass; value?: SlotClass; placeholder?: SlotClass; arrow?: SlotClass; content?: SlotClass; viewport?: SlotClass; group?: SlotClass; empty?: SlotClass; label?: SlotClass; separator?: SlotClass; item?: SlotClass; itemLeadingIcon?: SlotClass; itemLeadingAvatar?: SlotClass; itemLeadingAvatarSize?: SlotClass; itemLeadingChip?: SlotClass; itemLeadingChipSize?: SlotClass; itemTrailing?: SlotClass; itemTrailingIcon?: SlotClass; itemWrapper?: SlotClass; itemLabel?: SlotClass; itemDescription?: SlotClass; input?: SlotClass; focusScope?: SlotClass; trailingClear?: SlotClass; } | undefined;
  /**
   * When `true`, prevents the user from interacting with listbox
   */
  disabled?: boolean | undefined;
  /**
   * The controlled open state of the Combobox. Can be binded with `v-model:open`.
   */
  open?: boolean | undefined;
  /**
   * The open state of the combobox when it is initially rendered. <br> Use when you do not need to control its open state.
   */
  defaultOpen?: boolean | undefined;
  /**
   * The name of the field. Submitted with its owning form as part of a name/value pair.
   */
  name?: string | undefined;
  /**
   * Whether to reset the searchTerm when the Combobox input blurred
   * @default "true"
   */
  resetSearchTermOnBlur?: boolean | undefined;
  /**
   * Whether to reset the searchTerm when the Combobox value is selected
   * @default "true"
   */
  resetSearchTermOnSelect?: boolean | undefined;
  /**
   * When `true` the `modelValue` will be reset to `null` (or `[]` if `multiple`)
   * @default "true"
   */
  resetModelValueOnClear?: boolean | undefined;
  /**
   * When `true`, hover over item will trigger highlight
   */
  highlightOnHover?: boolean | undefined;
  /**
   * Use this to compare objects by a particular field, or pass your own comparison function for complete control over how objects are compared.
   */
  by?: string | ((a: T, b: T) => boolean) | undefined;
  /**
   * Display an icon based on the `leading` and `trailing` props.
   */
  icon?: any;
  /**
   * Display an avatar on the left side.
   */
  avatar?: AvatarProps | undefined;
  /**
   * When `true`, the icon will be displayed on the left side.
   */
  leading?: boolean | undefined;
  /**
   * Display an icon on the left side.
   */
  leadingIcon?: any;
  /**
   * When `true`, the icon will be displayed on the right side.
   */
  trailing?: boolean | undefined;
  /**
   * When `true`, the loading icon will be displayed.
   */
  loading?: boolean | undefined;
  /**
   * The icon when the `loading` prop is `true`.
   */
  loadingIcon?: any;
  form?: string | undefined;
  formaction?: string | undefined;
  formenctype?: string | undefined;
  formmethod?: string | undefined;
  formnovalidate?: Booleanish | undefined;
  formtarget?: string | undefined;
  /**
   * @default "\"\""
   */
  searchTerm?: string | undefined;
}
```

> \[!NOTE]
> See: https\://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attributes
>
> Este componente também suporta todos os atributos HTML nativos de `<button>`.

### Slots

```ts
/**
 * Slots for the SelectMenu component
 */
interface SelectMenuSlots {
  leading(): any;
  default(): any;
  trailing(): any;
  empty(): any;
  item(): any;
  item-leading(): any;
  item-label(): any;
  item-description(): any;
  item-trailing(): any;
  content-top(): any;
  content-bottom(): any;
  create-item-label(): any;
}
```

### Emits

```ts
/**
 * Emitted events for the SelectMenu component
 */
interface SelectMenuEmits {
  update:open: (payload: [value: boolean]) => void;
  change: (payload: [event: Event]) => void;
  blur: (payload: [event: FocusEvent]) => void;
  focus: (payload: [event: FocusEvent]) => void;
  create: (payload: [item: string]) => void;
  clear: (payload: []) => void;
  highlight: (payload: [payload: { ref: HTMLElement; value: _Number<_Optional<_Nullable<GetModelValue<T, VK, M, ExcludeItem>, Mod>, Mod>, Mod> | IsClearUsed<M, C>; } | undefined]) => void;
  update:modelValue: (payload: [value: _Number<_Optional<_Nullable<GetModelValue<T, VK, M, ExcludeItem>, Mod>, Mod>, Mod> | IsClearUsed<M, C>]) => void;
  update:searchTerm: (payload: [value: string]) => void;
}
```

### Expose

Ao acessar o componente por meio de um template ref, você pode usar o seguinte:

| Name                                                                                                                              | Type                                                                                                                                                |
| --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `triggerRef`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"}  | `Ref<HTMLButtonElement | null>`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} |
| `viewportRef`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | `Ref<HTMLDivElement | null>`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"}    |

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    selectMenu: {
      slots: {
        base: [
          'relative group rounded-md inline-flex items-center disabled:cursor-not-allowed disabled:opacity-75',
          'transition-colors'
        ],
        leading: 'absolute inset-y-0 start-0 flex items-center',
        leadingIcon: 'shrink-0 text-dimmed',
        leadingAvatar: 'shrink-0',
        leadingAvatarSize: '',
        trailing: 'absolute inset-y-0 end-0 flex items-center',
        trailingIcon: 'shrink-0 text-dimmed',
        value: 'truncate pointer-events-none',
        placeholder: 'truncate text-dimmed',
        arrow: 'fill-bg stroke-default',
        content: [
          'max-h-[min(15rem,var(--reka-select-content-available-height,15rem))] w-(--reka-select-trigger-width) bg-default shadow-lg rounded-md ring ring-default overflow-hidden origin-(--reka-select-content-transform-origin) pointer-events-auto flex flex-col',
          'max-h-[min(15rem,var(--reka-combobox-content-available-height,15rem))] origin-(--reka-combobox-content-transform-origin) w-(--reka-combobox-trigger-width)'
        ],
        viewport: 'relative scroll-py-1 overflow-y-auto flex-1',
        group: 'p-1 isolate',
        empty: 'text-center text-muted',
        label: 'font-semibold text-highlighted',
        separator: '-mx-1 my-1 h-px bg-border',
        item: [
          'group relative w-full flex items-start select-none outline-none before:absolute before:z-[-1] before:inset-px before:rounded-md data-disabled:cursor-not-allowed data-disabled:opacity-75 text-default data-highlighted:not-data-disabled:text-highlighted data-highlighted:not-data-disabled:before:bg-elevated/50',
          'transition-colors before:transition-colors'
        ],
        itemLeadingIcon: [
          'shrink-0 text-dimmed group-data-highlighted:not-group-data-disabled:text-default',
          'transition-colors'
        ],
        itemLeadingAvatar: 'shrink-0',
        itemLeadingAvatarSize: '',
        itemLeadingChip: 'shrink-0',
        itemLeadingChipSize: '',
        itemTrailing: 'ms-auto inline-flex gap-1.5 items-center',
        itemTrailingIcon: 'shrink-0',
        itemWrapper: 'flex-1 flex flex-col min-w-0',
        itemLabel: 'truncate',
        itemDescription: 'truncate text-muted',
        input: 'border-b border-default',
        focusScope: 'flex flex-col min-h-0',
        trailingClear: 'p-0'
      },
      variants: {
        fieldGroup: {
          horizontal: 'not-only:first:rounded-e-none not-only:last:rounded-s-none not-last:not-first:rounded-none focus-visible:z-[1]',
          vertical: 'not-only:first:rounded-b-none not-only:last:rounded-t-none not-last:not-first:rounded-none focus-visible:z-[1]'
        },
        size: {
          xs: {
            base: 'px-2 py-1 text-xs gap-1',
            leading: 'ps-2',
            trailing: 'pe-2',
            leadingIcon: 'size-4',
            leadingAvatarSize: '3xs',
            trailingIcon: 'size-4',
            label: 'p-1 text-[10px]/3 gap-1',
            item: 'p-1 text-xs gap-1',
            itemLeadingIcon: 'size-4',
            itemLeadingAvatarSize: '3xs',
            itemLeadingChip: 'size-4',
            itemLeadingChipSize: 'sm',
            itemTrailingIcon: 'size-4',
            empty: 'p-2 text-xs'
          },
          sm: {
            base: 'px-2.5 py-1.5 text-xs gap-1.5',
            leading: 'ps-2.5',
            trailing: 'pe-2.5',
            leadingIcon: 'size-4',
            leadingAvatarSize: '3xs',
            trailingIcon: 'size-4',
            label: 'p-1.5 text-[10px]/3 gap-1.5',
            item: 'p-1.5 text-xs gap-1.5',
            itemLeadingIcon: 'size-4',
            itemLeadingAvatarSize: '3xs',
            itemLeadingChip: 'size-4',
            itemLeadingChipSize: 'sm',
            itemTrailingIcon: 'size-4',
            empty: 'p-2.5 text-xs'
          },
          md: {
            base: 'px-2.5 py-1.5 text-sm gap-1.5',
            leading: 'ps-2.5',
            trailing: 'pe-2.5',
            leadingIcon: 'size-5',
            leadingAvatarSize: '2xs',
            trailingIcon: 'size-5',
            label: 'p-1.5 text-xs gap-1.5',
            item: 'p-1.5 text-sm gap-1.5',
            itemLeadingIcon: 'size-5',
            itemLeadingAvatarSize: '2xs',
            itemLeadingChip: 'size-5',
            itemLeadingChipSize: 'md',
            itemTrailingIcon: 'size-5',
            empty: 'p-2.5 text-sm'
          },
          lg: {
            base: 'px-3 py-2 text-sm gap-2',
            leading: 'ps-3',
            trailing: 'pe-3',
            leadingIcon: 'size-5',
            leadingAvatarSize: '2xs',
            trailingIcon: 'size-5',
            label: 'p-2 text-xs gap-2',
            item: 'p-2 text-sm gap-2',
            itemLeadingIcon: 'size-5',
            itemLeadingAvatarSize: '2xs',
            itemLeadingChip: 'size-5',
            itemLeadingChipSize: 'md',
            itemTrailingIcon: 'size-5',
            empty: 'p-3 text-sm'
          },
          xl: {
            base: 'px-3 py-2 text-base gap-2',
            leading: 'ps-3',
            trailing: 'pe-3',
            leadingIcon: 'size-6',
            leadingAvatarSize: 'xs',
            trailingIcon: 'size-6',
            label: 'p-2 text-sm gap-2',
            item: 'p-2 text-base gap-2',
            itemLeadingIcon: 'size-6',
            itemLeadingAvatarSize: 'xs',
            itemLeadingChip: 'size-6',
            itemLeadingChipSize: 'lg',
            itemTrailingIcon: 'size-6',
            empty: 'p-3 text-base'
          }
        },
        variant: {
          outline: 'text-highlighted bg-default ring ring-inset ring-accented hover:bg-elevated disabled:bg-default',
          soft: 'text-highlighted bg-elevated/50 hover:bg-elevated focus:bg-elevated disabled:bg-elevated/50',
          subtle: 'text-highlighted bg-elevated ring ring-inset ring-accented hover:bg-accented/75 disabled:bg-elevated',
          ghost: 'text-highlighted bg-transparent hover:bg-elevated focus:bg-elevated disabled:bg-transparent dark:disabled:bg-transparent',
          none: 'text-highlighted bg-transparent focus:outline-none'
        },
        color: {
          primary: '',
          secondary: '',
          accent: '',
          success: '',
          info: '',
          warning: '',
          error: '',
          neutral: ''
        },
        leading: {
          true: ''
        },
        trailing: {
          true: ''
        },
        loading: {
          true: ''
        },
        highlight: {
          true: ''
        },
        fixed: {
          false: ''
        },
        type: {
          file: 'file:me-1.5 file:font-medium file:text-muted file:outline-none'
        },
        position: {
          popper: {
            content: 'data-[state=open]:animate-[scale-in_100ms_ease-out] data-[state=closed]:animate-[scale-out_100ms_ease-in]'
          },
          'item-aligned': {
            content: ''
          }
        },
        multiple: {
          true: ''
        },
        virtualize: {
          true: {
            viewport: 'p-1 isolate'
          },
          false: {
            viewport: 'divide-y divide-default'
          }
        }
      },
      compoundVariants: [
        {
          color: 'primary',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-primary/25 focus-visible:outline-3 focus-visible:ring-primary'
        },
        {
          color: 'secondary',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-secondary/25 focus-visible:outline-3 focus-visible:ring-secondary'
        },
        {
          color: 'accent',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-accent/25 focus-visible:outline-3 focus-visible:ring-accent'
        },
        {
          color: 'success',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-success/25 focus-visible:outline-3 focus-visible:ring-success'
        },
        {
          color: 'info',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-info/25 focus-visible:outline-3 focus-visible:ring-info'
        },
        {
          color: 'warning',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-warning/25 focus-visible:outline-3 focus-visible:ring-warning'
        },
        {
          color: 'error',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-error/25 focus-visible:outline-3 focus-visible:ring-error'
        },
        {
          color: 'primary',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-primary/25 focus-visible:outline-3'
        },
        {
          color: 'secondary',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-secondary/25 focus-visible:outline-3'
        },
        {
          color: 'accent',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-accent/25 focus-visible:outline-3'
        },
        {
          color: 'success',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-success/25 focus-visible:outline-3'
        },
        {
          color: 'info',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-info/25 focus-visible:outline-3'
        },
        {
          color: 'warning',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-warning/25 focus-visible:outline-3'
        },
        {
          color: 'error',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-error/25 focus-visible:outline-3'
        },
        {
          color: 'primary',
          highlight: true,
          class: 'ring ring-inset ring-primary'
        },
        {
          color: 'secondary',
          highlight: true,
          class: 'ring ring-inset ring-secondary'
        },
        {
          color: 'accent',
          highlight: true,
          class: 'ring ring-inset ring-accent'
        },
        {
          color: 'success',
          highlight: true,
          class: 'ring ring-inset ring-success'
        },
        {
          color: 'info',
          highlight: true,
          class: 'ring ring-inset ring-info'
        },
        {
          color: 'warning',
          highlight: true,
          class: 'ring ring-inset ring-warning'
        },
        {
          color: 'error',
          highlight: true,
          class: 'ring ring-inset ring-error'
        },
        {
          color: 'neutral',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-inverted/25 focus-visible:outline-3 focus-visible:ring-inverted'
        },
        {
          color: 'neutral',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-inverted/25 focus-visible:outline-3'
        },
        {
          color: 'neutral',
          highlight: true,
          class: 'ring ring-inset ring-inverted'
        },
        {
          leading: true,
          size: 'xs',
          class: 'ps-7'
        },
        {
          leading: true,
          size: 'sm',
          class: 'ps-8'
        },
        {
          leading: true,
          size: 'md',
          class: 'ps-9'
        },
        {
          leading: true,
          size: 'lg',
          class: 'ps-10'
        },
        {
          leading: true,
          size: 'xl',
          class: 'ps-11'
        },
        {
          trailing: true,
          size: 'xs',
          class: 'pe-7'
        },
        {
          trailing: true,
          size: 'sm',
          class: 'pe-8'
        },
        {
          trailing: true,
          size: 'md',
          class: 'pe-9'
        },
        {
          trailing: true,
          size: 'lg',
          class: 'pe-10'
        },
        {
          trailing: true,
          size: 'xl',
          class: 'pe-11'
        },
        {
          loading: true,
          leading: true,
          class: {
            leadingIcon: 'animate-spin'
          }
        },
        {
          loading: true,
          leading: false,
          trailing: true,
          class: {
            trailingIcon: 'animate-spin'
          }
        },
        {
          fixed: false,
          size: 'xs',
          class: 'md:text-xs'
        },
        {
          fixed: false,
          size: 'sm',
          class: 'md:text-xs'
        },
        {
          fixed: false,
          size: 'md',
          class: 'md:text-sm'
        },
        {
          fixed: false,
          size: 'lg',
          class: 'md:text-sm'
        }
      ],
      defaultVariants: {
        size: 'md',
        color: 'accent',
        variant: 'outline',
        position: 'popper'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/SelectMenu.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/select-menu.ts).


# Separator

## Uso

Use o componente Separator como está para separar conteúdo.

```vue
<template>
  <USeparator />
</template>
```

### Orientação

Use a prop `orientation` para alterar a orientação do Separator. O padrão é `horizontal`.

```vue
<template>
  <USeparator orientation="vertical" class="h-48" />
</template>
```

### Label

Use a prop `label` para exibir um rótulo no meio do Separator.

```vue
<template>
  <USeparator label="Hello World" />
</template>
```

### Posição `4.8+`

Use a prop `position` para alterar a posição do conteúdo do Separator. O padrão é `center`.

```vue
<template>
  <USeparator position="start" label="Hello World" />
</template>
```

### Ícone

Use a prop `icon` para exibir um ícone no meio do Separator.

```vue
<template>
  <USeparator icon="i-simple-icons-nuxtdotjs" />
</template>
```

### Avatar

Use a prop `avatar` para exibir um avatar no meio do Separator.

```vue
<template>
  <USeparator :avatar="{
  src: 'https://github.com/nuxt.png',
  loading: 'lazy'
}" />
</template>
```

### Cor

Use a prop `color` para alterar a cor do Separator. O padrão é `neutral`.

```vue
<template>
  <USeparator color="primary" type="solid" />
</template>
```

### Tipo

Use a prop `type` para alterar o tipo do Separator. O padrão é `solid`.

```vue
<template>
  <USeparator type="dashed" />
</template>
```

### Tamanho

Use a prop `size` para alterar o tamanho do Separator. O padrão é `xs`.

```vue
<template>
  <USeparator size="lg" />
</template>
```

## API

### Props

```ts
/**
 * Props for the Separator component
 */
interface SeparatorProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  /**
   * Display a label in the middle.
   */
  label?: string | undefined;
  /**
   * Display an icon in the middle.
   */
  icon?: any;
  /**
   * Display an avatar in the middle.
   */
  avatar?: AvatarProps | undefined;
  color?: "error" | "neutral" | "primary" | "secondary" | "accent" | "success" | "info" | "warning" | undefined;
  size?: "xs" | "sm" | "md" | "lg" | "xl" | undefined;
  type?: "solid" | "dashed" | "dotted" | undefined;
  /**
   * The orientation of the separator.
   * @default "\"horizontal\""
   */
  orientation?: "horizontal" | "vertical" | undefined;
  ui?: { root?: SlotClass; border?: SlotClass; container?: SlotClass; icon?: SlotClass; avatar?: SlotClass; avatarSize?: SlotClass; label?: SlotClass; } | undefined;
  /**
   * Whether or not the component is purely decorative. <br>When `true`, accessibility-related attributes
   * are updated so that that the rendered element is removed from the accessibility tree.
   */
  decorative?: boolean | undefined;
}
```

### Slots

```ts
/**
 * Slots for the Separator component
 */
interface SeparatorSlots {
  default(): any;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    separator: {
      slots: {
        root: 'flex items-center align-center text-center',
        border: '',
        container: 'font-medium text-default flex',
        icon: 'shrink-0 size-5',
        avatar: 'shrink-0',
        avatarSize: '2xs',
        label: 'text-sm'
      },
      variants: {
        color: {
          primary: {
            border: 'border-primary'
          },
          secondary: {
            border: 'border-secondary'
          },
          accent: {
            border: 'border-accent'
          },
          success: {
            border: 'border-success'
          },
          info: {
            border: 'border-info'
          },
          warning: {
            border: 'border-warning'
          },
          error: {
            border: 'border-error'
          },
          neutral: {
            border: 'border-default'
          }
        },
        orientation: {
          horizontal: {
            root: 'w-full flex-row',
            border: 'w-full',
            container: 'mx-3 whitespace-nowrap'
          },
          vertical: {
            root: 'h-full flex-col',
            border: 'h-full',
            container: 'my-2'
          }
        },
        size: {
          xs: '',
          sm: '',
          md: '',
          lg: '',
          xl: ''
        },
        type: {
          solid: {
            border: 'border-solid'
          },
          dashed: {
            border: 'border-dashed'
          },
          dotted: {
            border: 'border-dotted'
          }
        }
      },
      compoundVariants: [
        {
          orientation: 'horizontal',
          size: 'xs',
          class: {
            border: 'border-t'
          }
        },
        {
          orientation: 'horizontal',
          size: 'sm',
          class: {
            border: 'border-t-[2px]'
          }
        },
        {
          orientation: 'horizontal',
          size: 'md',
          class: {
            border: 'border-t-[3px]'
          }
        },
        {
          orientation: 'horizontal',
          size: 'lg',
          class: {
            border: 'border-t-[4px]'
          }
        },
        {
          orientation: 'horizontal',
          size: 'xl',
          class: {
            border: 'border-t-[5px]'
          }
        },
        {
          orientation: 'vertical',
          size: 'xs',
          class: {
            border: 'border-s'
          }
        },
        {
          orientation: 'vertical',
          size: 'sm',
          class: {
            border: 'border-s-[2px]'
          }
        },
        {
          orientation: 'vertical',
          size: 'md',
          class: {
            border: 'border-s-[3px]'
          }
        },
        {
          orientation: 'vertical',
          size: 'lg',
          class: {
            border: 'border-s-[4px]'
          }
        },
        {
          orientation: 'vertical',
          size: 'xl',
          class: {
            border: 'border-s-[5px]'
          }
        }
      ],
      defaultVariants: {
        color: 'neutral',
        size: 'xs',
        type: 'solid'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/Separator.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/separator.ts).


# Sidebar

## Uso

O componente Sidebar é uma sidebar fixa e independente que empurra o conteúdo da página. No desktop, ela é renderizada inline e pode ser recolhida; no mobile, ela abre um componente [Modal](https://ui.nitro.news/docs/components/modal), [Slideover](https://ui.nitro.news/docs/components/slideover) ou [Drawer](https://ui.nitro.news/docs/components/drawer).

> \[!TIP]
> See: /docs/components/dashboard-sidebar
>
> **Sidebar vs DashboardSidebar**: This component is a simple, standalone sidebar you can drop anywhere (chat panel, settings, navigation). If you need drag-to-resize, state persistence and integration with [DashboardGroup](https://ui.nitro.news/docs/components/dashboard-group), use [DashboardSidebar](https://ui.nitro.news/docs/components/dashboard-sidebar) instead.

Use os slots `header`, `default` e `footer` para personalizar o conteúdo da sidebar. A diretiva `v-model:open` é sensível à viewport: no desktop ela controla o estado expandido/recolhido, no mobile ela controla o menu.

::component-example
---
collapse: true
overflowHidden: true
prettier: true
class: "!p-0 !justify-start h-[500px] contain-[paint] transform-gpu"
name: sidebar-example
---
::

### Variante

Use a prop `variant` para alterar o estilo visual da sidebar. O padrão é `sidebar`.

::component-example
---
collapse: true
options:
  - name: variant
    label: variant
    items:
      - sidebar
      - floating
      - inset
    default: inset
overflowHidden: true
prettier: true
class: "!p-0 !justify-start h-[500px] contain-[paint] transform-gpu"
name: sidebar-props-example
---
::

### Recolhível

Use a prop `collapsible` para alterar o comportamento de recolhimento da sidebar. O padrão é `offcanvas`.

- `offcanvas`: The sidebar slides out of view completely.
- `icon`: The sidebar shrinks to icon-only width.
- `none`: The sidebar is not collapsible.

::component-example
---
collapse: true
options:
  - name: collapsible
    label: collapsible
    items:
      - offcanvas
      - icon
      - none
    default: icon
  - name: variant
    label: variant
    items:
      - sidebar
      - floating
      - inset
    default: sidebar
overflowHidden: true
prettier: true
class: "!p-0 !justify-start h-[500px] contain-[paint] transform-gpu"
name: sidebar-props-example
---
::

> \[!TIP]
> See: #slots
>
> Você pode acessar o `state` nas props de slot para personalizar o conteúdo da sidebar quando ela está recolhida.

### Lado

Use a prop `side` para alterar o lado da sidebar. O padrão é `left`.

::component-example
---
collapse: true
options:
  - name: side
    label: side
    items:
      - left
      - right
    default: right
overflowHidden: true
prettier: true
class: "!p-0 !justify-start h-[500px] contain-[paint] transform-gpu"
name: sidebar-props-example
---
::

### Título

Use a prop `title` para definir o título do cabeçalho da sidebar.

```vue
<template>
  <USidebar title="Navigation">
    <Placeholder class="h-full" />
  </USidebar>
</template>
```

### Descrição

Use a prop `description` para definir a descrição do cabeçalho da sidebar.

```vue
<template>
  <USidebar title="Navigation" description="Browse your workspace">
    <Placeholder class="h-full" />
  </USidebar>
</template>
```

### Trilho

Use a prop `rail` para exibir uma borda interativa fina na sidebar que alterna o estado recolhido ao clicar. O trilho só é renderizado quando `collapsible` não é `none`.

```vue
<template>
  <USidebar rail collapsible="icon" title="Navigation">
    <Placeholder class="h-full" />
  </USidebar>
</template>
```

### Fechar

Use a prop `close` para exibir um botão de fechar no cabeçalho da sidebar. O botão de fechar só é renderizado quando `collapsible` não é `none`.

Você pode passar qualquer propriedade do componente [Button](https://ui.nitro.news/docs/components/button) para personalizá-lo.

```vue
<template>
  <USidebar close rail collapsible="icon" title="Navigation">
    <Placeholder class="h-full" />
  </USidebar>
</template>
```

### Ícone de fechar

Use a prop `close-icon` para personalizar o [Icon](https://ui.nitro.news/docs/components/icon) do botão de fechar. O padrão é `i-lucide-x`.

```vue
<template>
  <USidebar close close-icon="i-lucide-panel-right-close" rail collapsible="icon" side="right" title="Navigation">
    <Placeholder class="h-full" />
  </USidebar>
</template>
```

**Nuxt:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/nuxt#theme
>
> Você pode personalizar esse ícone globalmente no seu `app.config.ts` na chave `ui.icons.close`.

**Vue:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/vue#theme
>
> Você pode personalizar esse ícone globalmente no seu `vite.config.ts` na chave `ui.icons.close`.

### Modo

Use a prop `mode` para alterar o modo do menu da sidebar no mobile. O padrão é `slideover`.

::component-example
---
collapse: true
iframe:
  height: 500px;
iframeMobile: true
options:
  - name: mode
    label: mode
    default: slideover
    items:
      - modal
      - slideover
      - drawer
overflowHidden: true
props:
  class: w-full
name: sidebar-mode-example
---
::

> \[!TIP]
> See: #props
>
> Você pode usar a prop `menu` para personalizar o menu da sidebar; ele se adapta dependendo do modo que você escolher.

## Exemplos

### Controlar o estado de abertura

Você pode controlar o estado de abertura usando a prop `open` ou a diretiva `v-model:open`. No desktop ela controla o estado expandido/recolhido, no mobile ela abre/fecha o menu deslizante.

::component-example
---
collapse: true
overflowHidden: true
prettier: true
class: "!p-0 !justify-start h-[500px] contain-[paint] transform-gpu"
name: sidebar-open-example
---
::

> \[!NOTE]
>
> Neste exemplo, aproveitando o [`defineShortcuts`](https://ui.nitro.news/docs/composables/define-shortcuts), você pode alternar o estado de abertura da Sidebar pressionando :kbd{value="O"}.

### Persistir o estado de abertura

Use [`useLocalStorage`](https://vueuse.org/core/useLocalStorage/){rel="&#x22;nofollow&#x22;"} do VueUse ou [`useCookie`](https://nuxt.com/docs/4.x/api/composables/use-cookie){rel="&#x22;nofollow&#x22;"} em vez de `ref` para persistir o estado da sidebar entre recarregamentos de página.

::component-example
---
collapse: true
overflowHidden: true
prettier: true
class: "!p-0 !justify-start h-[500px] contain-[paint] transform-gpu"
name: sidebar-persist-example
---
::

> \[!NOTE]
>
> A única diferença em relação ao exemplo anterior é substituir `ref(true)` por `useLocalStorage('sidebar-open', true)`.

### Com largura personalizada

A largura da sidebar é controlada pela variável CSS `--sidebar-width` (o padrão é `16rem`). A largura do ícone recolhido é controlada por `--sidebar-width-icon` (o padrão é `4rem`).

Sobrescreva-as globalmente no seu CSS ou por instância com o atributo `style`.

::component-example
---
collapse: true
overflowHidden: true
prettier: true
class: "!p-0 !justify-start h-[500px] contain-[paint] transform-gpu"
name: sidebar-width-example
---
::

### Com cabeçalho

Para posicionar a sidebar abaixo de um [Header](https://ui.nitro.news/docs/components/header), personalize o `gap` e o `container` usando a prop `ui`.

::component-example
---
collapse: true
overflowHidden: true
prettier: true
class: "!p-0 !justify-start h-[500px] contain-[paint] transform-gpu"
name: sidebar-header-example
---
::

> \[!NOTE]
>
> A variável `--ui-header-height` tem o padrão `4rem` e é usada pelo Header. Ajuste-a se a sua navbar usar uma altura diferente.

### Com chat de IA

Use a sidebar no lado direito com [ChatMessages](https://ui.nitro.news/docs/components/chat-messages) e [ChatPrompt](https://ui.nitro.news/docs/components/chat-prompt) para criar um painel de chat de IA.

::component-example
---
collapse: true
overflowHidden: true
prettier: true
class: "!p-0 !justify-start h-[500px] contain-[paint] transform-gpu"
name: sidebar-chat-example
---
::

## API

### Props

```ts
/**
 * Props for the Sidebar component
 */
interface SidebarProps {
  /**
   * The element or component this component should render as.
   * @default "\"aside\""
   */
  as?: any;
  /**
   * The visual variant of the sidebar.
   * @default "\"sidebar\""
   */
  variant?: "floating" | "sidebar" | "inset" | undefined;
  /**
   * The collapse behavior of the sidebar.
   * - `offcanvas`: The sidebar slides out of view completely.
   * - `icon`: The sidebar shrinks to icon-only width.
   * - `none`: The sidebar is not collapsible.
   * @default "\"offcanvas\""
   */
  collapsible?: "offcanvas" | "icon" | "none" | undefined;
  /**
   * The side to render the sidebar on.
   * @default "\"left\""
   */
  side?: "left" | "right" | undefined;
  /**
   * The title displayed in the sidebar header.
   */
  title?: string | undefined;
  /**
   * The description displayed in the sidebar header.
   */
  description?: string | undefined;
  /**
   * Display a close button to collapse the sidebar.
   * Only renders when `collapsible` is not `none`.
   * `{ size: 'md', color: 'neutral', variant: 'ghost' }`{lang="ts-type"}
   * @default "false"
   */
  close?: boolean | Omit<ButtonProps, LinkPropsKeys> | undefined;
  /**
   * The icon displayed in the close button.
   */
  closeIcon?: any;
  /**
   * Display a rail on the sidebar edge to toggle collapse.
   * Only renders when `collapsible` is not `none`.
   * @default "false"
   */
  rail?: boolean | undefined;
  /**
   * Animate the sidebar when collapsing or expanding.
   * @default "true"
   */
  transition?: boolean | undefined;
  /**
   * The mode of the sidebar menu on mobile.
   * @default "\"slideover\" as never"
   */
  mode?: T | undefined;
  /**
   * The props for the sidebar menu component on mobile.
   */
  menu?: SidebarMenu<T> | undefined;
  ui?: { root?: SlotClass; gap?: SlotClass; container?: SlotClass; inner?: SlotClass; header?: SlotClass; wrapper?: SlotClass; title?: SlotClass; description?: SlotClass; actions?: SlotClass; close?: SlotClass; body?: SlotClass; footer?: SlotClass; rail?: SlotClass; } | undefined;
  /**
   * @default "true"
   */
  open?: boolean | undefined;
}
```

### Slots

```ts
/**
 * Slots for the Sidebar component
 */
interface SidebarSlots {
  header(): any;
  title(): any;
  description(): any;
  actions(): any;
  close(): any;
  default(): any;
  footer(): any;
  rail(): any;
  content(): any;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    sidebar: {
      slots: {
        root: 'peer [--sidebar-width:16rem] [--sidebar-width-icon:4rem]',
        gap: 'relative w-(--sidebar-width) bg-transparent',
        container: 'fixed inset-y-0 z-10 hidden h-svh w-(--sidebar-width) lg:flex',
        inner: 'flex size-full flex-col overflow-hidden divide-y divide-default',
        header: 'flex items-center gap-1.5 overflow-hidden px-4 min-h-(--ui-header-height)',
        wrapper: 'min-w-0 flex-1',
        title: 'text-highlighted font-semibold truncate',
        description: 'text-muted text-sm truncate',
        actions: 'flex items-center gap-1.5 shrink-0',
        close: '',
        body: 'flex min-h-0 flex-1 flex-col gap-4 overflow-y-auto p-4',
        footer: 'flex items-center gap-1.5 overflow-hidden p-4',
        rail: [
          'absolute inset-y-0 z-20 hidden w-4 after:absolute after:inset-y-0 after:left-1/2 after:w-px lg:flex hover:after:bg-(--ui-border-accented)',
          'after:transition-colors'
        ]
      },
      variants: {
        transition: {
          true: {
            gap: 'transition-[width] duration-200 ease-out',
            container: 'transition-[left,right,width] duration-200 ease-out',
            rail: 'transition-all ease-out'
          }
        },
        side: {
          left: {
            container: 'left-0 border-e border-default',
            rail: 'end-0 translate-x-1/2'
          },
          right: {
            container: 'right-0 border-s border-default',
            rail: '-start-px -translate-x-1/2'
          }
        },
        collapsible: {
          offcanvas: {
            root: 'group/sidebar hidden lg:block',
            gap: 'data-[state=collapsed]:w-0'
          },
          icon: {
            root: 'group/sidebar hidden lg:block',
            gap: 'data-[state=collapsed]:w-(--sidebar-width-icon)',
            container: 'data-[state=collapsed]:w-(--sidebar-width-icon)',
            actions: 'group-data-[state=collapsed]/sidebar:hidden',
            body: 'group-data-[state=collapsed]/sidebar:overflow-hidden'
          },
          none: {
            root: 'h-full w-(--sidebar-width)'
          }
        },
        variant: {
          sidebar: {},
          floating: {
            container: 'p-4 border-transparent',
            inner: 'rounded-lg ring ring-default shadow-lg',
            rail: 'inset-y-4'
          },
          inset: {
            container: 'py-4 border-transparent',
            inner: 'divide-transparent',
            rail: 'inset-y-4'
          }
        }
      },
      compoundVariants: [
        {
          side: 'left',
          collapsible: [
            'offcanvas',
            'icon'
          ],
          class: {
            rail: 'cursor-w-resize data-[state=collapsed]:cursor-e-resize'
          }
        },
        {
          side: 'right',
          collapsible: [
            'offcanvas',
            'icon'
          ],
          class: {
            rail: 'cursor-e-resize data-[state=collapsed]:cursor-w-resize'
          }
        },
        {
          side: 'left',
          collapsible: 'none',
          class: {
            root: 'border-e border-default'
          }
        },
        {
          side: 'right',
          collapsible: 'none',
          class: {
            root: 'border-s border-default'
          }
        },
        {
          side: 'left',
          collapsible: 'offcanvas',
          class: {
            container: 'data-[state=collapsed]:-left-(--sidebar-width)'
          }
        },
        {
          side: 'right',
          collapsible: 'offcanvas',
          class: {
            container: 'data-[state=collapsed]:-right-(--sidebar-width)'
          }
        },
        {
          variant: 'floating',
          collapsible: 'icon',
          class: {
            gap: 'data-[state=collapsed]:w-[calc(var(--sidebar-width-icon)+--spacing(8))]',
            container: 'data-[state=collapsed]:w-[calc(var(--sidebar-width-icon)+--spacing(8)+2px)]'
          }
        },
        {
          variant: 'floating',
          collapsible: 'none',
          class: {
            root: 'p-4 border-0'
          }
        },
        {
          variant: 'inset',
          collapsible: 'none',
          class: {
            root: 'py-4 border-0'
          }
        },
        {
          variant: 'floating',
          side: 'left',
          class: {
            rail: 'end-4'
          }
        },
        {
          variant: 'floating',
          side: 'right',
          class: {
            rail: 'start-[calc(--spacing(4)-1px)]'
          }
        }
      ]
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/Sidebar.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/sidebar.ts).


# Skeleton

## Uso

Use o componente Skeleton como está para exibir um placeholder.

:component-example{name="skeleton-example"}

## API

### Props

```ts
/**
 * Props for the Skeleton component
 */
interface SkeletonProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  ui?: { base?: any; } | undefined;
}
```

### Slots

```ts
/**
 * Slots for the Skeleton component
 */
interface SkeletonSlots {
  default(): any;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    skeleton: {
      base: 'animate-pulse rounded-md bg-elevated'
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/Skeleton.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/skeleton.ts).


# Slideover

## Uso

Use a [Button](https://ui.nitro.news/docs/components/button) or any other component in the default slot of the Slideover.

Depois, use o slot `#content` para adicionar o conteúdo exibido quando o Slideover está aberto.

```vue
<template>
  <USlideover>
    <NButton label="Open" color="neutral" variant="subtle" />
  
    <template #content>
      <Placeholder class="h-full m-4" />
    </template></USlideover>
</template>
```

Você também pode usar os slots `#header`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}, `#body`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} e `#footer`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} para personalizar o conteúdo do Slideover.

### Título

Use a prop `title` para definir o título do cabeçalho do Slideover.

```vue
<template>
  <USlideover title="Slideover with title">
    <NButton label="Open" color="neutral" variant="subtle" />
  
    <template #body>
      <Placeholder class="h-full" />
    </template></USlideover>
</template>
```

### Descrição

Use a prop `description` para definir a descrição do cabeçalho do Slideover.

```vue
<template>
  <USlideover title="Slideover with description" description="Lorem ipsum dolor sit amet, consectetur adipiscing elit.">
    <NButton label="Open" color="neutral" variant="subtle" />
  
    <template #body>
      <Placeholder class="h-full" />
    </template></USlideover>
</template>
```

### Fechar

Use a prop `close` para personalizar ou ocultar o botão de fechar (com o valor `false`) exibido no cabeçalho do Slideover.

Você pode passar qualquer propriedade do componente [Button](https://ui.nitro.news/docs/components/button) para personalizá-lo.

```vue
<template>
  <USlideover title="Slideover with close button" :close="{
  color: 'primary',
  variant: 'outline',
  class: 'rounded-full'
}">
    <NButton label="Open" color="neutral" variant="subtle" />
  
    <template #body>
      <Placeholder class="h-full" />
    </template></USlideover>
</template>
```

> \[!NOTE]
>
> O botão de fechar não é exibido se o slot `#content` for usado, pois ele faz parte do cabeçalho.

### Ícone de fechar

Use a prop `close-icon` para personalizar o [Icon](https://ui.nitro.news/docs/components/icon) do botão de fechar. O padrão é `i-lucide-x`.

```vue
<template>
  <USlideover title="Slideover with close button" close-icon="i-lucide-arrow-right">
    <NButton label="Open" color="neutral" variant="subtle" />
  
    <template #body>
      <Placeholder class="h-full" />
    </template></USlideover>
</template>
```

**Nuxt:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/nuxt#theme
>
> Você pode personalizar esse ícone globalmente no seu `app.config.ts` na chave `ui.icons.close`.

**Vue:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/vue#theme
>
> Você pode personalizar esse ícone globalmente no seu `vite.config.ts` na chave `ui.icons.close`.

### Lado

Use a prop `side` para definir o lado da tela de onde o Slideover vai deslizar. O padrão é `right`.

```vue
<template>
  <USlideover side="left" title="Slideover with side">
    <NButton label="Open" color="neutral" variant="subtle" />
  
    <template #body>
      <Placeholder class="h-full min-h-48" />
    </template></USlideover>
</template>
```

### Inset `4.3+`

Use a prop `inset` para recuar o Slideover em relação às bordas.

```vue
<template>
  <USlideover side="right" inset title="Slideover with inset">
    <NButton label="Open" color="neutral" variant="subtle" />
  
    <template #body>
      <Placeholder class="min-w-96 min-h-96 size-full" />
    </template></USlideover>
</template>
```

### Transição

Use a prop `transition` para controlar se o Slideover é animado ou não. O padrão é `true`.

```vue
<template>
  <USlideover :transition="false" title="Slideover without transition">
    <NButton label="Open" color="neutral" variant="subtle" />
  
    <template #body>
      <Placeholder class="h-full" />
    </template></USlideover>
</template>
```

### Overlay

Use a prop `overlay` para controlar se o Slideover tem um overlay ou não. O padrão é `true`.

```vue
<template>
  <USlideover :overlay="false" title="Slideover without overlay">
    <NButton label="Open" color="neutral" variant="subtle" />
  
    <template #body>
      <Placeholder class="h-full" />
    </template></USlideover>
</template>
```

### Modal

Use a prop `modal` para controlar se o Slideover bloqueia a interação com o conteúdo externo. O padrão é `true`.

> \[!NOTE]
>
> Quando `modal` é definido como `false`, o overlay é automaticamente desabilitado e o conteúdo externo se torna interativo.

```vue
<template>
  <USlideover :modal="false" title="Slideover interactive">
    <NButton label="Open" color="neutral" variant="subtle" />
  
    <template #body>
      <Placeholder class="h-full" />
    </template></USlideover>
</template>
```

### Dispensável

Use a prop `dismissible` para controlar se o Slideover pode ser dispensado ao clicar fora dele ou pressionar escape. O padrão é `true`.

> \[!NOTE]
>
> Um evento `close:prevent` será emitido quando o usuário tentar fechá-lo.

> \[!TIP]
>
> Você pode combinar `modal: false` com `dismissible: false` para tornar o fundo do Slideover interativo sem fechá-lo.

```vue
<template>
  <USlideover :dismissible="false" modal title="Slideover non-dismissible">
    <NButton label="Open" color="neutral" variant="subtle" />
  
    <template #body>
      <Placeholder class="h-full" />
    </template></USlideover>
</template>
```

### Desmontar `Soon`

Use a prop `unmount-on-hide` para evitar que o conteúdo do Slideover seja desmontado quando ele é fechado. O padrão é `true`.

```vue
<template>
  <USlideover :unmount-on-hide="false" title="Slideover">
    <NButton label="Open" color="neutral" variant="subtle" />
  
    <template #body>
      <Placeholder class="h-full" />
    </template></USlideover>
</template>
```

> \[!NOTE]
>
> Você pode inspecionar o DOM para ver o conteúdo do Slideover sendo renderizado mesmo enquanto ele está fechado.

> \[!TIP]
>
> Quando a prop `portal` é definida como `false`, o conteúdo também é renderizado no servidor. Isso é útil para renderizar um Slideover aberto durante o SSR sem uma piscada no carregamento da página, ou para expor seu conteúdo para SEO.

## Exemplos

### Controlar o estado de abertura

Você pode controlar o estado de abertura usando a prop `default-open` ou a diretiva `v-model:open`.

:component-example{name="slideover-open-example"}

> \[!NOTE]
>
> Neste exemplo, aproveitando o [`defineShortcuts`](https://ui.nitro.news/docs/composables/define-shortcuts), você pode abrir e fechar o Slideover pressionando :kbd{value="O"}.

> \[!TIP]
>
> Isso permite mover o gatilho para fora do Slideover ou removê-lo por completo.

### Uso programático

Você pode usar o composable [`useOverlay`](https://ui.nitro.news/docs/composables/use-overlay) para abrir um Slideover programaticamente.

> \[!WARNING]
>
> Certifique-se de envolver seu app com o componente [`App`](https://ui.nitro.news/docs/components/app), que usa o componente [`OverlayProvider`](https://gitlab.nitro.news/nitro/ui/-/blob/main/src/runtime/components/OverlayProvider.vue){rel="&#x22;nofollow&#x22;"}.

Primeiro, crie um componente de slideover que será aberto programaticamente:

::component-example{prettier :preview='false' name="slideover-example"}
::

> \[!NOTE]
>
> Aqui emitimos um evento `close` quando o slideover é fechado ou dispensado. Você pode emitir qualquer dado por meio do evento `close`, porém o evento precisa ser emitido para que o valor de retorno seja capturado.

Depois, use-o no seu app:

:component-example{name="slideover-programmatic-example"}

> \[!TIP]
>
> Você pode fechar o slideover dentro do componente de slideover emitindo `emit('close')`.

### Slideovers aninhados

Você pode aninhar slideovers uns dentro dos outros.

:component-example{name="slideover-nested-example"}

### Com slot de rodapé

Use o slot `#footer` para adicionar conteúdo após o corpo do Slideover.

:component-example{name="slideover-footer-slot-example"}

## API

### Props

```ts
/**
 * Props for the Slideover component
 */
interface SlideoverProps {
  title?: string | undefined;
  description?: string | undefined;
  /**
   * The content of the slideover.
   */
  content?: (Omit<DialogContentProps, "as" | "asChild" | "forceMount"> & Partial<EmitsToProps<DialogContentImplEmits>>) | undefined;
  /**
   * Render an overlay behind the slideover.
   * @default "true"
   */
  overlay?: boolean | undefined;
  /**
   * Animate the slideover when opening or closing.
   * @default "true"
   */
  transition?: boolean | undefined;
  /**
   * The side of the slideover.
   * @default "\"right\""
   */
  side?: "right" | "top" | "bottom" | "left" | undefined;
  /**
   * Whether to inset the slideover from the edges.
   */
  inset?: boolean | undefined;
  /**
   * Render the slideover in a portal.
   * @default "true"
   */
  portal?: string | boolean | HTMLElement | undefined;
  /**
   * Display a close button to dismiss the slideover.
   * `{ size: 'md', color: 'neutral', variant: 'ghost' }`{lang="ts-type"}
   * @default "true"
   */
  close?: boolean | Omit<ButtonProps, LinkPropsKeys> | undefined;
  /**
   * The icon displayed in the close button.
   */
  closeIcon?: any;
  /**
   * When `false`, the slideover will not close when clicking outside or pressing escape.
   * @default "true"
   */
  dismissible?: boolean | undefined;
  ui?: { overlay?: SlotClass; content?: SlotClass; header?: SlotClass; wrapper?: SlotClass; body?: SlotClass; footer?: SlotClass; title?: SlotClass; description?: SlotClass; close?: SlotClass; loading?: SlotClass; } | undefined;
  /**
   * The controlled open state of the dialog. Can be binded as `v-model:open`.
   */
  open?: boolean | undefined;
  /**
   * The open state of the dialog when it is initially rendered. Use when you do not need to control its open state.
   */
  defaultOpen?: boolean | undefined;
  /**
   * The modality of the dialog When set to `true`, <br>
   * interaction with outside elements will be disabled and only dialog content will be visible to screen readers.
   * @default "true"
   */
  modal?: boolean | undefined;
  /**
   * When set to `false`, the dialog content will not be unmounted when closed, but instead hidden with CSS. <br>
   * Useful for SEO or when you want to improve performance by not remounting the component on every open.
   */
  unmountOnHide?: boolean | undefined;
}
```

### Slots

```ts
/**
 * Slots for the Slideover component
 */
interface SlideoverSlots {
  default(): any;
  content(): any;
  header(): any;
  title(): any;
  description(): any;
  actions(): any;
  close(): any;
  body(): any;
  footer(): any;
}
```

### Emits

```ts
/**
 * Emitted events for the Slideover component
 */
interface SlideoverEmits {
  leave: (payload: []) => void;
  after:leave: (payload: []) => void;
  enter: (payload: []) => void;
  after:enter: (payload: []) => void;
  close:prevent: (payload: []) => void;
  update:open: (payload: [value: boolean]) => void;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    slideover: {
      slots: {
        overlay: 'fixed inset-0 bg-secondary/75',
        content: 'fixed bg-default divide-y divide-default sm:ring ring-default sm:shadow-lg flex flex-col focus:outline-none',
        header: 'flex items-center gap-1.5 p-4 sm:px-6 min-h-(--ui-header-height)',
        wrapper: '',
        body: 'flex-1 overflow-y-auto p-4 sm:p-6',
        footer: 'flex items-center gap-1.5 p-4 sm:px-6',
        title: 'text-highlighted font-semibold',
        description: 'mt-1 text-muted text-sm',
        close: 'absolute top-4 end-4',
        loading: 'w-full h-full flex justify-center items-center'
      },
      variants: {
        side: {
          top: {
            content: ''
          },
          right: {
            content: 'max-w-md'
          },
          bottom: {
            content: ''
          },
          left: {
            content: 'max-w-md'
          }
        },
        inset: {
          true: {
            content: 'rounded-lg'
          }
        },
        transition: {
          true: {
            overlay: 'data-[state=open]:animate-[fade-in_200ms_ease-out] data-[state=closed]:animate-[fade-out_200ms_ease-in]'
          }
        }
      },
      compoundVariants: [
        {
          side: 'top',
          inset: true,
          class: {
            content: 'max-h-[calc(100%-2rem)] inset-x-4 top-4'
          }
        },
        {
          side: 'top',
          inset: false,
          class: {
            content: 'max-h-full inset-x-0 top-0'
          }
        },
        {
          side: 'right',
          inset: true,
          class: {
            content: 'w-[calc(100%-2rem)] inset-y-4 right-4'
          }
        },
        {
          side: 'right',
          inset: false,
          class: {
            content: 'w-full inset-y-0 right-0'
          }
        },
        {
          side: 'bottom',
          inset: true,
          class: {
            content: 'max-h-[calc(100%-2rem)] inset-x-4 bottom-4'
          }
        },
        {
          side: 'bottom',
          inset: false,
          class: {
            content: 'max-h-full inset-x-0 bottom-0'
          }
        },
        {
          side: 'left',
          inset: true,
          class: {
            content: 'w-[calc(100%-2rem)] inset-y-4 left-4'
          }
        },
        {
          side: 'left',
          inset: false,
          class: {
            content: 'w-full inset-y-0 left-0'
          }
        },
        {
          transition: true,
          side: 'top',
          class: {
            content: 'data-[state=open]:animate-[slide-in-from-top_200ms_ease-in-out] data-[state=closed]:animate-[slide-out-to-top_200ms_ease-in-out]'
          }
        },
        {
          transition: true,
          side: 'right',
          class: {
            content: 'data-[state=open]:animate-[slide-in-from-right_200ms_ease-in-out] data-[state=closed]:animate-[slide-out-to-right_200ms_ease-in-out]'
          }
        },
        {
          transition: true,
          side: 'bottom',
          class: {
            content: 'data-[state=open]:animate-[slide-in-from-bottom_200ms_ease-in-out] data-[state=closed]:animate-[slide-out-to-bottom_200ms_ease-in-out]'
          }
        },
        {
          transition: true,
          side: 'left',
          class: {
            content: 'data-[state=open]:animate-[slide-in-from-left_200ms_ease-in-out] data-[state=closed]:animate-[slide-out-to-left_200ms_ease-in-out]'
          }
        }
      ]
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/Slideover.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/slideover.ts).


# Slider

## Uso

Use a diretiva `v-model` para controlar o valor do Slider.

```vue
<script setup lang="ts">
const value = ref(50)
</script>

<template>
  <USlider v-model="value" />
</template>
```

Use a prop `default-value` para definir o valor inicial quando você não precisa controlar o estado.

```vue
<template>
  <USlider :default-value="50" />
</template>
```

### Mín / Máx

Use as props `min` e `max` para definir os valores mínimo e máximo do Slider. O padrão é `0` e `100`.

```vue
<template>
  <USlider :min="0" :max="50" :default-value="50" />
</template>
```

### Etapa

Use a prop `step` para definir o valor de incremento do Slider. O padrão é `1`.

```vue
<template>
  <USlider :step="10" :default-value="50" />
</template>
```

### Múltiplo

Use a diretiva `v-model` ou a prop `default-value` com um array de valores para criar um Slider de intervalo.

```vue
<script setup lang="ts">
const value = ref([
  25,
  75
])
</script>

<template>
  <USlider v-model="value" />
</template>
```

Use a prop `min-steps-between-thumbs` para limitar a distância mínima entre os thumbs.

```vue
<script setup lang="ts">
const value = ref([
  25,
  50,
  75
])
</script>

<template>
  <USlider v-model="value" :min-steps-between-thumbs="10" />
</template>
```

### Orientação

Use a prop `orientation` para alterar a orientação do Slider. O padrão é `horizontal`.

```vue
<template>
  <USlider orientation="vertical" :default-value="50" class="h-48" />
</template>
```

### Cor

Use a prop `color` para alterar a cor do Slider.

```vue
<template>
  <USlider color="neutral" :default-value="50" />
</template>
```

### Tamanho

Use a prop `size` para alterar o tamanho do Slider.

```vue
<template>
  <USlider size="xl" :default-value="50" />
</template>
```

### Tooltip

Use a prop `tooltip` para exibir um [Tooltip](https://ui.nitro.news/docs/components/tooltip) ao redor dos thumbs do Slider com o valor atual. Você pode defini-la como `true` para o comportamento padrão ou passar um objeto para personalizá-la com qualquer propriedade do componente [Tooltip](https://ui.nitro.news/docs/components/tooltip#props).

```vue
<template>
  <USlider :default-value="50" tooltip />
</template>
```

### Desabilitado

Use a prop `disabled` para desabilitar o Slider.

```vue
<template>
  <USlider disabled :default-value="50" />
</template>
```

### Invertido

Use a prop `inverted` para inverter visualmente o Slider.

```vue
<template>
  <USlider inverted :default-value="25" />
</template>
```

## API

### Props

```ts
/**
 * Props for the Slider component
 */
interface SliderProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  size?: "xs" | "sm" | "md" | "lg" | "xl" | undefined;
  color?: "primary" | "secondary" | "accent" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
  /**
   * The orientation of the slider.
   * @default "\"horizontal\""
   */
  orientation?: "horizontal" | "vertical" | undefined;
  /**
   * Display a tooltip around the slider thumbs with the current value.
   * `{ disableClosingTrigger: true }`{lang="ts-type"}
   */
  tooltip?: boolean | TooltipProps | undefined;
  /**
   * The value of the slider when initially rendered. Use when you do not need to control the state of the slider.
   */
  defaultValue?: number | number[] | undefined;
  ui?: { root?: SlotClass; track?: SlotClass; range?: SlotClass; thumb?: SlotClass; } | undefined;
  /**
   * The name of the field. Submitted with its owning form as part of a name/value pair.
   */
  name?: string | undefined;
  /**
   * When `true`, prevents the user from interacting with the slider.
   */
  disabled?: boolean | undefined;
  /**
   * Whether the slider is visually inverted.
   */
  inverted?: boolean | undefined;
  /**
   * The minimum value for the range.
   * @default "0"
   */
  min?: number | undefined;
  /**
   * The maximum value for the range.
   * @default "100"
   */
  max?: number | undefined;
  /**
   * The stepping interval.
   * @default "1"
   */
  step?: number | undefined;
  /**
   * The minimum permitted steps between multiple thumbs.
   */
  minStepsBetweenThumbs?: number | undefined;
  modelValue?: T | undefined;
}
```

### Emits

```ts
/**
 * Emitted events for the Slider component
 */
interface SliderEmits {
  change: (payload: [event: Event]) => void;
  update:modelValue: (payload: [value: T | undefined]) => void;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    slider: {
      slots: {
        root: 'relative flex items-center select-none touch-none',
        track: 'relative bg-accented overflow-hidden rounded-full grow',
        range: 'absolute rounded-full',
        thumb: 'rounded-full bg-default ring-2 focus-visible:outline-3 focus-visible:outline-offset-2'
      },
      variants: {
        color: {
          primary: {
            range: 'bg-primary',
            thumb: 'ring-primary outline-primary/25'
          },
          secondary: {
            range: 'bg-secondary',
            thumb: 'ring-secondary outline-secondary/25'
          },
          accent: {
            range: 'bg-accent',
            thumb: 'ring-accent outline-accent/25'
          },
          success: {
            range: 'bg-success',
            thumb: 'ring-success outline-success/25'
          },
          info: {
            range: 'bg-info',
            thumb: 'ring-info outline-info/25'
          },
          warning: {
            range: 'bg-warning',
            thumb: 'ring-warning outline-warning/25'
          },
          error: {
            range: 'bg-error',
            thumb: 'ring-error outline-error/25'
          },
          neutral: {
            range: 'bg-inverted',
            thumb: 'ring-inverted outline-inverted/25'
          }
        },
        size: {
          xs: {
            thumb: 'size-3'
          },
          sm: {
            thumb: 'size-3.5'
          },
          md: {
            thumb: 'size-4'
          },
          lg: {
            thumb: 'size-4.5'
          },
          xl: {
            thumb: 'size-5'
          }
        },
        orientation: {
          horizontal: {
            root: 'w-full',
            range: 'h-full'
          },
          vertical: {
            root: 'flex-col h-full',
            range: 'w-full'
          }
        },
        disabled: {
          true: {
            root: 'opacity-75 cursor-not-allowed'
          }
        }
      },
      compoundVariants: [
        {
          orientation: 'horizontal',
          size: 'xs',
          class: {
            track: 'h-[6px]'
          }
        },
        {
          orientation: 'horizontal',
          size: 'sm',
          class: {
            track: 'h-[7px]'
          }
        },
        {
          orientation: 'horizontal',
          size: 'md',
          class: {
            track: 'h-[8px]'
          }
        },
        {
          orientation: 'horizontal',
          size: 'lg',
          class: {
            track: 'h-[9px]'
          }
        },
        {
          orientation: 'horizontal',
          size: 'xl',
          class: {
            track: 'h-[10px]'
          }
        },
        {
          orientation: 'vertical',
          size: 'xs',
          class: {
            track: 'w-[6px]'
          }
        },
        {
          orientation: 'vertical',
          size: 'sm',
          class: {
            track: 'w-[7px]'
          }
        },
        {
          orientation: 'vertical',
          size: 'md',
          class: {
            track: 'w-[8px]'
          }
        },
        {
          orientation: 'vertical',
          size: 'lg',
          class: {
            track: 'w-[9px]'
          }
        },
        {
          orientation: 'vertical',
          size: 'xl',
          class: {
            track: 'w-[10px]'
          }
        }
      ],
      defaultVariants: {
        size: 'md',
        color: 'primary'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/Slider.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/slider.ts).


# Stepper

## Uso

Use o componente Stepper para exibir uma lista de itens em um stepper.

```vue
<script setup lang="ts">
import type { StepperItem } from '@nitro/ui'

const items = ref<StepperItem[]>([
  {
    title: "Address",
    description: "Add your address here",
    icon: "i-lucide-house"
  },
  {
    title: "Shipping",
    description: "Set your preferred shipping method",
    icon: "i-lucide-truck"
  },
  {
    title: "Checkout",
    description: "Confirm your order"
  }
])
</script>

<template>
  <UStepper :items="items" />
</template>
```

### Itens

Use a prop `items` como um array de objetos com as seguintes propriedades:

- `title?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `description?: AvatarProps`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `content?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `icon?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `value?: string | number`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `disabled?: boolean`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- [`slot?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}](https://ui.nitro.news/#with-custom-slot)
- `class?: any`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `ui?: { item?: ClassNameValue, container?: ClassNameValue, trigger?: ClassNameValue, indicator?: ClassNameValue, icon?: ClassNameValue, separator?: ClassNameValue, wrapper?: ClassNameValue, title?: ClassNameValue, description?: ClassNameValue }`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

```vue
<script setup lang="ts">
import type { StepperItem } from '@nitro/ui'

const items = ref<StepperItem[]>([
  {
    title: "Address",
    description: "Add your address here",
    icon: "i-lucide-house"
  },
  {
    title: "Shipping",
    description: "Set your preferred shipping method",
    icon: "i-lucide-truck"
  },
  {
    title: "Checkout",
    description: "Confirm your order"
  }
])
</script>

<template>
  <UStepper :items="items" class="w-full" />
</template>
```

> \[!NOTE]
>
> Clique nos itens para navegar pelas etapas.

### Cor

Use a prop `color` para alterar a cor do Stepper.

```vue
<script setup lang="ts">
import type { StepperItem } from '@nitro/ui'

const items = ref<StepperItem[]>([
  {
    title: "Address",
    description: "Add your address here",
    icon: "i-lucide-house"
  },
  {
    title: "Shipping",
    description: "Set your preferred shipping method",
    icon: "i-lucide-truck"
  },
  {
    title: "Checkout",
    description: "Confirm your order"
  }
])
</script>

<template>
  <UStepper color="neutral" :items="items" class="w-full" />
</template>
```

### Tamanho

Use a prop `size` para alterar o tamanho do Stepper.

```vue
<script setup lang="ts">
import type { StepperItem } from '@nitro/ui'

const items = ref<StepperItem[]>([
  {
    title: "Address",
    description: "Add your address here",
    icon: "i-lucide-house"
  },
  {
    title: "Shipping",
    description: "Set your preferred shipping method",
    icon: "i-lucide-truck"
  },
  {
    title: "Checkout",
    description: "Confirm your order"
  }
])
</script>

<template>
  <UStepper size="xl" :items="items" class="w-full" />
</template>
```

### Orientação

Use a prop `orientation` para alterar a orientação do Stepper. O padrão é `horizontal`.

```vue
<script setup lang="ts">
import type { StepperItem } from '@nitro/ui'

const items = ref<StepperItem[]>([
  {
    title: "Address",
    description: "Add your address here",
    icon: "i-lucide-house"
  },
  {
    title: "Shipping",
    description: "Set your preferred shipping method",
    icon: "i-lucide-truck"
  },
  {
    title: "Checkout",
    description: "Confirm your order"
  }
])
</script>

<template>
  <UStepper orientation="vertical" :items="items" class="w-full" />
</template>
```

### Desabilitado

Use a prop `disabled` para desabilitar a navegação pelas etapas.

```vue
<script setup lang="ts">
import type { StepperItem } from '@nitro/ui'

const items = ref<StepperItem[]>([
  {
    title: "Address",
    description: "Add your address here",
    icon: "i-lucide-house"
  },
  {
    title: "Shipping",
    description: "Set your preferred shipping method",
    icon: "i-lucide-truck"
  },
  {
    title: "Checkout",
    description: "Confirm your order"
  }
])
</script>

<template>
  <UStepper disabled :items="items" />
</template>
```

> \[!NOTE]
> See: #with-controls
>
> Isso pode ser útil quando você quer forçar a navegação com controles.

## Exemplos

### Com controles

Você pode adicionar controles adicionais para o stepper usando botões.

:component-example{name="stepper-with-controls-example"}

### Controlar o item ativo

Você pode controlar o item ativo usando a prop `default-value` ou a diretiva `v-model` com o `value` do item. Se nenhum `value` for fornecido, o padrão é o índice.

:component-example{name="stepper-model-value-example"}

> \[!TIP]
>
> Use a prop `value-key` para alterar a chave usada para corresponder os itens quando um `v-model` ou `default-value` é fornecido.

### Com slot de conteúdo

Use o slot `#content` para personalizar o conteúdo de cada item.

:component-example{name="stepper-content-slot-example"}

### Com slot personalizado

Use a propriedade `slot` para personalizar um item específico.

Você terá acesso aos seguintes slots:

- `#{{ item.slot }}`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

:component-example{name="stepper-custom-slot-example"}

## API

### Props

```ts
/**
 * Props for the Stepper component
 */
interface StepperProps {
  items: T[];
  /**
   * The element or component this component should render as.
   */
  as?: any;
  size?: "xs" | "sm" | "md" | "lg" | "xl" | undefined;
  color?: "primary" | "secondary" | "accent" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
  /**
   * The orientation of the stepper.
   * @default "\"horizontal\""
   */
  orientation?: "horizontal" | "vertical" | undefined;
  /**
   * The key used to get the value from the item.
   * @default "\"value\""
   */
  valueKey?: GetItemKeys<T> | undefined;
  /**
   * The value of the step that should be active when initially rendered. Use when you do not need to control the state of the steps.
   */
  defaultValue?: string | number | undefined;
  disabled?: boolean | undefined;
  ui?: { root?: SlotClass; header?: SlotClass; item?: SlotClass; container?: SlotClass; trigger?: SlotClass; indicator?: SlotClass; icon?: SlotClass; separator?: SlotClass; wrapper?: SlotClass; title?: SlotClass; description?: SlotClass; content?: SlotClass; } | undefined;
  /**
   * Whether or not the steps must be completed in order.
   * @default "true"
   */
  linear?: boolean | undefined;
  modelValue?: string | number | undefined;
}
```

### Slots

```ts
/**
 * Slots for the Stepper component
 */
interface StepperSlots {
  indicator(): any;
  wrapper(): any;
  title(): any;
  description(): any;
  content(): any;
}
```

### Emits

```ts
/**
 * Emitted events for the Stepper component
 */
interface StepperEmits {
  next: (payload: [value: T]) => void;
  prev: (payload: [value: T]) => void;
  update:modelValue: (payload: [value: string | number | undefined]) => void;
}
```

### Expose

Você pode acessar a instância tipada do componente usando [`useTemplateRef`](https://vuejs.org/api/composition-api-helpers.html#usetemplateref){rel="&#x22;nofollow&#x22;"}.

```vue
<script setup lang="ts">
const stepper = useTemplateRef('stepper')
</script>

<template>
  <NStepper ref="stepper" />
</template>
```

Isso dará a você acesso ao seguinte:

| Name                                                                                                                          | Type                                                                                                                               |
| ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `next`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"}    | `() => void`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"}   |
| `prev`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"}    | `() => void`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"}   |
| `hasNext`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | `Ref<boolean>`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} |
| `hasPrev`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | `Ref<boolean>`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} |

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    stepper: {
      slots: {
        root: 'flex gap-4',
        header: 'flex',
        item: 'group text-center relative w-full',
        container: 'relative',
        trigger: 'rounded-full font-medium text-center align-middle flex items-center justify-center font-semibold group-data-[state=completed]:text-inverted group-data-[state=active]:text-inverted text-muted bg-elevated focus-visible:outline-2 focus-visible:outline-offset-2',
        indicator: 'flex items-center justify-center size-full',
        icon: 'shrink-0',
        separator: 'absolute rounded-full group-data-[disabled]:opacity-75 bg-accented',
        wrapper: '',
        title: 'font-medium text-default',
        description: 'text-muted text-wrap',
        content: 'size-full'
      },
      variants: {
        orientation: {
          horizontal: {
            root: 'flex-col',
            container: 'flex justify-center',
            separator: 'top-[calc(50%-2px)] h-0.5',
            wrapper: 'mt-1'
          },
          vertical: {
            header: 'flex-col gap-4',
            item: 'flex text-start',
            separator: 'start-[calc(50%-1px)] -bottom-[10px] w-0.5'
          }
        },
        size: {
          xs: {
            trigger: 'size-6 text-xs',
            icon: 'size-3',
            title: 'text-xs',
            description: 'text-xs',
            wrapper: 'mt-1.5'
          },
          sm: {
            trigger: 'size-8 text-sm',
            icon: 'size-4',
            title: 'text-xs',
            description: 'text-xs',
            wrapper: 'mt-2'
          },
          md: {
            trigger: 'size-10 text-base',
            icon: 'size-5',
            title: 'text-sm',
            description: 'text-sm',
            wrapper: 'mt-2.5'
          },
          lg: {
            trigger: 'size-12 text-lg',
            icon: 'size-6',
            title: 'text-base',
            description: 'text-base',
            wrapper: 'mt-3'
          },
          xl: {
            trigger: 'size-14 text-xl',
            icon: 'size-7',
            title: 'text-lg',
            description: 'text-lg',
            wrapper: 'mt-3.5'
          }
        },
        color: {
          primary: {
            trigger: 'group-data-[state=completed]:bg-primary group-data-[state=active]:bg-primary focus-visible:outline-primary',
            separator: 'group-data-[state=completed]:bg-primary'
          },
          secondary: {
            trigger: 'group-data-[state=completed]:bg-secondary group-data-[state=active]:bg-secondary focus-visible:outline-secondary',
            separator: 'group-data-[state=completed]:bg-secondary'
          },
          accent: {
            trigger: 'group-data-[state=completed]:bg-accent group-data-[state=active]:bg-accent focus-visible:outline-accent',
            separator: 'group-data-[state=completed]:bg-accent'
          },
          success: {
            trigger: 'group-data-[state=completed]:bg-success group-data-[state=active]:bg-success focus-visible:outline-success',
            separator: 'group-data-[state=completed]:bg-success'
          },
          info: {
            trigger: 'group-data-[state=completed]:bg-info group-data-[state=active]:bg-info focus-visible:outline-info',
            separator: 'group-data-[state=completed]:bg-info'
          },
          warning: {
            trigger: 'group-data-[state=completed]:bg-warning group-data-[state=active]:bg-warning focus-visible:outline-warning',
            separator: 'group-data-[state=completed]:bg-warning'
          },
          error: {
            trigger: 'group-data-[state=completed]:bg-error group-data-[state=active]:bg-error focus-visible:outline-error',
            separator: 'group-data-[state=completed]:bg-error'
          },
          neutral: {
            trigger: 'group-data-[state=completed]:bg-inverted group-data-[state=active]:bg-inverted focus-visible:outline-inverted',
            separator: 'group-data-[state=completed]:bg-inverted'
          }
        }
      },
      compoundVariants: [
        {
          orientation: 'horizontal',
          size: 'xs',
          class: {
            separator: 'start-[calc(50%+16px)] end-[calc(-50%+16px)]'
          }
        },
        {
          orientation: 'horizontal',
          size: 'sm',
          class: {
            separator: 'start-[calc(50%+20px)] end-[calc(-50%+20px)]'
          }
        },
        {
          orientation: 'horizontal',
          size: 'md',
          class: {
            separator: 'start-[calc(50%+28px)] end-[calc(-50%+28px)]'
          }
        },
        {
          orientation: 'horizontal',
          size: 'lg',
          class: {
            separator: 'start-[calc(50%+32px)] end-[calc(-50%+32px)]'
          }
        },
        {
          orientation: 'horizontal',
          size: 'xl',
          class: {
            separator: 'start-[calc(50%+36px)] end-[calc(-50%+36px)]'
          }
        },
        {
          orientation: 'vertical',
          size: 'xs',
          class: {
            separator: 'top-[30px]',
            item: 'gap-1.5'
          }
        },
        {
          orientation: 'vertical',
          size: 'sm',
          class: {
            separator: 'top-[38px]',
            item: 'gap-2'
          }
        },
        {
          orientation: 'vertical',
          size: 'md',
          class: {
            separator: 'top-[46px]',
            item: 'gap-2.5'
          }
        },
        {
          orientation: 'vertical',
          size: 'lg',
          class: {
            separator: 'top-[54px]',
            item: 'gap-3'
          }
        },
        {
          orientation: 'vertical',
          size: 'xl',
          class: {
            separator: 'top-[62px]',
            item: 'gap-3.5'
          }
        }
      ],
      defaultVariants: {
        size: 'md',
        color: 'primary'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/Stepper.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/stepper.ts).


# Switch

## Uso

Use a diretiva `v-model` para controlar o estado marcado do Switch.

```vue
<script setup lang="ts">
const value = ref(true)
</script>

<template>
  <USwitch v-model="value" />
</template>
```

Use a prop `default-value` para definir o valor inicial quando você não precisa controlar o estado.

```vue
<template>
  <USwitch default-value />
</template>
```

### Label

Use a prop `label` para definir o rótulo do Switch.

```vue
<template>
  <USwitch label="Check me" />
</template>
```

Ao usar a prop `required`, um asterisco é adicionado ao lado do rótulo.

```vue
<template>
  <USwitch required label="Check me" />
</template>
```

### Descrição

Use a prop `description` para definir a descrição do Switch.

```vue
<template>
  <USwitch label="Check me" description="This is a checkbox." />
</template>
```

### Ícone

Use as props `checked-icon` e `unchecked-icon` para definir os ícones do Switch quando marcado e desmarcado.

```vue
<template>
  <USwitch unchecked-icon="i-lucide-x" checked-icon="i-lucide-check" default-value label="Check me" />
</template>
```

### Carregando

Use a prop `loading` para exibir um ícone de carregamento no Switch.

```vue
<template>
  <USwitch loading default-value label="Check me" />
</template>
```

### Ícone de carregamento

Use a prop `loading-icon` para personalizar o ícone de carregamento. O padrão é `i-lucide-loader-circle`.

```vue
<template>
  <USwitch loading loading-icon="i-lucide-loader" default-value label="Check me" />
</template>
```

**Nuxt:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/nuxt#theme
>
> Você pode personalizar esse ícone globalmente no seu `app.config.ts` na chave `ui.icons.loading`.

**Vue:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/vue#theme
>
> Você pode personalizar esse ícone globalmente no seu `vite.config.ts` na chave `ui.icons.loading`.

### Cor

Use a prop `color` para alterar a cor do Switch.

```vue
<template>
  <USwitch color="neutral" default-value label="Check me" />
</template>
```

### Tamanho

Use a prop `size` para alterar o tamanho do Switch.

```vue
<template>
  <USwitch size="xl" default-value label="Check me" />
</template>
```

### Desabilitado

Use a prop `disabled` para desabilitar o Switch.

```vue
<template>
  <USwitch disabled label="Check me" />
</template>
```

## API

### Props

```ts
/**
 * Props for the Switch component
 */
interface SwitchProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  color?: "primary" | "secondary" | "accent" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
  size?: "md" | "xs" | "sm" | "lg" | "xl" | undefined;
  /**
   * Highlight the ring color like a focus state.
   */
  highlight?: boolean | undefined;
  /**
   * When `true`, the loading icon will be displayed.
   */
  loading?: boolean | undefined;
  /**
   * The icon when the `loading` prop is `true`.
   */
  loadingIcon?: any;
  /**
   * Display an icon when the switch is checked.
   */
  checkedIcon?: any;
  /**
   * Display an icon when the switch is unchecked.
   */
  uncheckedIcon?: any;
  label?: string | undefined;
  description?: string | undefined;
  ui?: { root?: SlotClass; base?: SlotClass; container?: SlotClass; thumb?: SlotClass; icon?: SlotClass; wrapper?: SlotClass; label?: SlotClass; description?: SlotClass; } | undefined;
  /**
   * When `true`, prevents the user from interacting with the switch.
   */
  disabled?: boolean | undefined;
  id?: string | undefined;
  /**
   * The name of the field. Submitted with its owning form as part of a name/value pair.
   */
  name?: string | undefined;
  /**
   * When `true`, indicates that the user must set the value before the owning form can be submitted.
   */
  required?: boolean | undefined;
  /**
   * The value given as data when submitted with a `name`.
   */
  value?: string | undefined;
  /**
   * The state of the switch when it is initially rendered. Use when you do not need to control its state.
   */
  defaultValue?: T | undefined;
  /**
   * The controlled state of the switch. Can be bind as `v-model`.
   */
  modelValue?: T | null | undefined;
  /**
   * The value used when the switch is on. Defaults to `true`.
   */
  trueValue?: T | undefined;
  /**
   * The value used when the switch is off. Defaults to `false`.
   */
  falseValue?: T | undefined;
  autofocus?: Booleanish | undefined;
  form?: string | undefined;
  formaction?: string | undefined;
  formenctype?: string | undefined;
  formmethod?: string | undefined;
  formnovalidate?: Booleanish | undefined;
  formtarget?: string | undefined;
}
```

> \[!NOTE]
> See: https\://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attributes
>
> Este componente também suporta todos os atributos HTML nativos de `<button>`.

### Slots

```ts
/**
 * Slots for the Switch component
 */
interface SwitchSlots {
  label(): any;
  description(): any;
}
```

### Emits

```ts
/**
 * Emitted events for the Switch component
 */
interface SwitchEmits {
  change: (payload: [event: Event]) => void;
  update:modelValue: (payload: [payload: T]) => void;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    switch: {
      slots: {
        root: 'relative flex items-start',
        base: [
          'inline-flex items-center shrink-0 rounded-full border-2 border-transparent focus-visible:outline-3 data-[state=unchecked]:bg-accented',
          'transition-[background] duration-200'
        ],
        container: 'flex items-center',
        thumb: 'group pointer-events-none rounded-full bg-default shadow-lg ring-0 transition-transform duration-200 data-[state=unchecked]:translate-x-0 data-[state=unchecked]:rtl:-translate-x-0 flex items-center justify-center',
        icon: [
          'absolute shrink-0 group-data-[state=unchecked]:text-dimmed opacity-0 size-10/12',
          'transition-[color,opacity] duration-200'
        ],
        wrapper: 'ms-2',
        label: 'block font-medium text-default',
        description: 'text-muted'
      },
      variants: {
        color: {
          primary: {
            base: 'data-[state=checked]:bg-primary outline-primary/25',
            icon: 'group-data-[state=checked]:text-primary'
          },
          secondary: {
            base: 'data-[state=checked]:bg-secondary outline-secondary/25',
            icon: 'group-data-[state=checked]:text-secondary'
          },
          accent: {
            base: 'data-[state=checked]:bg-accent outline-accent/25',
            icon: 'group-data-[state=checked]:text-accent'
          },
          success: {
            base: 'data-[state=checked]:bg-success outline-success/25',
            icon: 'group-data-[state=checked]:text-success'
          },
          info: {
            base: 'data-[state=checked]:bg-info outline-info/25',
            icon: 'group-data-[state=checked]:text-info'
          },
          warning: {
            base: 'data-[state=checked]:bg-warning outline-warning/25',
            icon: 'group-data-[state=checked]:text-warning'
          },
          error: {
            base: 'data-[state=checked]:bg-error outline-error/25',
            icon: 'group-data-[state=checked]:text-error'
          },
          neutral: {
            base: 'data-[state=checked]:bg-inverted outline-inverted/25',
            icon: 'group-data-[state=checked]:text-highlighted'
          }
        },
        size: {
          xs: {
            base: 'w-7',
            container: 'h-4',
            thumb: 'size-3 data-[state=checked]:translate-x-3 data-[state=checked]:rtl:-translate-x-3',
            wrapper: 'text-xs'
          },
          sm: {
            base: 'w-8',
            container: 'h-4',
            thumb: 'size-3.5 data-[state=checked]:translate-x-3.5 data-[state=checked]:rtl:-translate-x-3.5',
            wrapper: 'text-xs'
          },
          md: {
            base: 'w-9',
            container: 'h-5',
            thumb: 'size-4 data-[state=checked]:translate-x-4 data-[state=checked]:rtl:-translate-x-4',
            wrapper: 'text-sm'
          },
          lg: {
            base: 'w-10',
            container: 'h-5',
            thumb: 'size-4.5 data-[state=checked]:translate-x-4.5 data-[state=checked]:rtl:-translate-x-4.5',
            wrapper: 'text-sm'
          },
          xl: {
            base: 'w-11',
            container: 'h-6',
            thumb: 'size-5 data-[state=checked]:translate-x-5 data-[state=checked]:rtl:-translate-x-5',
            wrapper: 'text-base'
          }
        },
        checked: {
          true: {
            icon: 'group-data-[state=checked]:opacity-100'
          }
        },
        unchecked: {
          true: {
            icon: 'group-data-[state=unchecked]:opacity-100'
          }
        },
        loading: {
          true: {
            icon: 'animate-spin'
          }
        },
        highlight: {
          true: ''
        },
        required: {
          true: {
            label: "after:content-['*'] after:ms-0.5 after:text-error"
          }
        },
        disabled: {
          true: {
            root: 'opacity-75',
            base: 'cursor-not-allowed',
            label: 'cursor-not-allowed',
            description: 'cursor-not-allowed'
          }
        }
      },
      compoundVariants: [
        {
          color: 'primary',
          highlight: true,
          class: {
            base: 'ring ring-primary'
          }
        },
        {
          color: 'secondary',
          highlight: true,
          class: {
            base: 'ring ring-secondary'
          }
        },
        {
          color: 'accent',
          highlight: true,
          class: {
            base: 'ring ring-accent'
          }
        },
        {
          color: 'success',
          highlight: true,
          class: {
            base: 'ring ring-success'
          }
        },
        {
          color: 'info',
          highlight: true,
          class: {
            base: 'ring ring-info'
          }
        },
        {
          color: 'warning',
          highlight: true,
          class: {
            base: 'ring ring-warning'
          }
        },
        {
          color: 'error',
          highlight: true,
          class: {
            base: 'ring ring-error'
          }
        },
        {
          color: 'neutral',
          highlight: true,
          class: {
            base: 'ring ring-inverted'
          }
        }
      ],
      defaultVariants: {
        color: 'primary',
        size: 'md'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/Switch.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/switch.ts).


# Table

## Uso

O componente Table é construído sobre o [TanStack Table](https://tanstack.com/table/latest){rel="&#x22;nofollow&#x22;"} e usa o composable [useVueTable](https://tanstack.com/table/latest/docs/framework/vue/vue-table#usevuetable){rel="&#x22;nofollow&#x22;"} para oferecer uma API flexível e totalmente type-safe.

Ele renderiza os seus dados em linhas e colunas e suporta ordenação, filtragem, paginação, seleção de linhas, expansão, agrupamento, fixação e virtualização, então você pode construir desde uma tabela de dados simples até um data grid completo.

::component-example{.!p-0 :source='false' name="table-example"}
::

> \[!NOTE]
> See: https\://gitlab.nitro.news/nitro/ui/-/tree/main/docs/app/components/content/examples/table/TableExample.vue
>
> Este exemplo demonstra o caso de uso mais comum do componente `Table`. Confira o código-fonte no GitHub.

### Dados

Use a prop `data` como um array de objetos; as colunas serão geradas com base nas chaves dos objetos.

```vue
<script setup lang="ts">
const data = ref([
  {
    id: "4600",
    date: "2024-03-11T15:30:00",
    status: "paid",
    email: "james.anderson@example.com",
    amount: 594
  },
  {
    id: "4599",
    date: "2024-03-11T10:10:00",
    status: "failed",
    email: "mia.white@example.com",
    amount: 276
  },
  {
    id: "4598",
    date: "2024-03-11T08:50:00",
    status: "refunded",
    email: "william.brown@example.com",
    amount: 315
  },
  {
    id: "4597",
    date: "2024-03-10T19:45:00",
    status: "paid",
    email: "emma.davis@example.com",
    amount: 529
  },
  {
    id: "4596",
    date: "2024-03-10T15:55:00",
    status: "paid",
    email: "ethan.harris@example.com",
    amount: 639
  }
])
</script>

<template>
  <UTable :data="data" class="flex-1" />
</template>
```

### Colunas

Use a prop `columns` como um array de objetos [ColumnDef](https://tanstack.com/table/latest/docs/api/core/column-def){rel="&#x22;nofollow&#x22;"} com propriedades como:

- `accessorKey`: [The key of the row object to use when extracting the value for the column.]{.text-muted}
- `header`: [The header to display for the column. If a string is passed, it can be used as a default for the column ID. If a function is passed, it will be passed a props object for the header and should return the rendered header value (the exact type depends on the adapter being used).]{.text-muted}
- [`footer`](https://ui.nitro.news/#with-column-footer): [The footer to display for the column. Works exactly like header, but is displayed under the table.]{.text-muted}
- `cell`: [The cell to display each row for the column. If a function is passed, it will be passed a props object for the cell and should return the rendered cell value (the exact type depends on the adapter being used).]{.text-muted}
- `meta`: [Extra properties for the column.]{.text-muted}
  - `class`:
    - `td`: [The classes to apply to the `td` element.]{.text-muted}
    - `th`: [The classes to apply to the `th` element.]{.text-muted}
  - `style`:
    - `td`: [The style to apply to the `td` element.]{.text-muted}
    - `th`: [The style to apply to the `th` element.]{.text-muted}
  - [`colspan`](https://ui.nitro.news/#with-column-span):
    - `td`: [The colspan attribute to apply to the `td` element.]{.text-muted}
  - [`rowspan`](https://ui.nitro.news/#with-column-span):
    - `td`: [The rowspan attribute to apply to the `td` element.]{.text-muted}

Para renderizar componentes ou outros elementos HTML, você precisará usar a [função `h`](https://vuejs.org/api/render-function.html#h){rel="&#x22;nofollow&#x22;"} do Vue dentro das props `header` e `cell`. Isso é diferente de outros componentes que usam slots, mas permite mais flexibilidade.

> \[!TIP]
> See: #with-slots
>
> Você também pode usar slots para personalizar o cabeçalho e as células de dados da tabela.

::component-example
---
collapse: true
highlights:
  - 53
  - 108
prettier: true
class: "!p-0"
name: table-columns-example
---
::

> \[!NOTE]
>
> Ao renderizar componentes com `h`, você pode usar a função `resolveComponent` ou importar de `#components`.

### Meta

Use a prop `meta` como um objeto ([TableMeta](https://tanstack.com/table/latest/docs/api/core/table#meta){rel="&#x22;nofollow&#x22;"}) para passar propriedades como:

- `class`:
  - `tr`: [The classes to apply to the `tr` element.]{.text-muted}
- `style`:
  - `tr`: [The style to apply to the `tr` element.]{.text-muted}

::component-example
---
collapse: true
highlights:
  - 128
  - 140
prettier: true
class: "!p-0"
name: table-meta-example
---
::

### Carregando

Use a prop `loading` para exibir um estado de carregamento, a prop `loading-color` para alterar a cor dele e a prop `loading-animation` para alterar a animação dele.

```vue
<script setup lang="ts">
const data = ref([
  {
    id: "4600",
    date: "2024-03-11T15:30:00",
    status: "paid",
    email: "james.anderson@example.com",
    amount: 594
  },
  {
    id: "4599",
    date: "2024-03-11T10:10:00",
    status: "failed",
    email: "mia.white@example.com",
    amount: 276
  },
  {
    id: "4598",
    date: "2024-03-11T08:50:00",
    status: "refunded",
    email: "william.brown@example.com",
    amount: 315
  },
  {
    id: "4597",
    date: "2024-03-10T19:45:00",
    status: "paid",
    email: "emma.davis@example.com",
    amount: 529
  },
  {
    id: "4596",
    date: "2024-03-10T15:55:00",
    status: "paid",
    email: "ethan.harris@example.com",
    amount: 639
  }
])
</script>

<template>
  <UTable loading loading-color="primary" loading-animation="carousel" :data="data" class="flex-1" />
</template>
```

### Fixo

Use a prop `sticky` para tornar o cabeçalho ou o rodapé fixos.

```vue
<script setup lang="ts">
const data = ref([
  {
    id: "4600",
    date: "2024-03-11T15:30:00",
    status: "paid",
    email: "james.anderson@example.com",
    amount: 594
  },
  {
    id: "4599",
    date: "2024-03-11T10:10:00",
    status: "failed",
    email: "mia.white@example.com",
    amount: 276
  },
  {
    id: "4598",
    date: "2024-03-11T08:50:00",
    status: "refunded",
    email: "william.brown@example.com",
    amount: 315
  },
  {
    id: "4597",
    date: "2024-03-10T19:45:00",
    status: "paid",
    email: "emma.davis@example.com",
    amount: 529
  },
  {
    id: "4596",
    date: "2024-03-10T15:55:00",
    status: "paid",
    email: "ethan.harris@example.com",
    amount: 639
  },
  {
    id: "4595",
    date: "2024-03-10T15:55:00",
    status: "paid",
    email: "ethan.harris@example.com",
    amount: 639
  },
  {
    id: "4594",
    date: "2024-03-10T15:55:00",
    status: "paid",
    email: "ethan.harris@example.com",
    amount: 639
  }
])
</script>

<template>
  <UTable sticky :data="data" class="flex-1 max-h-[312px]" />
</template>
```

## Exemplos

### Com ações de linha

Você pode adicionar uma nova coluna que renderiza um componente [DropdownMenu](https://ui.nitro.news/docs/components/dropdown-menu) dentro da `cell` para renderizar ações de linha.

::component-example
---
collapse: true
highlights:
  - 115
  - 141
prettier: true
class: "!p-0"
name: table-row-actions-example
---
::

### Com linhas expansíveis

Você pode adicionar uma nova coluna que renderiza um componente [Button](https://ui.nitro.news/docs/components/button) dentro da `cell` para alternar o estado expansível de uma linha usando as [APIs de Expanding](https://tanstack.com/table/latest/docs/api/features/expanding){rel="&#x22;nofollow&#x22;"} do TanStack Table.

> \[!CAUTION]
>
> Você precisa definir o slot `#expanded` para renderizar o conteúdo expandido, que receberá a linha como parâmetro.

::component-example
---
collapse: true
highlights:
  - 55
  - 72
prettier: true
class: "!p-0"
name: table-row-expandable-example
---
::

> \[!TIP]
>
> Você pode usar a prop `expanded` para controlar o estado expansível das linhas (pode ser vinculada com `v-model`).

> \[!NOTE]
>
> Você também poderia adicionar essa ação ao componente [`DropdownMenu`](https://ui.nitro.news/docs/components/dropdown-menu) dentro da coluna `actions`.

### Com linhas agrupadas

Você pode agrupar as linhas com base no valor de uma coluna e exibir/ocultar as sublinhas por meio de algum botão adicionado à célula usando as [APIs de Grouping](https://tanstack.com/table/latest/docs/api/features/grouping){rel="&#x22;nofollow&#x22;"} do TanStack Table.

#### Partes importantes:

- Add `grouping` prop with an array of column ids you want to group by.
- Add `grouping-options` prop. It must include `getGroupedRowModel`, you can import it from `@tanstack/vue-table` or implement your own.
- Expand rows via `row.toggleExpanded()` method on any cell of the row. Keep in mind, it also toggles `#expanded` slot.
- Use `aggregateFn` on column definition to define how to aggregate the rows.
- `agregatedCell` renderer on column definition only works if there is no `cell` renderer.

::component-example
---
collapse: true
highlights:
  - 157
  - 160
prettier: true
class: "!p-0"
name: table-grouped-rows-example
---
::

### Com fixação de linhas `4.6+`

Você pode adicionar uma coluna que renderiza um componente [Button](https://ui.nitro.news/docs/components/button) dentro da `cell` para alternar o estado de fixação de uma linha usando as [APIs de Row Pinning](https://tanstack.com/table/latest/docs/api/features/row-pinning){rel="&#x22;nofollow&#x22;"} do TanStack Table. Linhas fixadas permanecem no topo ou na base da tabela, independentemente da ordenação ou filtragem.

::component-example
---
collapse: true
highlights:
  - 91
  - 107
  - 160
  - 165
  - 168
overflowHidden: true
prettier: true
class: "!p-0"
name: table-row-pinning-example
---
::

> \[!TIP]
>
> Você pode usar a prop `row-pinning` para controlar o estado de fixação das linhas (pode ser vinculada com `v-model`).

### Com seleção de linhas

Você pode adicionar uma nova coluna que renderiza um componente [Checkbox](https://ui.nitro.news/docs/components/checkbox) dentro do `header` e da `cell` para selecionar linhas usando as [APIs de Row Selection](https://tanstack.com/table/latest/docs/api/features/row-selection){rel="&#x22;nofollow&#x22;"} do TanStack Table.

::component-example
---
collapse: true
highlights:
  - 55
  - 72
prettier: true
class: "!p-0"
name: table-row-selection-example
---
::

> \[!TIP]
>
> Você pode usar a prop `row-selection` para controlar o estado de seleção das linhas (pode ser vinculada com `v-model`).

### Com evento de seleção da linha

Você pode adicionar um listener `@select` para tornar as linhas clicáveis com ou sem uma coluna de checkbox.

> \[!NOTE]
>
> A função handler recebe as instâncias de `Event` e `TableRow` como primeiro e segundo argumentos, respectivamente.

::component-example
---
collapse: true
highlights:
  - 124
  - 131
prettier: true
class: "!p-0"
name: table-row-select-event-example
---
::

> \[!TIP]
>
> Você pode usar isso para navegar até uma página, abrir um modal ou até selecionar a linha manualmente.

### Com evento de menu de contexto da linha

Você pode adicionar um listener `@contextmenu` para tornar as linhas clicáveis com o botão direito e envolver a Table em um componente [ContextMenu](https://ui.nitro.news/docs/components/context-menu) para exibir ações de linha, por exemplo.

> \[!NOTE]
>
> A função handler recebe as instâncias de `Event` e `TableRow` como primeiro e segundo argumentos, respectivamente.

::component-example
---
collapse: true
highlights:
  - 133
  - 173
prettier: true
class: "!p-0"
name: table-row-context-menu-event-example
---
::

### Com evento de hover da linha

Você pode adicionar um listener `@hover` para tornar as linhas sensíveis ao hover e usar um componente [Popover](https://ui.nitro.news/docs/components/popover) ou [Tooltip](https://ui.nitro.news/docs/components/tooltip) para exibir os detalhes da linha, por exemplo.

> \[!NOTE]
>
> A função handler recebe as instâncias de `Event` e `TableRow` como primeiro e segundo argumentos, respectivamente.

::component-example
---
collapse: true
highlights:
  - 129
  - 152
prettier: true
class: "!p-0"
name: table-row-hover-event-example
---
::

> \[!NOTE]
>
> Este exemplo é semelhante ao [exemplo com cursor que acompanha](https://ui.nitro.news/docs/components/popover#with-following-cursor) do Popover e usa um [`refDebounced`](https://vueuse.org/shared/refDebounced/#refdebounced){rel="&#x22;nofollow&#x22;"} para evitar que o Popover abra e feche rápido demais ao mover o cursor de uma linha para outra.

### Com rodapé de coluna

Você pode adicionar uma propriedade `footer` à definição da coluna para renderizar um rodapé para a coluna.

::component-example
---
collapse: true
highlights:
  - 100
  - 112
prettier: true
class: "!p-0"
name: table-column-footer-example
---
::

### Com span de coluna

Você pode usar as propriedades `colspan` e `rowspan` no `meta` da coluna para mesclar células. Essas propriedades aceitam um valor estático ou uma função que recebe a célula e retorna o valor do span.

> \[!NOTE]
>
> Ao usar `rowspan`, as células que são "absorvidas" pelo span de uma linha anterior precisam ser ocultadas visualmente. Use o `meta` `class` com uma função que retorna `'hidden'` para essas células.

::component-example
---
collapse: true
prettier: true
class: "!p-0"
name: table-column-span-example
---
::

### Com ordenação de colunas

Você pode atualizar o `header` de uma coluna para renderizar um componente [Button](https://ui.nitro.news/docs/components/button) dentro do `header` para alternar o estado de ordenação usando as [APIs de Sorting](https://tanstack.com/table/latest/docs/api/features/sorting){rel="&#x22;nofollow&#x22;"} do TanStack Table.

::component-example
---
collapse: true
highlights:
  - 90
  - 105
prettier: true
class: "!p-0"
name: table-column-sorting-example
---
::

> \[!TIP]
>
> Você pode usar a prop `sorting` para controlar o estado de ordenação das colunas (pode ser vinculada com `v-model`).

Você também pode criar um componente reutilizável para tornar o cabeçalho de qualquer coluna ordenável.

::component-example
---
collapse: true
highlights:
  - 110
  - 161
prettier: true
class: "!p-0"
name: table-column-sorting-reusable-example
---
::

> \[!NOTE]
>
> Neste exemplo, usamos uma função para definir o cabeçalho da coluna, mas você também pode criar um componente de verdade.

### Com fixação de colunas

Você pode atualizar o `header` de uma coluna para renderizar um componente [Button](https://ui.nitro.news/docs/components/button) dentro do `header` para alternar o estado de fixação usando as [APIs de Pinning](https://tanstack.com/table/latest/docs/api/features/row-pinning){rel="&#x22;nofollow&#x22;"} do TanStack Table.

> \[!NOTE]
>
> Uma coluna fixada fica fixa no lado esquerdo ou direito da tabela. Ao usar fixação de colunas, você deve definir valores de `size` explícitos para as suas colunas para garantir o tratamento correto da largura das colunas, especialmente com várias colunas fixadas.

::component-example
---
collapse: true
highlights:
  - 108
  - 126
overflowHidden: true
prettier: true
class: "!p-0 overflow-clip"
name: table-column-pinning-example
---
::

> \[!TIP]
>
> Você pode usar a prop `column-pinning` para controlar o estado de fixação das colunas (pode ser vinculada com `v-model`).

### Com visibilidade de colunas

Você pode usar um componente [DropdownMenu](https://ui.nitro.news/docs/components/dropdown-menu) para alternar a visibilidade das colunas usando as [APIs de Column Visibility](https://tanstack.com/table/latest/docs/api/features/column-visibility){rel="&#x22;nofollow&#x22;"} do TanStack Table.

::component-example
---
collapse: true
highlights:
  - 121
  - 146
prettier: true
class: "!p-0"
name: table-column-visibility-example
---
::

> \[!TIP]
>
> Você pode usar a prop `column-visibility` para controlar o estado de visibilidade das colunas (pode ser vinculada com `v-model`).

### Com filtros de coluna

Você pode usar um componente [Input](https://ui.nitro.news/docs/components/input) para filtrar as linhas por coluna usando as [APIs de Column Filtering](https://tanstack.com/table/latest/docs/api/features/column-filtering){rel="&#x22;nofollow&#x22;"} do TanStack Table.

::component-example
---
collapse: true
highlights:
  - 123
  - 128
prettier: true
class: "!p-0"
name: table-column-filters-example
---
::

> \[!TIP]
>
> Você pode usar a prop `column-filters` para controlar o estado dos filtros das colunas (pode ser vinculada com `v-model`).

### Com filtro global

Você pode usar um componente [Input](https://ui.nitro.news/docs/components/input) para filtrar as linhas usando as [APIs de Global Filtering](https://tanstack.com/table/latest/docs/api/features/global-filtering){rel="&#x22;nofollow&#x22;"} do TanStack Table.

::component-example
---
collapse: true
highlights:
  - 116
prettier: true
class: "!p-0"
name: table-global-filter-example
---
::

> \[!TIP]
>
> Você pode usar a prop `global-filter` para controlar o estado do filtro global (pode ser vinculada com `v-model`).

### Com paginação

Você pode usar um componente [Pagination](https://ui.nitro.news/docs/components/pagination) para controlar o estado de paginação usando as [APIs de Pagination](https://tanstack.com/table/latest/docs/api/features/pagination){rel="&#x22;nofollow&#x22;"}.

Há diferentes abordagens de paginação, como explicado no [Guia de Paginação](https://tanstack.com/table/latest/docs/guide/pagination#pagination-guide){rel="&#x22;nofollow&#x22;"}. Neste exemplo, usamos paginação no lado do cliente, então precisamos passar manualmente a função `getPaginationRowModel()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}.

::component-example
---
collapse: true
highlights:
  - 204
  - 209
prettier: true
class: "!p-0"
name: table-pagination-example
---
::

> \[!TIP]
>
> Você pode usar a prop `pagination` para controlar o estado de paginação (pode ser vinculada com `v-model`).

### Com dados buscados

Você pode buscar dados de uma API e usá-los na Table.

::component-example
---
collapse: true
highlights:
  - 15
  - 26
prettier: true
class: "!p-0"
name: table-fetch-example
---
::

> \[!NOTE]
>
> Este exemplo usa `useLazyFetch` com `server: false` para buscar os dados no cliente sem bloquear a renderização inicial. O estado de carregamento verifica os status `pending` e `idle` para exibir um indicador de carregamento antes e durante a busca.

### Com rolagem infinita

Se você usa paginação no lado do servidor, pode usar o composable [`useInfiniteScroll`](https://vueuse.org/core/useInfiniteScroll/#useinfinitescroll){rel="&#x22;nofollow&#x22;"} para carregar mais dados conforme o usuário rola.

::component-example
---
collapse: true
highlights:
  - 72
  - 83
overflowHidden: true
prettier: true
class: "!p-0"
name: table-infinite-scroll-example
---
::

> \[!NOTE]
>
> Este exemplo usa `useLazyFetch` com `server: false` para buscar os dados no cliente sem bloquear a renderização inicial. O estado de carregamento verifica os status `pending` e `idle` para exibir um indicador de carregamento antes e durante a busca. Páginas adicionais são carregadas conforme o usuário rola.

### Com arrastar e soltar

Você pode usar o composable [`useSortable`](https://vueuse.org/integrations/useSortable/){rel="&#x22;nofollow&#x22;"} de [`@vueuse/integrations`](https://vueuse.org/integrations/README.html){rel="&#x22;nofollow&#x22;"} para habilitar a funcionalidade de arrastar e soltar na Table. Essa integração envolve o [Sortable.js](https://sortablejs.github.io/Sortable/){rel="&#x22;nofollow&#x22;"} para oferecer uma experiência de arrastar e soltar fluida.

> \[!NOTE]
>
> Como o ref da tabela não expõe o elemento tbody, adicione uma classe única a ele via a prop `:ui` para mirá-lo com o `useSortable` (ex.: `:ui="{ tbody: 'my-table-tbody' }"`).

::component-example
---
collapse: true
highlights:
  - 81
  - 83
prettier: true
class: "!p-0"
name: table-drag-and-drop-example
---
::

### Com virtualização `4.1+`

Use a prop `virtualize` para habilitar a virtualização em grandes conjuntos de dados, como um booleano ou um objeto com opções como `{ estimateSize: 65, overscan: 12 }`. Você também pode passar outras [opções do TanStack Virtual](https://tanstack.com/virtual/latest/docs/api/virtualizer#optional-options){rel="&#x22;nofollow&#x22;"} para personalizar o comportamento da virtualização. A prop `sticky` funciona em combinação com `virtualize` para manter o cabeçalho ou o rodapé visíveis ao rolar por grandes conjuntos de dados.

> \[!WARNING]
>
> A fixação de linhas não é suportada quando a virtualização está habilitada.

::component-example
---
collapse: true
overflowHidden: true
prettier: true
class: "!p-0"
name: table-virtualize-example
---
::

> \[!NOTE]
>
> É necessária uma restrição de altura na tabela para que a virtualização funcione corretamente (ex.: `class="h-[400px]"`).

### Com elemento de rolagem externo `Soon`

Passe uma função `getScrollElement` na prop `virtualize` para virtualizar em relação a um container de rolagem ancestral em vez do próprio root da tabela. Defina `scrollMargin` como o deslocamento da tabela em relação ao início do elemento de rolagem (ex.: a altura do conteúdo acima dela), para que um cabeçalho e o corpo da tabela compartilhem uma única barra de rolagem.

::component-example
---
collapse: true
overflowHidden: true
prettier: true
class: "!p-0"
name: table-external-scroll-example
---
::

> \[!NOTE]
>
> Nesse modo, o `overflow` do root da tabela é `visible` e o container externo controla a rolagem nos dois eixos, então dê a ele `overflow-auto` (não apenas `overflow-y-auto`) para manter tabelas largas roláveis horizontalmente. Um cabeçalho `sticky` então se ancora a esse container.

### Com dados de árvore

Você pode usar a prop `get-sub-rows` para exibir dados hierárquicos (em árvore) na tabela.
Por exemplo, se os seus objetos de dados têm um array `children`, defina `:get-sub-rows="row => row.children"` para habilitar linhas expansíveis.

::component-example
---
collapse: true
highlights:
  - 175
prettier: true
class: "!p-0"
name: table-tree-data-example
---
::

### Com slots

Você pode usar slots para personalizar o cabeçalho e as células de dados da tabela.

Use o slot `#<column>-header` para personalizar o cabeçalho de uma coluna. Você terá acesso às propriedades `column`, `header` e `table` no escopo do slot.

Use o slot `#<column>-cell` para personalizar a célula de uma coluna. Você terá acesso às propriedades `cell`, `column`, `getValue`, `renderValue`, `row` e `table` no escopo do slot.

::component-example
---
collapse: true
prettier: true
class: "!p-0"
name: table-slots-example
---
::

## API

### Props

```ts
/**
 * Props for the Table component
 */
interface TableProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  data?: T[] | undefined;
  columns?: TableColumn<T, unknown>[] | undefined;
  caption?: string | undefined;
  /**
   * You can pass any object to `options.meta` and access it anywhere the `table` is available via `table.options.meta`.
   */
  meta?: TableMeta<T> | undefined;
  /**
   * Enable virtualization for large datasets.
   * Note: row pinning is not supported when virtualization is enabled.
   * @default "false"
   */
  virtualize?: boolean | (Partial<Omit<VirtualizerOptions<Element, Element>, "count" | "estimateSize" | "overscan">> & { getScrollElement?: (() => Element | null) | undefined; overscan?: number | undefined; estimateSize?: number | ((index: number) => number) | undefined; }) | undefined;
  /**
   * The text to display when the table is empty.
   */
  empty?: string | undefined;
  /**
   * Whether the table should have a sticky header or footer. True for both, 'header' for header only, 'footer' for footer only.
   */
  sticky?: boolean | "header" | "footer" | undefined;
  /**
   * Whether the table should be in loading state.
   */
  loading?: boolean | undefined;
  loadingColor?: "primary" | "secondary" | "accent" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
  loadingAnimation?: "carousel" | "carousel-inverse" | "swing" | "elastic" | undefined;
  /**
   * Use the `watchOptions` prop to customize reactivity (for ex: disable deep watching for changes in your data or limiting the max traversal depth). This can improve performance by reducing unnecessary re-renders, but it should be used with caution as it may lead to unexpected behavior if not managed properly.
   * @default "{
    deep: true
}"
   */
  watchOptions?: WatchOptions<boolean> | undefined;
  globalFilterOptions?: Omit<GlobalFilterOptions<T>, "onGlobalFilterChange"> | undefined;
  columnFiltersOptions?: Omit<ColumnFiltersOptions<T>, "getFilteredRowModel" | "onColumnFiltersChange"> | undefined;
  columnPinningOptions?: Omit<ColumnPinningOptions, "onColumnPinningChange"> | undefined;
  columnSizingOptions?: Omit<ColumnSizingOptions, "onColumnSizingChange" | "onColumnSizingInfoChange"> | undefined;
  visibilityOptions?: Omit<VisibilityOptions, "onColumnVisibilityChange"> | undefined;
  sortingOptions?: Omit<SortingOptions<T>, "getSortedRowModel" | "onSortingChange"> | undefined;
  groupingOptions?: Omit<GroupingOptions, "onGroupingChange"> | undefined;
  expandedOptions?: Omit<ExpandedOptions<T>, "getExpandedRowModel" | "onExpandedChange"> | undefined;
  rowSelectionOptions?: Omit<RowSelectionOptions<T>, "onRowSelectionChange"> | undefined;
  rowPinningOptions?: Omit<RowPinningOptions<T>, "onRowPinningChange"> | undefined;
  paginationOptions?: Omit<PaginationOptions, "onPaginationChange"> | undefined;
  facetedOptions?: FacetedOptions<T> | undefined;
  onSelect?: ((e: Event, row: TableRow<T>) => void) | undefined;
  onHover?: ((e: Event, row: TableRow<T> | null) => void) | undefined;
  onContextmenu?: ((e: Event, row: TableRow<T>) => void) | ((e: Event, row: TableRow<T>) => void)[] | undefined;
  ui?: { root?: SlotClass; base?: SlotClass; caption?: SlotClass; thead?: SlotClass; tbody?: SlotClass; tfoot?: SlotClass; tr?: SlotClass; th?: SlotClass; td?: SlotClass; empty?: SlotClass; loading?: SlotClass; } | undefined;
  state?: Partial<TableState> | undefined;
  onStateChange?: ((updater: Updater<TableState>) => void) | undefined;
  renderFallbackValue?: any;
  /**
   * An array of extra features that you can add to the table instance.
   */
  _features?: TableFeature<any>[] | undefined;
  /**
   * Set this option to override any of the `autoReset...` feature options.
   */
  autoResetAll?: boolean | undefined;
  /**
   * Set this option to `true` to output all debugging information to the console.
   */
  debugAll?: boolean | undefined;
  /**
   * Set this option to `true` to output cell debugging information to the console.
   */
  debugCells?: boolean | undefined;
  /**
   * Set this option to `true` to output column debugging information to the console.
   */
  debugColumns?: boolean | undefined;
  /**
   * Set this option to `true` to output header debugging information to the console.
   */
  debugHeaders?: boolean | undefined;
  /**
   * Set this option to `true` to output row debugging information to the console.
   */
  debugRows?: boolean | undefined;
  /**
   * Set this option to `true` to output table debugging information to the console.
   */
  debugTable?: boolean | undefined;
  /**
   * Default column options to use for all column defs supplied to the table.
   */
  defaultColumn?: Partial<ColumnDef<T, unknown>> | undefined;
  /**
   * This optional function is used to derive a unique ID for any given row. If not provided the rows index is used (nested rows join together with `.` using their grandparents' index eg. `index.index.index`). If you need to identify individual rows that are originating from any server-side operations, it's suggested you use this function to return an ID that makes sense regardless of network IO/ambiguity eg. a userId, taskId, database ID field, etc.
   */
  getRowId?: ((originalRow: T, index: number, parent?: Row<T> | undefined) => string) | undefined;
  /**
   * This optional function is used to access the sub rows for any given row. If you are using nested rows, you will need to use this function to return the sub rows object (or undefined) from the row.
   */
  getSubRows?: ((originalRow: T, index: number) => T[] | undefined) | undefined;
  /**
   * Use this option to optionally pass initial state to the table. This state will be used when resetting various table states either automatically by the table (eg. `options.autoResetPageIndex`) or via functions like `table.resetRowSelection()`. Most reset function allow you optionally pass a flag to reset to a blank/default state instead of the initial state.
   * 
   * Table state will not be reset when this object changes, which also means that the initial state object does not need to be stable.
   */
  initialState?: InitialTableState | undefined;
  /**
   * This option is used to optionally implement the merging of table options.
   */
  mergeOptions?: ((defaultOptions: TableOptions<T>, options: Partial<TableOptions<T>>) => TableOptions<T>) | undefined;
  cellpadding?: Numberish | undefined;
  cellspacing?: Numberish | undefined;
  summary?: string | undefined;
  width?: Numberish | undefined;
  globalFilter?: string | undefined;
  columnFilters?: ColumnFiltersState | undefined;
  columnOrder?: ColumnOrderState | undefined;
  columnVisibility?: VisibilityState | undefined;
  columnPinning?: ColumnPinningState | undefined;
  columnSizing?: ColumnSizingState | undefined;
  columnSizingInfo?: ColumnSizingInfoState | undefined;
  rowSelection?: RowSelectionState | undefined;
  rowPinning?: RowPinningState | undefined;
  sorting?: SortingState | undefined;
  grouping?: GroupingState | undefined;
  expanded?: ExpandedState | undefined;
  pagination?: PaginationState | undefined;
}
```

> \[!NOTE]
> See: https\://developer.mozilla.org/en-US/docs/Web/HTML/Element/table#attributes
>
> Este componente também suporta todos os atributos HTML nativos de `<table>`.

### Slots

```ts
/**
 * Slots for the Table component
 */
interface TableSlots {
  expanded(): any;
  empty(): any;
  loading(): any;
  caption(): any;
  body-top(): any;
  body-bottom(): any;
}
```

### Expose

Você pode acessar a instância tipada do componente usando [`useTemplateRef`](https://vuejs.org/api/composition-api-helpers.html#usetemplateref){rel="&#x22;nofollow&#x22;"}.

```vue
<script setup lang="ts">
const table = useTemplateRef('table')
</script>

<template>
  <NTable ref="table" />
</template>
```

Isso dará a você acesso ao seguinte:

| Name                                                                                                                           | Type                                                                                                                                                                                                                       |
| ------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tableRef`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | `Ref<HTMLTableElement | null>`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"}                                                                         |
| `tableApi`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | [`Table`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"}](https://tanstack.com/table/latest/docs/api/core/table#table-api){rel="&#x22;nofollow&#x22;"} |

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    table: {
      slots: {
        root: 'relative overflow-auto outline-accent/25 focus-visible:outline-3',
        base: 'min-w-full overflow-clip',
        caption: 'sr-only',
        thead: 'relative',
        tbody: 'isolate [&>tr[data-selectable=true]:hover>td]:bg-neutral-100 [&>tr]:data-[selectable=true]:focus-visible:outline-accent [&>tr:nth-child(even)>td]:bg-neutral-50',
        tfoot: 'relative',
        tr: 'data-[selected=true]:bg-accented',
        th: 'px-8 py-3.5 text-lg text-secondary text-left rtl:text-right font-semibold data-[sortable=true]:px-4 bg-clip-padding',
        td: 'px-8 py-4 text-base whitespace-nowrap not-last:border-r border-default bg-clip-padding',
        empty: 'py-6 text-center text-sm text-muted',
        loading: 'py-6 text-center'
      },
      variants: {
        pinned: {
          true: {
            th: 'sticky bg-default z-1',
            td: 'sticky bg-default z-1'
          }
        },
        sticky: {
          true: {
            thead: 'sticky top-0 inset-x-0 bg-default z-1',
            tfoot: 'sticky bottom-0 inset-x-0 bg-default z-1'
          },
          header: {
            thead: 'sticky top-0 inset-x-0 bg-default z-1'
          },
          footer: {
            tfoot: 'sticky bottom-0 inset-x-0 bg-default z-1'
          }
        },
        loading: {
          true: {
            thead: 'after:absolute after:z-1 after:h-px'
          }
        },
        empty: {
          true: {
            thead: 'hidden',
            tfoot: 'hidden'
          }
        },
        externalScroll: {
          true: {
            root: 'overflow-visible'
          }
        },
        loadingAnimation: {
          carousel: '',
          'carousel-inverse': '',
          swing: '',
          elastic: ''
        },
        loadingColor: {
          primary: '',
          secondary: '',
          accent: '',
          success: '',
          info: '',
          warning: '',
          error: '',
          neutral: ''
        }
      },
      compoundVariants: [
        {
          loading: true,
          loadingColor: 'primary',
          class: {
            thead: 'after:bg-primary'
          }
        },
        {
          loading: true,
          loadingColor: 'secondary',
          class: {
            thead: 'after:bg-secondary'
          }
        },
        {
          loading: true,
          loadingColor: 'accent',
          class: {
            thead: 'after:bg-accent'
          }
        },
        {
          loading: true,
          loadingColor: 'success',
          class: {
            thead: 'after:bg-success'
          }
        },
        {
          loading: true,
          loadingColor: 'info',
          class: {
            thead: 'after:bg-info'
          }
        },
        {
          loading: true,
          loadingColor: 'warning',
          class: {
            thead: 'after:bg-warning'
          }
        },
        {
          loading: true,
          loadingColor: 'error',
          class: {
            thead: 'after:bg-error'
          }
        },
        {
          loading: true,
          loadingColor: 'neutral',
          class: {
            thead: 'after:bg-inverted'
          }
        },
        {
          loading: true,
          loadingAnimation: 'carousel',
          class: {
            thead: 'after:animate-[carousel_2s_ease-in-out_infinite] rtl:after:animate-[carousel-rtl_2s_ease-in-out_infinite]'
          }
        },
        {
          loading: true,
          loadingAnimation: 'carousel-inverse',
          class: {
            thead: 'after:animate-[carousel-inverse_2s_ease-in-out_infinite] rtl:after:animate-[carousel-inverse-rtl_2s_ease-in-out_infinite]'
          }
        },
        {
          loading: true,
          loadingAnimation: 'swing',
          class: {
            thead: 'after:animate-[swing_2s_ease-in-out_infinite]'
          }
        },
        {
          loading: true,
          loadingAnimation: 'elastic',
          class: {
            thead: 'after:animate-[elastic_2s_ease-in-out_infinite]'
          }
        }
      ],
      defaultVariants: {
        loadingColor: 'accent',
        loadingAnimation: 'carousel'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/Table.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/table.ts).


# Tabs

## Uso

Use o componente Tabs para exibir uma lista de itens em abas.

::component-example
---
collapse: true
prettier: true
props:
  class: w-full
name: tabs-example
---
::

### Itens

Use a prop `items` como um array de objetos com as seguintes propriedades:

- `label?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `icon?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `avatar?: AvatarProps`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `badge?: string | number | BadgeProps`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `content?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `value?: string | number`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `disabled?: boolean`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- [`slot?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}](https://ui.nitro.news/#with-custom-slot)
- `class?: any`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `ui?: { trigger?: ClassNameValue, leadingIcon?: ClassNameValue, leadingAvatar?: ClassNameValue, leadingAvatarSize?: ClassNameValue, label?: ClassNameValue, trailingBadge?: ClassNameValue, trailingBadgeSize?: ClassNameValue, content?: ClassNameValue }`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

```vue
<script setup lang="ts">
import type { TabsItem } from '@nitro/ui'

const items = ref<TabsItem[]>([
  {
    label: "Account",
    icon: "i-lucide-user",
    content: "This is the account content."
  },
  {
    label: "Password",
    icon: "i-lucide-lock",
    content: "This is the password content."
  }
])
</script>

<template>
  <UTabs :items="items" class="w-full" />
</template>
```

### Conteúdo

Defina a prop `content` como `false` para transformar o Tabs em um controle apenas de alternância, sem exibir nenhum conteúdo. O padrão é `true`.

```vue
<script setup lang="ts">
import type { TabsItem } from '@nitro/ui'

const items = ref<TabsItem[]>([
  {
    label: "Account",
    icon: "i-lucide-user",
    content: "This is the account content."
  },
  {
    label: "Password",
    icon: "i-lucide-lock",
    content: "This is the password content."
  }
])
</script>

<template>
  <UTabs :content="false" :items="items" class="w-full" />
</template>
```

### Desmontar

Use a prop `unmount-on-hide` para evitar que o conteúdo seja desmontado quando o Tabs é recolhido. O padrão é `true`.

```vue
<script setup lang="ts">
import type { TabsItem } from '@nitro/ui'

const items = ref<TabsItem[]>([
  {
    label: "Account",
    icon: "i-lucide-user",
    content: "This is the account content."
  },
  {
    label: "Password",
    icon: "i-lucide-lock",
    content: "This is the password content."
  }
])
</script>

<template>
  <UTabs :unmount-on-hide="false" :items="items" class="w-full" />
</template>
```

> \[!NOTE]
>
> Você pode inspecionar o DOM para ver o conteúdo de cada item sendo renderizado.

### Cor

Use a prop `color` para alterar a cor do Tabs.

```vue
<script setup lang="ts">
import type { TabsItem } from '@nitro/ui'

const items = ref<TabsItem[]>([
  {
    label: "Account"
  },
  {
    label: "Password"
  }
])
</script>

<template>
  <UTabs color="neutral" :content="false" :items="items" class="w-full" />
</template>
```

### Variante

Use a prop `variant` para alterar a variante do Tabs.

```vue
<script setup lang="ts">
import type { TabsItem } from '@nitro/ui'

const items = ref<TabsItem[]>([
  {
    label: "Account"
  },
  {
    label: "Password"
  }
])
</script>

<template>
  <UTabs color="neutral" variant="link" :content="false" :items="items" class="w-full" />
</template>
```

### Tamanho

Use a prop `size` para alterar o tamanho do Tabs.

```vue
<script setup lang="ts">
import type { TabsItem } from '@nitro/ui'

const items = ref<TabsItem[]>([
  {
    label: "Account"
  },
  {
    label: "Password"
  }
])
</script>

<template>
  <UTabs size="md" variant="pill" :content="false" :items="items" class="w-full" />
</template>
```

### Orientação

Use a prop `orientation` para alterar a orientação do Tabs. O padrão é `horizontal`.

```vue
<script setup lang="ts">
import type { TabsItem } from '@nitro/ui'

const items = ref<TabsItem[]>([
  {
    label: "Account"
  },
  {
    label: "Password"
  }
])
</script>

<template>
  <UTabs orientation="vertical" variant="pill" :content="false" :items="items" class="w-full" />
</template>
```

## Exemplos

### Controlar o item ativo

Você pode controlar o item ativo usando a prop `default-value` ou a diretiva `v-model` com o `value` do item. Se nenhum `value` for fornecido, o padrão é o índice **como string**.

:component-example{name="tabs-model-value-example"}

> \[!TIP]
>
> Use a prop `value-key` para alterar a chave usada para corresponder os itens quando um `v-model` ou `default-value` é fornecido.

### Com query da rota

Você pode controlar o item ativo por um parâmetro de query da URL, usando `route.query.tab` como o `value` do item.

:component-example{name="tabs-route-query-example"}

### Com slot de conteúdo

Use o slot `#content` para personalizar o conteúdo de cada item.

:component-example{name="tabs-content-slot-example"}

### Com barra de abas inferior

Use a prop `ui` para transformar o Tabs em uma barra de abas inferior no estilo mobile, com ícones e rótulos pequenos, semelhante ao YouTube ou Instagram.

::component-example{collapse name="tabs-bottom-tab-bar-example"}
::

### Com slot personalizado

Use a propriedade `slot` para personalizar um item específico.

Você terá acesso aos seguintes slots:

- `#{{ item.slot }}`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

::component-example{collapse name="tabs-custom-slot-example"}
::

## API

### Props

```ts
/**
 * Props for the Tabs component
 */
interface TabsProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  items?: T[] | undefined;
  color?: "primary" | "secondary" | "accent" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
  variant?: "pill" | "link" | undefined;
  size?: "sm" | "xs" | "md" | "lg" | "xl" | undefined;
  /**
   * The orientation of the tabs.
   * @default "\"horizontal\""
   */
  orientation?: DataOrientation | undefined;
  /**
   * The content of the tabs, can be disabled to prevent rendering the content.
   * @default "true"
   */
  content?: boolean | undefined;
  /**
   * The key used to get the label from the item.
   * @default "\"label\""
   */
  labelKey?: GetItemKeys<T> | undefined;
  ui?: { root?: SlotClass; list?: SlotClass; indicator?: SlotClass; trigger?: SlotClass; leadingIcon?: SlotClass; leadingAvatar?: SlotClass; leadingAvatarSize?: SlotClass; label?: SlotClass; trailingBadge?: SlotClass; trailingBadgeSize?: SlotClass; content?: SlotClass; } | undefined;
  /**
   * The value of the tab that should be active when initially rendered. Use when you do not need to control the state of the tabs
   * @default "\"0\""
   */
  defaultValue?: string | number | undefined;
  /**
   * The controlled value of the tab to activate. Can be bind as `v-model`.
   */
  modelValue?: string | number | undefined;
  /**
   * Whether a tab is activated automatically (on focus) or manually (on click).
   */
  activationMode?: "automatic" | "manual" | undefined;
  /**
   * When `true`, the element will be unmounted on closed state.
   * @default "true"
   */
  unmountOnHide?: boolean | undefined;
}
```

### Slots

```ts
/**
 * Slots for the Tabs component
 */
interface TabsSlots {
  leading(): any;
  default(): any;
  trailing(): any;
  content(): any;
  list-leading(): any;
  list-trailing(): any;
}
```

### Emits

```ts
/**
 * Emitted events for the Tabs component
 */
interface TabsEmits {
  update:modelValue: (payload: [payload: string | number]) => void;
}
```

### Expose

Ao acessar o componente por meio de um template ref, você pode usar o seguinte:

| Name                                                                                                                              | Type                                                                                                                                                 |
| --------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `triggersRef`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | `Ref<ComponentPublicInstance[]>`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} |

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    tabs: {
      slots: {
        root: 'flex items-center gap-2',
        list: 'relative flex p-1 group',
        indicator: 'absolute transition-[translate,width] duration-200',
        trigger: [
          'group relative inline-flex items-center min-w-0 data-[state=inactive]:text-muted hover:data-[state=inactive]:not-disabled:text-default font-medium rounded-md disabled:cursor-not-allowed disabled:opacity-75',
          'transition-colors'
        ],
        leadingIcon: 'shrink-0',
        leadingAvatar: 'shrink-0',
        leadingAvatarSize: '',
        label: 'truncate',
        trailingBadge: 'shrink-0',
        trailingBadgeSize: 'sm',
        content: 'focus:outline-none w-full'
      },
      variants: {
        color: {
          primary: '',
          secondary: '',
          accent: '',
          success: '',
          info: '',
          warning: '',
          error: '',
          neutral: ''
        },
        variant: {
          pill: {
            list: 'bg-elevated rounded-lg',
            trigger: 'grow',
            indicator: 'rounded-md shadow-xs'
          },
          link: {
            list: 'border-default',
            indicator: 'rounded-full',
            trigger: 'focus:outline-none'
          }
        },
        orientation: {
          horizontal: {
            root: 'flex-col',
            list: 'w-full',
            indicator: 'left-0 w-(--reka-tabs-indicator-size) translate-x-(--reka-tabs-indicator-position)',
            trigger: 'justify-center'
          },
          vertical: {
            list: 'flex-col',
            indicator: 'top-0 h-(--reka-tabs-indicator-size) translate-y-(--reka-tabs-indicator-position)'
          }
        },
        size: {
          xs: {
            trigger: 'px-2 py-1 text-xs gap-1',
            leadingIcon: 'size-4',
            leadingAvatarSize: '3xs'
          },
          sm: {
            trigger: 'px-2.5 py-1.5 text-xs gap-1.5',
            leadingIcon: 'size-4',
            leadingAvatarSize: '3xs'
          },
          md: {
            trigger: 'px-3 py-1.5 text-sm gap-1.5',
            leadingIcon: 'size-5',
            leadingAvatarSize: '2xs'
          },
          lg: {
            trigger: 'px-3 py-2 text-sm gap-2',
            leadingIcon: 'size-5',
            leadingAvatarSize: '2xs'
          },
          xl: {
            trigger: 'px-3 py-2 text-base gap-2',
            leadingIcon: 'size-6',
            leadingAvatarSize: 'xs'
          }
        }
      },
      compoundVariants: [
        {
          orientation: 'horizontal',
          variant: 'pill',
          class: {
            indicator: 'inset-y-1'
          }
        },
        {
          orientation: 'horizontal',
          variant: 'link',
          class: {
            list: 'border-b -mb-px',
            indicator: '-bottom-px h-px'
          }
        },
        {
          orientation: 'vertical',
          variant: 'pill',
          class: {
            indicator: 'inset-x-1',
            list: 'items-center'
          }
        },
        {
          orientation: 'vertical',
          variant: 'link',
          class: {
            list: 'border-s -ms-px',
            indicator: '-start-px w-px'
          }
        },
        {
          color: 'primary',
          variant: 'pill',
          class: {
            indicator: 'bg-primary',
            trigger: 'data-[state=active]:text-inverted focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary'
          }
        },
        {
          color: 'secondary',
          variant: 'pill',
          class: {
            indicator: 'bg-secondary',
            trigger: 'data-[state=active]:text-inverted focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-secondary'
          }
        },
        {
          color: 'accent',
          variant: 'pill',
          class: {
            indicator: 'bg-accent',
            trigger: 'data-[state=active]:text-inverted focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-accent'
          }
        },
        {
          color: 'success',
          variant: 'pill',
          class: {
            indicator: 'bg-success',
            trigger: 'data-[state=active]:text-inverted focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-success'
          }
        },
        {
          color: 'info',
          variant: 'pill',
          class: {
            indicator: 'bg-info',
            trigger: 'data-[state=active]:text-inverted focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-info'
          }
        },
        {
          color: 'warning',
          variant: 'pill',
          class: {
            indicator: 'bg-warning',
            trigger: 'data-[state=active]:text-inverted focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-warning'
          }
        },
        {
          color: 'error',
          variant: 'pill',
          class: {
            indicator: 'bg-error',
            trigger: 'data-[state=active]:text-inverted focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-error'
          }
        },
        {
          color: 'neutral',
          variant: 'pill',
          class: {
            indicator: 'bg-inverted',
            trigger: 'data-[state=active]:text-inverted focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-inverted'
          }
        },
        {
          color: 'primary',
          variant: 'link',
          class: {
            indicator: 'bg-primary',
            trigger: 'data-[state=active]:text-primary focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-primary'
          }
        },
        {
          color: 'secondary',
          variant: 'link',
          class: {
            indicator: 'bg-secondary',
            trigger: 'data-[state=active]:text-secondary focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-secondary'
          }
        },
        {
          color: 'accent',
          variant: 'link',
          class: {
            indicator: 'bg-accent',
            trigger: 'data-[state=active]:text-accent focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-accent'
          }
        },
        {
          color: 'success',
          variant: 'link',
          class: {
            indicator: 'bg-success',
            trigger: 'data-[state=active]:text-success focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-success'
          }
        },
        {
          color: 'info',
          variant: 'link',
          class: {
            indicator: 'bg-info',
            trigger: 'data-[state=active]:text-info focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-info'
          }
        },
        {
          color: 'warning',
          variant: 'link',
          class: {
            indicator: 'bg-warning',
            trigger: 'data-[state=active]:text-warning focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-warning'
          }
        },
        {
          color: 'error',
          variant: 'link',
          class: {
            indicator: 'bg-error',
            trigger: 'data-[state=active]:text-error focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-error'
          }
        },
        {
          color: 'neutral',
          variant: 'link',
          class: {
            indicator: 'bg-inverted',
            trigger: 'data-[state=active]:text-highlighted focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-inverted'
          }
        }
      ],
      defaultVariants: {
        color: 'primary',
        variant: 'pill',
        size: 'md'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/Tabs.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/tabs.ts).


# Textarea

## Uso

Use a diretiva `v-model` para controlar o valor do Textarea.

```vue
<script setup lang="ts">
const value = ref("")
</script>

<template>
  <UTextarea />
</template>
```

### Linhas

Use a prop `rows` para definir o número de linhas. O padrão é `3`.

```vue
<template>
  <UTextarea :rows="12" />
</template>
```

### Placeholder

Use a prop `placeholder` para definir um texto de placeholder.

```vue
<template>
  <UTextarea placeholder="Type something..." />
</template>
```

### Redimensionamento automático

Use a prop `autoresize` para habilitar o redimensionamento automático da altura do Textarea.

```vue
<script setup lang="ts">
const value = ref("This is a long text that will autoresize the height of the Textarea.")
</script>

<template>
  <UTextarea v-model="value" autoresize />
</template>
```

Use a prop `maxrows` para definir o número máximo de linhas ao redimensionar automaticamente. Se definido como `0`, o Textarea cresce indefinidamente.

```vue
<script setup lang="ts">
const value = ref("This is a long text that will autoresize the height of the Textarea with a maximum of 4 rows.")
</script>

<template>
  <UTextarea v-model="value" :maxrows="4" autoresize />
</template>
```

### Cor

Use a prop `color` para alterar a cor do ring quando o Textarea está em foco.

```vue
<template>
  <UTextarea color="neutral" highlight placeholder="Type something..." />
</template>
```

> \[!NOTE]
>
> A prop `highlight` é usada aqui para mostrar o estado de foco. Ela é usada internamente quando ocorre um erro de validação.

### Variante

Use a prop `variant` para alterar a variante do Textarea.

```vue
<template>
  <UTextarea color="neutral" variant="subtle" :highlight="false" placeholder="Type something..." />
</template>
```

### Tamanho

Use a prop `size` para alterar o tamanho do Textarea.

```vue
<template>
  <UTextarea size="xl" placeholder="Type something..." />
</template>
```

### Ícone

Use a prop `icon` para exibir um [Icon](https://ui.nitro.news/docs/components/icon) dentro do Textarea.

```vue
<template>
  <UTextarea icon="i-lucide-search" size="md" variant="outline" placeholder="Search..." :rows="1" />
</template>
```

Use as props `leading` e `trailing` para definir a posição do ícone ou as props `leading-icon` e `trailing-icon` para definir um ícone diferente para cada posição.

```vue
<template>
  <UTextarea trailing-icon="i-lucide-at-sign" placeholder="Enter your email" size="md" :rows="1" />
</template>
```

### Avatar

Use a prop `avatar` para exibir um [Avatar](https://ui.nitro.news/docs/components/avatar) dentro do Textarea.

```vue
<template>
  <UTextarea :avatar="{
  src: 'https://github.com/nuxt.png',
  loading: 'lazy'
}" size="md" variant="outline" placeholder="Search..." :rows="1" />
</template>
```

### Carregando

Use a prop `loading` para exibir um ícone de carregamento no Textarea.

```vue
<template>
  <UTextarea loading :trailing="false" placeholder="Search..." :rows="1" />
</template>
```

### Ícone de carregamento

Use a prop `loading-icon` para personalizar o ícone de carregamento. O padrão é `i-lucide-loader-circle`.

```vue
<template>
  <UTextarea loading loading-icon="i-lucide-loader" placeholder="Search..." :rows="1" />
</template>
```

**Nuxt:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/nuxt#theme
>
> Você pode personalizar esse ícone globalmente no seu `app.config.ts` na chave `ui.icons.loading`.

**Vue:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/vue#theme
>
> Você pode personalizar esse ícone globalmente no seu `vite.config.ts` na chave `ui.icons.loading`.

### Desabilitado

Use a prop `disabled` para desabilitar o Textarea.

```vue
<template>
  <UTextarea disabled placeholder="Type something..." />
</template>
```

## API

### Props

```ts
/**
 * Props for the Textarea component
 */
interface TextareaProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  id?: string | undefined;
  name?: string | undefined;
  /**
   * The placeholder text when the textarea is empty.
   */
  placeholder?: string | undefined;
  color?: "primary" | "secondary" | "accent" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
  variant?: "outline" | "soft" | "subtle" | "ghost" | "none" | undefined;
  size?: "xs" | "sm" | "md" | "lg" | "xl" | undefined;
  required?: boolean | undefined;
  autofocus?: boolean | undefined;
  /**
   * @default "0"
   */
  autofocusDelay?: number | undefined;
  autoresize?: boolean | undefined;
  /**
   * @default "0"
   */
  autoresizeDelay?: number | undefined;
  disabled?: boolean | undefined;
  /**
   * @default "3"
   */
  rows?: number | undefined;
  /**
   * @default "0"
   */
  maxrows?: number | undefined;
  /**
   * Highlight the ring color like a focus state.
   */
  highlight?: boolean | undefined;
  /**
   * Keep the mobile text size on all breakpoints.
   */
  fixed?: boolean | undefined;
  defaultValue?: _Number<_Optional<_Nullable<T, Mod>, Mod>, Mod> | undefined;
  modelValue?: _Number<_Optional<_Nullable<T, Mod>, Mod>, Mod> | undefined;
  modelModifiers?: Mod | undefined;
  ui?: { root?: SlotClass; base?: SlotClass; leading?: SlotClass; leadingIcon?: SlotClass; leadingAvatar?: SlotClass; leadingAvatarSize?: SlotClass; trailing?: SlotClass; trailingIcon?: SlotClass; } | undefined;
  /**
   * Display an icon based on the `leading` and `trailing` props.
   */
  icon?: any;
  /**
   * Display an avatar on the left side.
   */
  avatar?: AvatarProps | undefined;
  /**
   * When `true`, the icon will be displayed on the left side.
   */
  leading?: boolean | undefined;
  /**
   * Display an icon on the left side.
   */
  leadingIcon?: any;
  /**
   * When `true`, the icon will be displayed on the right side.
   */
  trailing?: boolean | undefined;
  /**
   * Display an icon on the right side.
   */
  trailingIcon?: any;
  /**
   * When `true`, the loading icon will be displayed.
   */
  loading?: boolean | undefined;
  /**
   * The icon when the `loading` prop is `true`.
   */
  loadingIcon?: any;
  autocomplete?: string | undefined;
  cols?: Numberish | undefined;
  dirname?: string | undefined;
  form?: string | undefined;
  maxlength?: Numberish | undefined;
  minlength?: Numberish | undefined;
  readonly?: Booleanish | undefined;
  wrap?: string | undefined;
}
```

> \[!NOTE]
> See: https\://developer.mozilla.org/en-US/docs/Web/HTML/Element/textarea#attributes
>
> Este componente também suporta todos os atributos HTML nativos de `<textarea>`.

### Slots

```ts
/**
 * Slots for the Textarea component
 */
interface TextareaSlots {
  leading(): any;
  default(): any;
  trailing(): any;
}
```

### Emits

```ts
/**
 * Emitted events for the Textarea component
 */
interface TextareaEmits {
  update:modelValue: (payload: [value: _Number<_Optional<_Nullable<T, Mod>, Mod>, Mod>]) => void;
  blur: (payload: [event: FocusEvent]) => void;
  change: (payload: [event: Event]) => void;
}
```

### Expose

Ao acessar o componente por meio de um template ref, você pode usar o seguinte:

| Name                                                                                                                              | Type                                                                                                                                                  |
| --------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `textareaRef`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | `Ref<HTMLTextAreaElement | null>`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} |
| `autoResize`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"}  | `() => void`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"}                      |

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    textarea: {
      slots: {
        root: 'relative inline-flex items-center',
        base: [
          'w-full rounded-md border-0 appearance-none placeholder:text-dimmed disabled:cursor-not-allowed disabled:opacity-75',
          'transition-colors'
        ],
        leading: 'absolute start-0 flex items-start',
        leadingIcon: 'shrink-0 text-dimmed',
        leadingAvatar: 'shrink-0',
        leadingAvatarSize: '',
        trailing: 'absolute end-0 flex items-start',
        trailingIcon: 'shrink-0 text-dimmed'
      },
      variants: {
        fieldGroup: {
          horizontal: {
            root: 'group has-focus-visible:z-[1]',
            base: 'group-not-only:group-first:rounded-e-none group-not-only:group-last:rounded-s-none group-not-last:group-not-first:rounded-none'
          },
          vertical: {
            root: 'group has-focus-visible:z-[1]',
            base: 'group-not-only:group-first:rounded-b-none group-not-only:group-last:rounded-t-none group-not-last:group-not-first:rounded-none'
          }
        },
        size: {
          xs: {
            base: 'px-2 py-1 text-sm/4 gap-1',
            leading: 'ps-2 inset-y-1',
            trailing: 'pe-2 inset-y-1',
            leadingIcon: 'size-4',
            leadingAvatarSize: '3xs',
            trailingIcon: 'size-4'
          },
          sm: {
            base: 'px-2.5 py-1.5 text-sm/4 gap-1.5',
            leading: 'ps-2.5 inset-y-1.5',
            trailing: 'pe-2.5 inset-y-1.5',
            leadingIcon: 'size-4',
            leadingAvatarSize: '3xs',
            trailingIcon: 'size-4'
          },
          md: {
            base: 'px-2.5 py-1.5 text-base/5 gap-1.5',
            leading: 'ps-2.5 inset-y-1.5',
            trailing: 'pe-2.5 inset-y-1.5',
            leadingIcon: 'size-5',
            leadingAvatarSize: '2xs',
            trailingIcon: 'size-5'
          },
          lg: {
            base: 'px-3 py-2 text-base/5 gap-2',
            leading: 'ps-3 inset-y-2',
            trailing: 'pe-3 inset-y-2',
            leadingIcon: 'size-5',
            leadingAvatarSize: '2xs',
            trailingIcon: 'size-5'
          },
          xl: {
            base: 'px-3 py-2 text-base gap-2',
            leading: 'ps-3 inset-y-2',
            trailing: 'pe-3 inset-y-2',
            leadingIcon: 'size-6',
            leadingAvatarSize: 'xs',
            trailingIcon: 'size-6'
          }
        },
        variant: {
          outline: 'text-highlighted bg-default ring ring-inset ring-accented',
          soft: 'text-highlighted bg-elevated/50 hover:bg-elevated focus:bg-elevated disabled:bg-elevated/50',
          subtle: 'text-highlighted bg-elevated ring ring-inset ring-accented',
          ghost: 'text-highlighted bg-transparent hover:bg-elevated focus:bg-elevated disabled:bg-transparent dark:disabled:bg-transparent',
          none: 'text-highlighted bg-transparent focus:outline-none'
        },
        color: {
          primary: '',
          secondary: '',
          accent: '',
          success: '',
          info: '',
          warning: '',
          error: '',
          neutral: ''
        },
        leading: {
          true: ''
        },
        trailing: {
          true: ''
        },
        loading: {
          true: ''
        },
        highlight: {
          true: ''
        },
        fixed: {
          false: ''
        },
        type: {
          file: 'file:me-1.5 file:font-medium file:text-muted file:outline-none'
        },
        autoresize: {
          true: {
            base: 'resize-none'
          }
        }
      },
      compoundVariants: [
        {
          color: 'primary',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-primary/25 focus-visible:outline-3 focus-visible:ring-primary'
        },
        {
          color: 'secondary',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-secondary/25 focus-visible:outline-3 focus-visible:ring-secondary'
        },
        {
          color: 'accent',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-accent/25 focus-visible:outline-3 focus-visible:ring-accent'
        },
        {
          color: 'success',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-success/25 focus-visible:outline-3 focus-visible:ring-success'
        },
        {
          color: 'info',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-info/25 focus-visible:outline-3 focus-visible:ring-info'
        },
        {
          color: 'warning',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-warning/25 focus-visible:outline-3 focus-visible:ring-warning'
        },
        {
          color: 'error',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-error/25 focus-visible:outline-3 focus-visible:ring-error'
        },
        {
          color: 'primary',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-primary/25 focus-visible:outline-3'
        },
        {
          color: 'secondary',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-secondary/25 focus-visible:outline-3'
        },
        {
          color: 'accent',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-accent/25 focus-visible:outline-3'
        },
        {
          color: 'success',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-success/25 focus-visible:outline-3'
        },
        {
          color: 'info',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-info/25 focus-visible:outline-3'
        },
        {
          color: 'warning',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-warning/25 focus-visible:outline-3'
        },
        {
          color: 'error',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-error/25 focus-visible:outline-3'
        },
        {
          color: 'primary',
          highlight: true,
          class: 'ring ring-inset ring-primary'
        },
        {
          color: 'secondary',
          highlight: true,
          class: 'ring ring-inset ring-secondary'
        },
        {
          color: 'accent',
          highlight: true,
          class: 'ring ring-inset ring-accent'
        },
        {
          color: 'success',
          highlight: true,
          class: 'ring ring-inset ring-success'
        },
        {
          color: 'info',
          highlight: true,
          class: 'ring ring-inset ring-info'
        },
        {
          color: 'warning',
          highlight: true,
          class: 'ring ring-inset ring-warning'
        },
        {
          color: 'error',
          highlight: true,
          class: 'ring ring-inset ring-error'
        },
        {
          color: 'neutral',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'outline-inverted/25 focus-visible:outline-3 focus-visible:ring-inverted'
        },
        {
          color: 'neutral',
          variant: [
            'soft',
            'ghost'
          ],
          class: 'outline-inverted/25 focus-visible:outline-3'
        },
        {
          color: 'neutral',
          highlight: true,
          class: 'ring ring-inset ring-inverted'
        },
        {
          leading: true,
          size: 'xs',
          class: 'ps-7'
        },
        {
          leading: true,
          size: 'sm',
          class: 'ps-8'
        },
        {
          leading: true,
          size: 'md',
          class: 'ps-9'
        },
        {
          leading: true,
          size: 'lg',
          class: 'ps-10'
        },
        {
          leading: true,
          size: 'xl',
          class: 'ps-11'
        },
        {
          trailing: true,
          size: 'xs',
          class: 'pe-7'
        },
        {
          trailing: true,
          size: 'sm',
          class: 'pe-8'
        },
        {
          trailing: true,
          size: 'md',
          class: 'pe-9'
        },
        {
          trailing: true,
          size: 'lg',
          class: 'pe-10'
        },
        {
          trailing: true,
          size: 'xl',
          class: 'pe-11'
        },
        {
          loading: true,
          leading: true,
          class: {
            leadingIcon: 'animate-spin'
          }
        },
        {
          loading: true,
          leading: false,
          trailing: true,
          class: {
            trailingIcon: 'animate-spin'
          }
        },
        {
          fixed: false,
          size: 'xs',
          class: 'md:text-xs'
        },
        {
          fixed: false,
          size: 'sm',
          class: 'md:text-xs'
        },
        {
          fixed: false,
          size: 'md',
          class: 'md:text-sm'
        },
        {
          fixed: false,
          size: 'lg',
          class: 'md:text-sm'
        }
      ],
      defaultVariants: {
        size: 'md',
        color: 'accent',
        variant: 'outline'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/Textarea.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/textarea.ts).


# Theme

## Uso

O componente Theme permite sobrescrever as **classes de slot** e as **props** padrão de todos os componentes filhos sem modificar cada um individualmente. Ele usa o mecanismo `provide` / `inject` do Vue internamente, então as sobrescritas se aplicam em qualquer profundidade.

> \[!NOTE]
>
> O componente Theme não renderiza nenhum elemento HTML; ele apenas fornece sobrescritas de tema aos seus filhos.

**Nuxt:**

> \[!TIP]
>
> Para a configuração de tema no nível do app, recomendamos usar o arquivo `app.config.ts`.

**Vue:**

> \[!TIP]
>
> Para a configuração de tema no nível do app, recomendamos usar o arquivo `vite.config.ts`.

### Classes de slot

Use a prop `ui` para sobrescrever as classes de slot dos componentes descendentes. As chaves são os nomes dos componentes (camelCase) e os valores são as sobrescritas das classes de slot deles.

:component-example{name="theme-ui-example"}

### Valores padrão de props `4.8+`

Use a prop `props` para sobrescrever o valor padrão de qualquer prop nos componentes descendentes. Cada chave corresponde a um parcial das props daquele componente.

:component-example{name="theme-props-example"}

> \[!TIP]
>
> Props explícitas em um componente (ex.: `<NButton color="primary" />`) sempre prevalecem sobre `<NTheme :props>`. Os padrões do Theme só se aplicam quando a prop não foi passada explicitamente.

## Exemplos

### Múltiplos componentes

Use chaves diferentes em `ui` ou `props` para tematizar vários tipos de componentes de uma vez.

:component-example{name="theme-multiple-example"}

### Temas aninhados

Aninhe vários componentes Theme para compor as sobrescritas. O Theme mais interno tem precedência, enquanto as chaves não sobrescritas são herdadas do Theme externo.

:component-example{name="theme-nested-example"}

### Prioridade explícita

Definir explicitamente qualquer prop (incluindo `ui`) em um componente individual sempre tem prioridade sobre o componente Theme.

:component-example{name="theme-priority-example"}

### Propagação profunda

As sobrescritas ficam disponíveis para todos os componentes descendentes, independentemente de quão profundamente aninhados eles estejam.

:component-example{name="theme-deep-example"}

> \[!NOTE]
>
> Neste exemplo, `MyButton` é um componente personalizado que renderiza um `UButton` internamente. As sobrescritas de tema ainda se aplicam porque se propagam por toda a árvore de componentes.

### Componentes de formulário

Use o componente Theme para aplicar uma estilização consistente em um grupo de componentes de formulário.

:component-example{name="theme-form-example"}

> \[!TIP]
>
> `<NFormField>`, `<NFieldGroup>` and `<NAvatarGroup>` keep precedence over `<NTheme :props>` for `size`, `color` and `highlight`. Validation errors also force the `error` color over any theme value.

### Componentes de prose

Use o namespace `prose` para tematizar os componentes de tipografia. As chaves ficam aninhadas sob `prose` (ex.: `prose.p`, `prose.code`).

:component-example{name="theme-prose-example"}

## API

### Props

```ts
/**
 * Props for the Theme component
 */
interface ThemeProps {
  /**
   * Per-component prop defaults that flow through `useComponentProps` to
   * every descendant. Each key maps to a partial of that component's props.
   */
  props?: ThemeDefaults | undefined;
  /**
   * Per-component slot class overrides (flat shorthand for `:props.<name>.ui`).
   */
  ui?: ThemeUI | undefined;
}
```

### Slots

```ts
/**
 * Slots for the Theme component
 */
interface ThemeSlots {
  default(): any;
}
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/Theme.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/theme.ts).


# Timeline

## Uso

Use o componente Timeline para exibir uma lista de itens em uma linha do tempo.

```vue
<script setup lang="ts">
import type { TimelineItem } from '@nitro/ui'

const items = ref<TimelineItem[]>([
  {
    date: "Mar 15, 2025",
    title: "Project Kickoff",
    description: "Kicked off the project with team alignment. Set up project milestones and allocated resources.",
    icon: "i-lucide-rocket"
  },
  {
    date: "Mar 22 2025",
    title: "Design Phase",
    description: "User research and design workshops. Created wireframes and prototypes for user testing.",
    icon: "i-lucide-palette"
  },
  {
    date: "Mar 29 2025",
    title: "Development Sprint",
    description: "Frontend and backend development. Implemented core features and integrated with APIs.",
    icon: "i-lucide-code"
  },
  {
    date: "Apr 5 2025",
    title: "Testing & Deployment",
    description: "QA testing and performance optimization. Deployed the application to production.",
    icon: "i-lucide-check-circle"
  }
])
</script>

<template>
  <UTimeline :items="items" />
</template>
```

### Itens

Use a prop `items` como um array de objetos com as seguintes propriedades:

- `date?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `title?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `description?: AvatarProps`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `icon?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `avatar?: AvatarProps`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `value?: string | number`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- [`slot?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}](https://ui.nitro.news/#with-custom-slot)
- `class?: any`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `ui?: { item?: ClassNameValue, container?: ClassNameValue, indicator?: ClassNameValue, separator?: ClassNameValue, wrapper?: ClassNameValue, date?: ClassNameValue, title?: ClassNameValue, description?: ClassNameValue }`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

```vue
<script setup lang="ts">
import type { TimelineItem } from '@nitro/ui'

const items = ref<TimelineItem[]>([
  {
    date: "Mar 15, 2025",
    title: "Project Kickoff",
    description: "Kicked off the project with team alignment. Set up project milestones and allocated resources.",
    icon: "i-lucide-rocket"
  },
  {
    date: "Mar 22 2025",
    title: "Design Phase",
    description: "User research and design workshops. Created wireframes and prototypes for user testing.",
    icon: "i-lucide-palette"
  },
  {
    date: "Mar 29 2025",
    title: "Development Sprint",
    description: "Frontend and backend development. Implemented core features and integrated with APIs.",
    icon: "i-lucide-code"
  },
  {
    date: "Apr 5 2025",
    title: "Testing & Deployment",
    description: "QA testing and performance optimization. Deployed the application to production.",
    icon: "i-lucide-check-circle"
  }
])
</script>

<template>
  <UTimeline :default-value="2" :items="items" class="w-96" />
</template>
```

### Cor

Use a prop `color` para alterar a cor dos itens ativos em uma Timeline.

```vue
<script setup lang="ts">
import type { TimelineItem } from '@nitro/ui'

const items = ref<TimelineItem[]>([
  {
    date: "Mar 15, 2025",
    title: "Project Kickoff",
    description: "Kicked off the project with team alignment. Set up project milestones and allocated resources.",
    icon: "i-lucide-rocket"
  },
  {
    date: "Mar 22 2025",
    title: "Design Phase",
    description: "User research and design workshops. Created wireframes and prototypes for user testing.",
    icon: "i-lucide-palette"
  },
  {
    date: "Mar 29 2025",
    title: "Development Sprint",
    description: "Frontend and backend development. Implemented core features and integrated with APIs.",
    icon: "i-lucide-code"
  },
  {
    date: "Apr 5 2025",
    title: "Testing & Deployment",
    description: "QA testing and performance optimization. Deployed the application to production.",
    icon: "i-lucide-check-circle"
  }
])
</script>

<template>
  <UTimeline color="neutral" :default-value="2" :items="items" class="w-96" />
</template>
```

### Tamanho

Use a prop `size` para alterar o tamanho do Timeline.

```vue
<script setup lang="ts">
import type { TimelineItem } from '@nitro/ui'

const items = ref<TimelineItem[]>([
  {
    date: "Mar 15, 2025",
    title: "Project Kickoff",
    description: "Kicked off the project with team alignment. Set up project milestones and allocated resources.",
    icon: "i-lucide-rocket"
  },
  {
    date: "Mar 22 2025",
    title: "Design Phase",
    description: "User research and design workshops. Created wireframes and prototypes for user testing.",
    icon: "i-lucide-palette"
  },
  {
    date: "Mar 29 2025",
    title: "Development Sprint",
    description: "Frontend and backend development. Implemented core features and integrated with APIs.",
    icon: "i-lucide-code"
  },
  {
    date: "Apr 5 2025",
    title: "Testing & Deployment",
    description: "QA testing and performance optimization. Deployed the application to production.",
    icon: "i-lucide-check-circle"
  }
])
</script>

<template>
  <UTimeline size="xs" :default-value="2" :items="items" class="w-96" />
</template>
```

### Orientação

Use a prop `orientation` para alterar a orientação do Timeline. O padrão é `vertical`.

```vue
<script setup lang="ts">
import type { TimelineItem } from '@nitro/ui'

const items = ref<TimelineItem[]>([
  {
    date: "Mar 15, 2025",
    title: "Project Kickoff",
    description: "Kicked off the project with team alignment.",
    icon: "i-lucide-rocket"
  },
  {
    date: "Mar 22 2025",
    title: "Design Phase",
    description: "User research and design workshops.",
    icon: "i-lucide-palette"
  },
  {
    date: "Mar 29 2025",
    title: "Development Sprint",
    description: "Frontend and backend development.",
    icon: "i-lucide-code"
  },
  {
    date: "Apr 5 2025",
    title: "Testing & Deployment",
    description: "QA testing and performance optimization.",
    icon: "i-lucide-check-circle"
  }
])
</script>

<template>
  <UTimeline orientation="horizontal" :default-value="2" :items="items" class="w-full" />
</template>
```

### Invertido

Use a prop reverse para inverter a direção da Timeline.

```vue
<script setup lang="ts">
import type { TimelineItem } from '@nitro/ui'

const items = ref<TimelineItem[]>([
  {
    date: "Mar 15, 2025",
    title: "Project Kickoff",
    description: "Kicked off the project with team alignment.",
    icon: "i-lucide-rocket"
  },
  {
    date: "Mar 22 2025",
    title: "Design Phase",
    description: "User research and design workshops.",
    icon: "i-lucide-palette"
  },
  {
    date: "Mar 29 2025",
    title: "Development Sprint",
    description: "Frontend and backend development.",
    icon: "i-lucide-code"
  },
  {
    date: "Apr 5 2025",
    title: "Testing & Deployment",
    description: "QA testing and performance optimization.",
    icon: "i-lucide-check-circle"
  }
])
</script>

<template>
  <UTimeline reverse v-model="value" orientation="vertical" :items="items" class="w-full" />
</template>
```

## Exemplos

### Controlar o item ativo

Você pode controlar o item ativo usando a prop `default-value` ou a diretiva `v-model` com o `value` do item. Se nenhum `value` for fornecido, o padrão é o índice.

::component-example{prettier name="timeline-model-value-example"}
::

> \[!TIP]
>
> Use a prop `value-key` para alterar a chave usada para corresponder os itens quando um `v-model` ou `default-value` é fornecido.

### Com evento de seleção

Você pode adicionar um listener `@select` para tornar os itens clicáveis.

> \[!NOTE]
>
> A função handler recebe o `Event` e o `TimelineItem` como primeiro e segundo argumentos, respectivamente.

::component-example{prettier name="timeline-select-example"}
::

### Com layout alternado

Use a prop `ui` para criar uma Timeline com layout alternado.

::component-example{prettier name="timeline-alternating-layout-example"}
::

### Com slot personalizado

Use a propriedade `slot` para personalizar um item específico.

Você terá acesso aos seguintes slots:

- `#{{ item.slot }}-indicator`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `#{{ item.slot }}-date`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `#{{ item.slot }}-title`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `#{{ item.slot }}-description`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

::component-example{prettier name="timeline-custom-slot-example"}
::

### Com slots

Use os slots disponíveis para criar uma Timeline mais complexa.

::component-example{prettier name="timeline-slots-example"}
::

## API

### Props

```ts
/**
 * Props for the Timeline component
 */
interface TimelineProps {
  items: T[];
  /**
   * The element or component this component should render as.
   */
  as?: any;
  size?: "3xs" | "2xs" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | undefined;
  color?: "primary" | "secondary" | "accent" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
  /**
   * The orientation of the Timeline.
   * @default "\"vertical\""
   */
  orientation?: "horizontal" | "vertical" | undefined;
  /**
   * The key used to get the value from the item.
   * @default "\"value\""
   */
  valueKey?: GetItemKeys<T> | undefined;
  defaultValue?: string | number | undefined;
  reverse?: boolean | undefined;
  ui?: { root?: SlotClass; item?: SlotClass; container?: SlotClass; indicator?: SlotClass; separator?: SlotClass; wrapper?: SlotClass; date?: SlotClass; title?: SlotClass; description?: SlotClass; } | undefined;
  modelValue?: string | number | undefined;
}
```

### Slots

```ts
/**
 * Slots for the Timeline component
 */
interface TimelineSlots {
  indicator(): any;
  wrapper(): any;
  date(): any;
  title(): any;
  description(): any;
}
```

### Emits

```ts
/**
 * Emitted events for the Timeline component
 */
interface TimelineEmits {
  select: (payload: [event: Event, item: T]) => void;
  update:modelValue: (payload: [value: string | number | undefined]) => void;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    timeline: {
      slots: {
        root: 'flex gap-1.5',
        item: 'group relative flex flex-1 gap-3',
        container: 'relative flex items-center gap-1.5',
        indicator: 'group-data-[state=completed]:text-inverted group-data-[state=active]:text-inverted text-muted',
        separator: 'flex-1 rounded-full bg-elevated',
        wrapper: 'w-full',
        date: 'text-dimmed text-xs/5',
        title: 'font-medium text-highlighted text-sm',
        description: 'text-muted text-wrap text-sm'
      },
      variants: {
        orientation: {
          horizontal: {
            root: 'flex-row w-full',
            item: 'flex-col',
            separator: 'h-0.5'
          },
          vertical: {
            root: 'flex-col',
            container: 'flex-col',
            separator: 'w-0.5'
          }
        },
        color: {
          primary: {
            indicator: 'group-data-[state=completed]:bg-primary group-data-[state=active]:bg-primary'
          },
          secondary: {
            indicator: 'group-data-[state=completed]:bg-secondary group-data-[state=active]:bg-secondary'
          },
          accent: {
            indicator: 'group-data-[state=completed]:bg-accent group-data-[state=active]:bg-accent'
          },
          success: {
            indicator: 'group-data-[state=completed]:bg-success group-data-[state=active]:bg-success'
          },
          info: {
            indicator: 'group-data-[state=completed]:bg-info group-data-[state=active]:bg-info'
          },
          warning: {
            indicator: 'group-data-[state=completed]:bg-warning group-data-[state=active]:bg-warning'
          },
          error: {
            indicator: 'group-data-[state=completed]:bg-error group-data-[state=active]:bg-error'
          },
          neutral: {
            indicator: 'group-data-[state=completed]:bg-inverted group-data-[state=active]:bg-inverted'
          }
        },
        size: {
          '3xs': '',
          '2xs': '',
          xs: '',
          sm: '',
          md: '',
          lg: '',
          xl: '',
          '2xl': '',
          '3xl': ''
        },
        reverse: {
          true: ''
        }
      },
      compoundVariants: [
        {
          color: 'primary',
          reverse: false,
          class: {
            separator: 'group-data-[state=completed]:bg-primary'
          }
        },
        {
          color: 'secondary',
          reverse: false,
          class: {
            separator: 'group-data-[state=completed]:bg-secondary'
          }
        },
        {
          color: 'accent',
          reverse: false,
          class: {
            separator: 'group-data-[state=completed]:bg-accent'
          }
        },
        {
          color: 'success',
          reverse: false,
          class: {
            separator: 'group-data-[state=completed]:bg-success'
          }
        },
        {
          color: 'info',
          reverse: false,
          class: {
            separator: 'group-data-[state=completed]:bg-info'
          }
        },
        {
          color: 'warning',
          reverse: false,
          class: {
            separator: 'group-data-[state=completed]:bg-warning'
          }
        },
        {
          color: 'error',
          reverse: false,
          class: {
            separator: 'group-data-[state=completed]:bg-error'
          }
        },
        {
          color: 'primary',
          reverse: true,
          class: {
            separator: 'group-data-[state=active]:bg-primary group-data-[state=completed]:bg-primary'
          }
        },
        {
          color: 'secondary',
          reverse: true,
          class: {
            separator: 'group-data-[state=active]:bg-secondary group-data-[state=completed]:bg-secondary'
          }
        },
        {
          color: 'accent',
          reverse: true,
          class: {
            separator: 'group-data-[state=active]:bg-accent group-data-[state=completed]:bg-accent'
          }
        },
        {
          color: 'success',
          reverse: true,
          class: {
            separator: 'group-data-[state=active]:bg-success group-data-[state=completed]:bg-success'
          }
        },
        {
          color: 'info',
          reverse: true,
          class: {
            separator: 'group-data-[state=active]:bg-info group-data-[state=completed]:bg-info'
          }
        },
        {
          color: 'warning',
          reverse: true,
          class: {
            separator: 'group-data-[state=active]:bg-warning group-data-[state=completed]:bg-warning'
          }
        },
        {
          color: 'error',
          reverse: true,
          class: {
            separator: 'group-data-[state=active]:bg-error group-data-[state=completed]:bg-error'
          }
        },
        {
          color: 'neutral',
          reverse: false,
          class: {
            separator: 'group-data-[state=completed]:bg-inverted'
          }
        },
        {
          color: 'neutral',
          reverse: true,
          class: {
            separator: 'group-data-[state=active]:bg-inverted group-data-[state=completed]:bg-inverted'
          }
        },
        {
          orientation: 'horizontal',
          size: '3xs',
          class: {
            wrapper: 'pe-4.5'
          }
        },
        {
          orientation: 'horizontal',
          size: '2xs',
          class: {
            wrapper: 'pe-5'
          }
        },
        {
          orientation: 'horizontal',
          size: 'xs',
          class: {
            wrapper: 'pe-5.5'
          }
        },
        {
          orientation: 'horizontal',
          size: 'sm',
          class: {
            wrapper: 'pe-6'
          }
        },
        {
          orientation: 'horizontal',
          size: 'md',
          class: {
            wrapper: 'pe-6.5'
          }
        },
        {
          orientation: 'horizontal',
          size: 'lg',
          class: {
            wrapper: 'pe-7'
          }
        },
        {
          orientation: 'horizontal',
          size: 'xl',
          class: {
            wrapper: 'pe-7.5'
          }
        },
        {
          orientation: 'horizontal',
          size: '2xl',
          class: {
            wrapper: 'pe-8'
          }
        },
        {
          orientation: 'horizontal',
          size: '3xl',
          class: {
            wrapper: 'pe-8.5'
          }
        },
        {
          orientation: 'vertical',
          size: '3xs',
          class: {
            wrapper: '-mt-0.5 pb-4.5'
          }
        },
        {
          orientation: 'vertical',
          size: '2xs',
          class: {
            wrapper: 'pb-5'
          }
        },
        {
          orientation: 'vertical',
          size: 'xs',
          class: {
            wrapper: 'mt-0.5 pb-5.5'
          }
        },
        {
          orientation: 'vertical',
          size: 'sm',
          class: {
            wrapper: 'mt-1 pb-6'
          }
        },
        {
          orientation: 'vertical',
          size: 'md',
          class: {
            wrapper: 'mt-1.5 pb-6.5'
          }
        },
        {
          orientation: 'vertical',
          size: 'lg',
          class: {
            wrapper: 'mt-2 pb-7'
          }
        },
        {
          orientation: 'vertical',
          size: 'xl',
          class: {
            wrapper: 'mt-2.5 pb-7.5'
          }
        },
        {
          orientation: 'vertical',
          size: '2xl',
          class: {
            wrapper: 'mt-3 pb-8'
          }
        },
        {
          orientation: 'vertical',
          size: '3xl',
          class: {
            wrapper: 'mt-3.5 pb-8.5'
          }
        }
      ],
      defaultVariants: {
        size: 'md',
        color: 'primary'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/Timeline.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/timeline.ts).


# Toast

## Uso

Use o composable [useToast](https://ui.nitro.news/docs/composables/use-toast) para exibir um toast na sua aplicação.

::component-example{collapse prettier name="toast-example"}
::

> \[!WARNING]
>
> Certifique-se de envolver seu app com o componente [`App`](https://ui.nitro.news/docs/components/app), que usa nosso componente [`Toaster`](https://gitlab.nitro.news/nitro/ui/-/blob/main/src/runtime/components/Toaster.vue){rel="&#x22;nofollow&#x22;"}, que por sua vez usa o componente [`ToastProvider`](https://reka-ui.com/docs/components/toast#provider){rel="&#x22;nofollow&#x22;"} do Reka UI.

> \[!TIP]
> See: /docs/components/app#props
>
> Você pode conferir a prop `toaster` do componente `App` para ver como configurar o Toaster globalmente.

### Título

Passe um campo `title` para o método `toast.add` para exibir um título.

::component-example
---
options:
  - name: title
    label: title
    default: Uh oh! Something went wrong.
name: toast-title-example
---
::

### Descrição

Passe um campo `description` para o método `toast.add` para exibir uma descrição.

::component-example
---
options:
  - name: title
    label: title
    default: Uh oh! Something went wrong.
  - name: description
    label: description
    default: There was a problem with your request.
name: toast-description-example
---
::

### Ícone

Passe um campo `icon` para o método `toast.add` para exibir um [Icon](https://ui.nitro.news/docs/components/icon).

::component-example
---
options:
  - name: icon
    label: icon
    default: i-lucide-wifi
name: toast-icon-example
---
::

### Avatar

Passe um campo `avatar` para o método `toast.add` para exibir um [Avatar](https://ui.nitro.news/docs/components/avatar).

::component-example
---
options:
  - name: avatar.src
    alias: avatar
    label: avatar.src
    default:
      src: https://github.com/benjamincanac.png
name: toast-avatar-example
---
::

### Cor

Passe um campo `color` para o método `toast.add` para alterar a cor do Toast.

::component-example
---
options:
  - name: color
    label: color
    default: neutral
    items:
      - primary
      - secondary
      - success
      - info
      - warning
      - error
      - neutral
name: toast-color-example
---
::

### Fechar

Passe um campo `close` para personalizar ou ocultar o [Button](https://ui.nitro.news/docs/components/button) de fechar (com o valor `false`).

:component-example{name="toast-close-example"}

### Ícone de fechar

Passe um campo `closeIcon` para personalizar o [Icon](https://ui.nitro.news/docs/components/icon) do botão de fechar. O padrão é `i-lucide-x`.

::component-example
---
options:
  - name: closeIcon
    label: closeIcon
    default: i-lucide-arrow-right
name: toast-close-icon-example
---
::

**Nuxt:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/nuxt#theme
>
> Você pode personalizar esse ícone globalmente no seu `app.config.ts` na chave `ui.icons.close`.

**Vue:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/vue#theme
>
> Você pode personalizar esse ícone globalmente no seu `vite.config.ts` na chave `ui.icons.close`.

### Ações

Passe um campo `actions` para adicionar algumas ações de [Button](https://ui.nitro.news/docs/components/button) ao Toast.

::component-example
---
options:
  - name: description
    label: description
    default: There was a problem with your request.
name: toast-actions-example
---
::

### Duração

Passe um campo `duration` para o método `toast.add` para alterar por quanto tempo o Toast permanece visível (em milissegundos). O padrão é `5000`.

> \[!TIP]
>
> Defina o campo `duration` como `0` para manter o Toast aberto até ser fechado manualmente.

::component-example
---
options:
  - name: duration
    label: duration
    default: 0
    items:
      - 0
      - 1000
      - 3000
      - 5000
name: toast-duration-example
---
::

### Progresso

Passe um campo `progress` para personalizar ou ocultar a barra de [Progress](https://ui.nitro.news/docs/components/progress) (com o valor `false`).

> \[!TIP]
>
> A barra de Progress herda a cor do Toast por padrão, mas você pode sobrescrevê-la usando o campo `progress.color`.

:component-example{name="toast-progress-example"}

### Orientação

Passe um campo `orientation` para o método `toast.add` para alterar a orientação do Toast.

::component-example
---
options:
  - name: orientation
    label: orientation
    default: horizontal
    items:
      - horizontal
      - vertical
name: toast-orientation-example
---
::

## Exemplos

> \[!NOTE]
> See: /components/app
>
> O Nitro UI fornece um componente **App** que envolve seu app para fornecer configurações globais.

### Alterar a posição global

Altere a prop `toaster.position` no componente [App](https://ui.nitro.news/docs/components/app#props) para alterar a posição dos toasts.

```vue [app.vue]
<script setup lang="ts">
const toaster = { position: 'bottom-right' }
</script>

<template>
  <NApp :toaster="toaster">
    <NuxtPage />
  </NApp>
</template>
```

::component-example
---
prettier: true
name: toast-example
---
#options
:toaster-position-example
::

### Alterar a duração global

Altere a prop `toaster.duration` no componente [App](https://ui.nitro.news/docs/components/app#props) para alterar a duração dos toasts.

```vue [app.vue]
<script setup lang="ts">
const toaster = { duration: 5000 }
</script>

<template>
  <NApp :toaster="toaster">
    <NuxtPage />
  </NApp>
</template>
```

::component-example
---
prettier: true
name: toast-example
---
#options
:toaster-duration-example
::

### Alterar o máximo global `4.1+`

Altere a prop `toaster.max` no componente [App](https://ui.nitro.news/docs/components/app#props) para alterar o número máximo de toasts exibidos ao mesmo tempo.

```vue [app.vue]
<script setup lang="ts">
const toaster = { max: 3 }
</script>

<template>
  <NApp :toaster="toaster">
    <NuxtPage />
  </NApp>
</template>
```

::component-example
---
prettier: true
name: toast-example
---
#options
:toaster-max-example
::

### Toasts empilhados

Defina a prop `toaster.expand` como `false` no componente [App](https://ui.nitro.news/docs/components/app#props) para exibir toasts empilhados (inspirado no [Sonner](https://sonner.emilkowal.ski/){rel="&#x22;nofollow&#x22;"}).

```vue [app.vue]
<script setup lang="ts">
const toaster = { expand: true }
</script>

<template>
  <NApp :toaster="toaster">
    <NuxtPage />
  </NApp>
</template>
```

> \[!TIP]
>
> Você pode passar o mouse sobre os toasts para expandi-los. Isso também pausa o cronômetro dos toasts.

::component-example
---
prettier: true
name: toast-example
---
#options
:toaster-expand-example
::

### Toasts sem duplicação `4.5+`

Ao chamar `toast.add` com um `id` que já existe, o toast existente pulsa em vez de criar uma duplicata.

::component-example{collapse name="toast-duplicate-example"}
::

### Com callback

Passe um campo `onUpdateOpen` para executar um callback quando o toast é fechado (seja por expiração ou por dispensa do usuário).

::component-example{collapse name="toast-callback-example"}
::

### Com conteúdo HTML

Use a [função de renderização `h()`](https://vuejs.org/api/render-function.html#h){rel="&#x22;nofollow&#x22;"} nos campos `title` ou `description` para renderizar elementos HTML ou componentes Vue com estilização personalizada.

::component-example{collapse name="toast-html-example"}
::

## API

### Props

```ts
/**
 * Props for the Toast component
 */
interface ToastProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  title?: StringOrVNode | undefined;
  description?: StringOrVNode | undefined;
  icon?: any;
  avatar?: AvatarProps | undefined;
  color?: "error" | "neutral" | "primary" | "secondary" | "accent" | "success" | "info" | "warning" | undefined;
  /**
   * The orientation between the content and the actions.
   * @default "\"vertical\""
   */
  orientation?: "vertical" | "horizontal" | undefined;
  /**
   * Display a close button to dismiss the toast.
   * `{ size: 'md', color: 'neutral', variant: 'link' }`{lang="ts-type"}
   * @default "true"
   */
  close?: boolean | Omit<ButtonProps, LinkPropsKeys> | undefined;
  /**
   * The icon displayed in the close button.
   */
  closeIcon?: any;
  /**
   * Display a list of actions:
   * - under the title and description when orientation is `vertical`
   * - next to the close button when orientation is `horizontal`
   * `{ size: 'xs' }`{lang="ts-type"}
   */
  actions?: ButtonProps[] | undefined;
  /**
   * Display a progress bar showing the toast's remaining duration.
   * `{ size: 'sm' }`{lang="ts-type"}
   * @default "true"
   */
  progress?: boolean | Pick<ProgressProps, "color" | "ui"> | undefined;
  ui?: { root?: SlotClass; wrapper?: SlotClass; title?: SlotClass; description?: SlotClass; icon?: SlotClass; avatar?: SlotClass; avatarSize?: SlotClass; actions?: SlotClass; progress?: SlotClass; close?: SlotClass; } | undefined;
  /**
   * The open state of the dialog when it is initially rendered. Use when you do not need to control its open state.
   */
  defaultOpen?: boolean | undefined;
  /**
   * The controlled open state of the dialog. Can be bind as `v-model:open`.
   */
  open?: boolean | undefined;
  /**
   * Control the sensitivity of the toast for accessibility purposes.
   * 
   * For toasts that are the result of a user action, choose `foreground`. Toasts generated from background tasks should use `background`.
   */
  type?: "foreground" | "background" | undefined;
  /**
   * Time in milliseconds that toast should remain visible for. Overrides value
   * given to `ToastProvider`.
   */
  duration?: number | undefined;
}
```

### Slots

```ts
/**
 * Slots for the Toast component
 */
interface ToastSlots {
  leading(): any;
  title(): any;
  description(): any;
  actions(): any;
  close(): any;
}
```

### Emits

```ts
/**
 * Emitted events for the Toast component
 */
interface ToastEmits {
  pause: (payload: []) => void;
  escapeKeyDown: (payload: [event: KeyboardEvent]) => void;
  resume: (payload: []) => void;
  swipeStart: (payload: [event: SwipeEvent]) => void;
  swipeMove: (payload: [event: SwipeEvent]) => void;
  swipeCancel: (payload: [event: SwipeEvent]) => void;
  swipeEnd: (payload: [event: SwipeEvent]) => void;
  update:open: (payload: [value: boolean]) => void;
}
```

### Expose

Ao acessar o componente por meio de um template ref, você pode usar o seguinte:

| Name                                                                                                                         | Type                                                                                                                              |
| ---------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `height`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} | `Ref<number>`{.language-ts-type.shiki.shiki-themes.material-theme-lighter.material-theme.material-theme-palenight lang="ts-type"} |

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    toast: {
      slots: {
        root: 'relative group overflow-hidden bg-default shadow-lg rounded-lg ring ring-default p-4 flex gap-2.5 focus-visible:outline-2 focus-visible:outline-offset-2',
        wrapper: 'w-0 flex-1 flex flex-col',
        title: 'text-sm font-semibold text-highlighted',
        description: 'text-sm text-default',
        icon: 'shrink-0 size-5',
        avatar: 'shrink-0',
        avatarSize: '2xl',
        actions: 'flex gap-1.5 shrink-0',
        progress: 'absolute inset-x-0 bottom-0',
        close: 'p-0'
      },
      variants: {
        color: {
          primary: {
            root: 'ring-inset ring-primary  focus-visible:outline-primary',
            title: 'text-primary',
            description: 'text-primary',
            icon: 'text-primary'
          },
          secondary: {
            root: 'ring-inset ring-secondary  focus-visible:outline-secondary',
            title: 'text-secondary',
            description: 'text-secondary',
            icon: 'text-secondary'
          },
          accent: {
            root: 'ring-inset ring-accent  focus-visible:outline-accent',
            title: 'text-accent',
            description: 'text-accent',
            icon: 'text-accent'
          },
          success: {
            root: 'ring-inset ring-success  focus-visible:outline-success',
            title: 'text-success',
            description: 'text-success',
            icon: 'text-success'
          },
          info: {
            root: 'ring-inset ring-info  focus-visible:outline-info',
            title: 'text-info',
            description: 'text-info',
            icon: 'text-info'
          },
          warning: {
            root: 'ring-inset ring-warning  focus-visible:outline-warning',
            title: 'text-warning',
            description: 'text-warning',
            icon: 'text-warning'
          },
          error: {
            root: 'ring-inset ring-error  focus-visible:outline-error',
            title: 'text-error',
            description: 'text-error',
            icon: 'text-error'
          },
          neutral: {
            root: 'focus-visible:outline-default',
            icon: 'text-highlighted'
          }
        },
        orientation: {
          horizontal: {
            root: 'items-center',
            actions: 'items-center'
          },
          vertical: {
            root: 'items-start',
            actions: 'items-start mt-2.5'
          }
        },
        title: {
          true: {
            description: 'mt-1'
          }
        }
      },
      defaultVariants: {
        color: 'neutral'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/Toast.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/toast.ts).


# Tooltip

## Uso

Use a [Button](https://ui.nitro.news/docs/components/button) or any other component in the default slot of the Tooltip.

```vue
<template>
  <UTooltip text="Open on GitHub">
    <NButton label="Open" color="neutral" variant="subtle" />
  </UTooltip>
</template>
```

> \[!WARNING]
>
> Certifique-se de envolver seu app com o componente [`App`](https://ui.nitro.news/docs/components/app), que usa o componente [`TooltipProvider`](https://reka-ui.com/docs/components/tooltip#provider){rel="&#x22;nofollow&#x22;"} do Reka UI.

> \[!TIP]
> See: /docs/components/app#props
>
> Você pode conferir a prop `tooltip` do componente `App` para ver como configurar o Tooltip globalmente.

### Texto

Use a prop `text` para definir o conteúdo do Tooltip.

```vue
<template>
  <UTooltip text="Open on GitHub">
    <NButton label="Open" color="neutral" variant="subtle" />
  </UTooltip>
</template>
```

### Kbds

Use a prop `kbds` para renderizar componentes [Kbd](https://ui.nitro.news/docs/components/kbd) no Tooltip.

```vue
<template>
  <UTooltip text="Open on GitHub" :kbds="[
  'meta',
  'G'
]">
    <NButton label="Open" color="neutral" variant="subtle" />
  </UTooltip>
</template>
```

> \[!TIP]
>
> Você pode usar teclas especiais como `meta`, que é exibida como `⌘` no macOS e `Ctrl` em outras plataformas.

### Atraso

Use a prop `delay-duration` para alterar o atraso antes de o Tooltip aparecer. Por exemplo, você pode fazê-lo aparecer instantaneamente definindo-a como `0`.

```vue
<template>
  <UTooltip :delay-duration="0" text="Open on GitHub">
    <NButton label="Open" color="neutral" variant="subtle" />
  </UTooltip>
</template>
```

> \[!TIP]
>
> Isso pode ser configurado globalmente por meio da opção `tooltip.delayDuration` no componente [`App`](https://ui.nitro.news/docs/components/app).

### Conteúdo

Use a prop `content` para controlar como o conteúdo do Tooltip é renderizado, como seu `align` ou `side`, por exemplo.

> \[!TIP]
>
> Isso pode ser configurado globalmente por meio da opção `tooltip.content` no componente [`App`](https://ui.nitro.news/docs/components/app).

```vue
<template>
  <UTooltip :content="{
  align: 'center',
  side: 'bottom',
  sideOffset: 8
}" text="Open on GitHub">
    <NButton label="Open" color="neutral" variant="subtle" />
  </UTooltip>
</template>
```

### Seta

Use a prop `arrow` para exibir uma seta no Tooltip.

```vue
<template>
  <UTooltip arrow text="Open on GitHub">
    <NButton label="Open" color="neutral" variant="subtle" />
  </UTooltip>
</template>
```

### Desabilitado

Use a prop `disabled` para desabilitar o Tooltip.

```vue
<template>
  <UTooltip disabled text="Open on GitHub">
    <NButton label="Open" color="neutral" variant="subtle" />
  </UTooltip>
</template>
```

## Exemplos

### Controlar o estado de abertura

Você pode controlar o estado de abertura usando a prop `default-open` ou a diretiva `v-model:open`.

:component-example{name="tooltip-open-example"}

> \[!NOTE]
>
> Neste exemplo, aproveitando o [`defineShortcuts`](https://ui.nitro.news/docs/composables/define-shortcuts), você pode abrir e fechar o Tooltip pressionando :kbd{value="O"}.

### Com cursor que acompanha

Você pode fazer o Tooltip acompanhar o cursor ao passar o mouse sobre um elemento usando a prop [`reference`](https://reka-ui.com/docs/components/tooltip#trigger){rel="&#x22;nofollow&#x22;"}:

:component-example{name="tooltip-cursor-example"}

## API

### Props

```ts
/**
 * Props for the Tooltip component
 */
interface TooltipProps {
  /**
   * The text content of the tooltip.
   */
  text?: string | undefined;
  /**
   * The keyboard keys to display in the tooltip.
   */
  kbds?: (string | undefined)[] | KbdProps[] | undefined;
  /**
   * The content of the tooltip.
   * 
   * Inherits from the `tooltip.content` of the {@link AppProps } component when not provided.
   */
  content?: (Omit<TooltipContentProps, "as" | "asChild"> & Partial<EmitsToProps<TooltipContentImplEmits>>) | undefined;
  /**
   * Display an arrow alongside the tooltip.
   * `{ rounded: true }`{lang="ts-type"}
   */
  arrow?: boolean | Omit<TooltipArrowProps, "as" | "asChild"> | undefined;
  /**
   * Render the tooltip in a portal.
   * @default "true"
   */
  portal?: string | boolean | HTMLElement | undefined;
  /**
   * The reference (or anchor) element that is being referred to for positioning.
   * 
   * If not provided will use the current component as anchor.
   */
  reference?: ReferenceElement | undefined;
  ui?: { content?: SlotClass; arrow?: SlotClass; text?: SlotClass; kbds?: SlotClass; kbdsSize?: SlotClass; } | undefined;
  /**
   * The open state of the tooltip when it is initially rendered.
   * Use when you do not need to control its open state.
   */
  defaultOpen?: boolean | undefined;
  /**
   * The controlled open state of the tooltip.
   */
  open?: boolean | undefined;
  /**
   * Override the duration given to the `Provider` to customise
   * the open delay for a specific tooltip.
   */
  delayDuration?: number | undefined;
  /**
   * Prevents Tooltip.Content from remaining open when hovering.
   * Disabling this has accessibility consequences. Inherits
   * from Tooltip.Provider.
   */
  disableHoverableContent?: boolean | undefined;
  /**
   * When `true`, clicking on trigger will not close the content.
   */
  disableClosingTrigger?: boolean | undefined;
  /**
   * When `true`, disable tooltip
   */
  disabled?: boolean | undefined;
  /**
   * Prevent the tooltip from opening if the focus did not come from
   * the keyboard by matching against the `:focus-visible` selector.
   * This is useful if you want to avoid opening it when switching
   * browser tabs or closing a dialog.
   */
  ignoreNonKeyboardFocus?: boolean | undefined;
}
```

### Slots

```ts
/**
 * Slots for the Tooltip component
 */
interface TooltipSlots {
  default(): any;
  content(): any;
}
```

### Emits

```ts
/**
 * Emitted events for the Tooltip component
 */
interface TooltipEmits {
  update:open: (payload: [value: boolean]) => void;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    tooltip: {
      slots: {
        content: 'flex items-center gap-1 bg-default text-highlighted shadow-sm rounded-sm ring ring-default h-6 px-2.5 py-1 text-xs select-none data-[state=delayed-open]:animate-[scale-in_100ms_ease-out] data-[state=closed]:animate-[scale-out_100ms_ease-in] origin-(--reka-tooltip-content-transform-origin) pointer-events-auto',
        arrow: 'fill-default',
        text: 'truncate',
        kbds: "hidden lg:inline-flex items-center shrink-0 gap-0.5 not-first-of-type:before:content-['·'] not-first-of-type:before:me-0.5",
        kbdsSize: 'sm'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/Tooltip.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/tooltip.ts).


# Tree

## Uso

Use o componente Tree para exibir uma estrutura hierárquica de itens.

```vue
<script setup lang="ts">
import type { TreeItem } from '@nitro/ui'

const items = ref<TreeItem[]>([
  {
    label: "app/",
    defaultExpanded: true,
    children: [
      {
        label: "composables/",
        children: [
          {
            label: "useAuth.ts",
            icon: "i-vscode-icons-file-type-typescript"
          },
          {
            label: "useUser.ts",
            icon: "i-vscode-icons-file-type-typescript"
          }
        ]
      },
      {
        label: "components/",
        defaultExpanded: true,
        children: [
          {
            label: "Card.vue",
            icon: "i-vscode-icons-file-type-vue"
          },
          {
            label: "Button.vue",
            icon: "i-vscode-icons-file-type-vue"
          }
        ]
      }
    ]
  },
  {
    label: "app.vue",
    icon: "i-vscode-icons-file-type-vue"
  },
  {
    label: "nuxt.config.ts",
    icon: "i-vscode-icons-file-type-nuxt"
  }
])
</script>

<template>
  <UTree :items="items" />
</template>
```

### Itens

Use a prop `items` como um array de objetos com as seguintes propriedades:

- `icon?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `label?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `trailingIcon?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `defaultExpanded?: boolean`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `disabled?: boolean`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `slot?: string`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `children?: TreeItem[]`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `onToggle?: (e: TreeItemToggleEvent<TreeItem>) => void`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `onSelect?: (e: TreeItemSelectEvent<TreeItem>) => void`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `class?: any`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `ui?: { item?: ClassNameValue, itemWithChildren?: ClassNameValue, link?: ClassNameValue, linkLeadingIcon?: ClassNameValue, linkLabel?: ClassNameValue, linkTrailing?: ClassNameValue, linkTrailingIcon?: ClassNameValue, listWithChildren?: ClassNameValue }`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

> \[!NOTE]
>
> É necessário um identificador único para cada item. O componente usará a prop `label` como identificador se nenhum `get-key` for fornecido. O ideal é fornecer uma prop de função `get-key` para retornar um identificador único. Alternativamente, você pode usar a prop `labelKey` para especificar qual propriedade usar como identificador único.

```vue
<script setup lang="ts">
import type { TreeItem } from '@nitro/ui'

const items = ref<TreeItem[]>([
  {
    label: "app/",
    defaultExpanded: true,
    children: [
      {
        label: "composables/",
        children: [
          {
            label: "useAuth.ts",
            icon: "i-vscode-icons-file-type-typescript"
          },
          {
            label: "useUser.ts",
            icon: "i-vscode-icons-file-type-typescript"
          }
        ]
      },
      {
        label: "components/",
        defaultExpanded: true,
        children: [
          {
            label: "Card.vue",
            icon: "i-vscode-icons-file-type-vue"
          },
          {
            label: "Button.vue",
            icon: "i-vscode-icons-file-type-vue"
          }
        ]
      }
    ]
  },
  {
    label: "app.vue",
    icon: "i-vscode-icons-file-type-vue"
  },
  {
    label: "nuxt.config.ts",
    icon: "i-vscode-icons-file-type-nuxt"
  }
])
</script>

<template>
  <UTree :items="items" />
</template>
```

### Múltiplo

Use a prop `multiple` para permitir múltiplas seleções de itens.

```vue
<script setup lang="ts">
import type { TreeItem } from '@nitro/ui'

const items = ref<TreeItem[]>([
  {
    label: "app/",
    defaultExpanded: true,
    children: [
      {
        label: "composables/",
        children: [
          {
            label: "useAuth.ts",
            icon: "i-vscode-icons-file-type-typescript"
          },
          {
            label: "useUser.ts",
            icon: "i-vscode-icons-file-type-typescript"
          }
        ]
      },
      {
        label: "components/",
        defaultExpanded: true,
        children: [
          {
            label: "Card.vue",
            icon: "i-vscode-icons-file-type-vue"
          },
          {
            label: "Button.vue",
            icon: "i-vscode-icons-file-type-vue"
          }
        ]
      }
    ]
  },
  {
    label: "app.vue",
    icon: "i-vscode-icons-file-type-vue"
  },
  {
    label: "nuxt.config.ts",
    icon: "i-vscode-icons-file-type-nuxt"
  }
])
</script>

<template>
  <UTree multiple :items="items" />
</template>
```

### Aninhado `4.1+`

Use a prop `nested` para controlar se a Tree é renderizada com estrutura aninhada ou como uma lista plana. O padrão é `true`.

```vue
<script setup lang="ts">
import type { TreeItem } from '@nitro/ui'

const items = ref<TreeItem[]>([
  {
    label: "app/",
    defaultExpanded: true,
    children: [
      {
        label: "composables/",
        children: [
          {
            label: "useAuth.ts",
            icon: "i-vscode-icons-file-type-typescript"
          },
          {
            label: "useUser.ts",
            icon: "i-vscode-icons-file-type-typescript"
          }
        ]
      },
      {
        label: "components/",
        defaultExpanded: true,
        children: [
          {
            label: "Card.vue",
            icon: "i-vscode-icons-file-type-vue"
          },
          {
            label: "Button.vue",
            icon: "i-vscode-icons-file-type-vue"
          }
        ]
      }
    ]
  },
  {
    label: "app.vue",
    icon: "i-vscode-icons-file-type-vue"
  },
  {
    label: "nuxt.config.ts",
    icon: "i-vscode-icons-file-type-nuxt"
  }
])
</script>

<template>
  <UTree :nested="false" :items="items" />
</template>
```

> \[!NOTE]
> See: #with-virtualization
>
> Quando `nested` é `false`, todos os itens são renderizados no mesmo nível com recuo para indicar a hierarquia. Isso é útil para virtualização ou para a funcionalidade de arrastar e soltar.

### Cor

Use a prop `color` para alterar a cor do Tree.

```vue
<script setup lang="ts">
import type { TreeItem } from '@nitro/ui'

const items = ref<TreeItem[]>([
  {
    label: "app/",
    defaultExpanded: true,
    children: [
      {
        label: "composables/",
        children: [
          {
            label: "useAuth.ts",
            icon: "i-vscode-icons-file-type-typescript"
          },
          {
            label: "useUser.ts",
            icon: "i-vscode-icons-file-type-typescript"
          }
        ]
      },
      {
        label: "components/",
        defaultExpanded: true,
        children: [
          {
            label: "Card.vue",
            icon: "i-vscode-icons-file-type-vue"
          },
          {
            label: "Button.vue",
            icon: "i-vscode-icons-file-type-vue"
          }
        ]
      }
    ]
  },
  {
    label: "app.vue",
    icon: "i-vscode-icons-file-type-vue"
  },
  {
    label: "nuxt.config.ts",
    icon: "i-vscode-icons-file-type-nuxt"
  }
])
</script>

<template>
  <UTree color="neutral" :items="items" />
</template>
```

### Tamanho

Use a prop `size` para alterar o tamanho do Tree.

```vue
<script setup lang="ts">
import type { TreeItem } from '@nitro/ui'

const items = ref<TreeItem[]>([
  {
    label: "app/",
    defaultExpanded: true,
    children: [
      {
        label: "composables/",
        children: [
          {
            label: "useAuth.ts",
            icon: "i-vscode-icons-file-type-typescript"
          },
          {
            label: "useUser.ts",
            icon: "i-vscode-icons-file-type-typescript"
          }
        ]
      },
      {
        label: "components/",
        defaultExpanded: true,
        children: [
          {
            label: "Card.vue",
            icon: "i-vscode-icons-file-type-vue"
          },
          {
            label: "Button.vue",
            icon: "i-vscode-icons-file-type-vue"
          }
        ]
      }
    ]
  },
  {
    label: "app.vue",
    icon: "i-vscode-icons-file-type-vue"
  },
  {
    label: "nuxt.config.ts",
    icon: "i-vscode-icons-file-type-nuxt"
  }
])
</script>

<template>
  <UTree size="xl" :items="items" />
</template>
```

### Ícone à direita

Use a prop `trailing-icon` para personalizar o [Icon](https://ui.nitro.news/docs/components/icon) à direita de um node pai. O padrão é `i-lucide-chevron-down`.

> \[!NOTE]
>
> Se um ícone for especificado para um item, ele sempre terá precedência sobre essas props.

```vue
<script setup lang="ts">
import type { TreeItem } from '@nitro/ui'

const items = ref<TreeItem[]>([
  {
    label: "app/",
    defaultExpanded: true,
    children: [
      {
        label: "composables/",
        trailingIcon: "i-lucide-chevron-down",
        children: [
          {
            label: "useAuth.ts",
            icon: "i-vscode-icons-file-type-typescript"
          },
          {
            label: "useUser.ts",
            icon: "i-vscode-icons-file-type-typescript"
          }
        ]
      },
      {
        label: "components/",
        defaultExpanded: true,
        children: [
          {
            label: "Card.vue",
            icon: "i-vscode-icons-file-type-vue"
          },
          {
            label: "Button.vue",
            icon: "i-vscode-icons-file-type-vue"
          }
        ]
      }
    ]
  },
  {
    label: "app.vue",
    icon: "i-vscode-icons-file-type-vue"
  },
  {
    label: "nuxt.config.ts",
    icon: "i-vscode-icons-file-type-nuxt"
  }
])
</script>

<template>
  <UTree trailing-icon="i-lucide-arrow-down" :items="items" />
</template>
```

**Nuxt:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/nuxt#theme
>
> Você pode personalizar esse ícone globalmente no seu `app.config.ts` na chave `ui.icons.chevronDown`.

**Vue:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/vue#theme
>
> Você pode personalizar esse ícone globalmente no seu `vite.config.ts` na chave `ui.icons.chevronDown`.

### Ícone de expandido

Use as props `expanded-icon` e `collapsed-icon` para personalizar os ícones de um node pai quando ele está expandido ou recolhido. O padrão é `i-lucide-folder-open` e `i-lucide-folder`, respectivamente.

```vue
<script setup lang="ts">
import type { TreeItem } from '@nitro/ui'

const items = ref<TreeItem[]>([
  {
    label: "app/",
    defaultExpanded: true,
    children: [
      {
        label: "composables/",
        children: [
          {
            label: "useAuth.ts",
            icon: "i-vscode-icons-file-type-typescript"
          },
          {
            label: "useUser.ts",
            icon: "i-vscode-icons-file-type-typescript"
          }
        ]
      },
      {
        label: "components/",
        defaultExpanded: true,
        children: [
          {
            label: "Card.vue",
            icon: "i-vscode-icons-file-type-vue"
          },
          {
            label: "Button.vue",
            icon: "i-vscode-icons-file-type-vue"
          }
        ]
      }
    ]
  },
  {
    label: "app.vue",
    icon: "i-vscode-icons-file-type-vue"
  },
  {
    label: "nuxt.config.ts",
    icon: "i-vscode-icons-file-type-nuxt"
  }
])
</script>

<template>
  <UTree expanded-icon="i-lucide-book-open" collapsed-icon="i-lucide-book" :items="items" />
</template>
```

**Nuxt:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/nuxt#theme
>
> Você pode personalizar esses ícones globalmente no seu `app.config.ts` nas chaves `ui.icons.folder` e `ui.icons.folderOpen`.

**Vue:**

> \[!TIP]
> See: /docs/getting-started/integrations/icons/vue#theme
>
> Você pode personalizar esses ícones globalmente no seu `vite.config.ts` nas chaves `ui.icons.folder` e `ui.icons.folderOpen`.

### Desabilitado

Use a prop `disabled` para impedir qualquer interação do usuário com a Tree.

```vue
<script setup lang="ts">
import type { TreeItem } from '@nitro/ui'

const items = ref<TreeItem[]>([
  {
    label: "app",
    icon: "i-lucide-folder",
    defaultExpanded: true,
    children: [
      {
        label: "composables",
        icon: "i-lucide-folder",
        children: [
          {
            label: "useAuth.ts",
            icon: "i-vscode-icons-file-type-typescript"
          },
          {
            label: "useUser.ts",
            icon: "i-vscode-icons-file-type-typescript"
          }
        ]
      },
      {
        label: "components",
        icon: "i-lucide-folder",
        children: [
          {
            label: "Home",
            icon: "i-lucide-folder",
            children: [
              {
                label: "Card.vue",
                icon: "i-vscode-icons-file-type-vue"
              },
              {
                label: "Button.vue",
                icon: "i-vscode-icons-file-type-vue"
              }
            ]
          }
        ]
      }
    ]
  },
  {
    label: "app.vue",
    icon: "i-vscode-icons-file-type-vue"
  },
  {
    label: "nuxt.config.ts",
    icon: "i-vscode-icons-file-type-nuxt"
  }
])
</script>

<template>
  <UTree disabled :items="items" />
</template>
```

> \[!NOTE]
>
> Você também pode desabilitar itens individuais usando `item.disabled`.

## Exemplos

### Controlar o(s) item(ns) selecionado(s)

Você pode controlar o(s) item(ns) selecionado(s) usando a prop `default-value` ou a diretiva `v-model`.

::component-example
---
collapse: true
props:
  class: w-60
name: tree-model-value-example
---
::

> \[!TIP]
>
> Use a prop `get-key` para alterar a função usada para obter a chave única de cada item quando um `v-model` ou `default-value` é fornecido.

Se você quiser evitar que um item seja selecionado, pode usar a propriedade `item.onSelect()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} ou o evento global `select`:

::component-example
---
collapse: true
props:
  class: w-60
name: tree-on-select-example
---
::

> \[!NOTE]
>
> Isso permite expandir ou recolher um item pai sem selecioná-lo.

### Controlar os itens expandidos

Você pode controlar os itens expandidos usando a prop `default-expanded` ou a diretiva `v-model`.

::component-example
---
collapse: true
props:
  class: w-60
name: tree-expanded-example
---
::

Se você quiser evitar que um item seja expandido, pode usar a propriedade `item.onToggle()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"} ou o evento global `toggle`:

::component-example
---
collapse: true
props:
  class: w-60
name: tree-on-toggle-example
---
::

> \[!NOTE]
>
> Isso permite selecionar um item pai sem expandir ou recolher seus filhos.

### Com checkbox nos itens `4.1+`

Você pode usar o slot `item-leading` para adicionar um [Checkbox](https://ui.nitro.news/docs/components/checkbox) aos itens. Use as props `multiple`, `propagate-select` e `bubble-select` para habilitar a seleção múltipla com relação pai-filho e os eventos `select` e `toggle` para controlar o estado selecionado e expandido dos itens.

::component-example
---
collapse: true
props:
  class: w-60
name: tree-checkbox-items-example
---
::

> \[!NOTE]
>
> Este exemplo usa a prop `as` para mudar os itens de `button` para `div`, já que o [`Checkbox`](https://ui.nitro.news/docs/components/checkbox) também é renderizado como um `button`.

### Com arrastar e soltar `4.1+`

Use o composable [`useSortable`](https://vueuse.org/integrations/useSortable/){rel="&#x22;nofollow&#x22;"} de [`@vueuse/integrations`](https://vueuse.org/integrations/README.html){rel="&#x22;nofollow&#x22;"} para habilitar a funcionalidade de arrastar e soltar na Tree. Essa integração envolve o [Sortable.js](https://sortablejs.github.io/Sortable/){rel="&#x22;nofollow&#x22;"} para oferecer uma experiência de arrastar e soltar fluida.

::component-example{collapse prettier name="tree-drag-and-drop-example"}
::

> \[!NOTE]
>
> Este exemplo define a prop `nested` como `false` para ter uma lista plana de itens, de modo que eles possam ser arrastados e soltos.

### Com virtualização `4.1+`

Use a prop `virtualize` para habilitar a virtualização em listas grandes, como um booleano ou um objeto com opções como `{ estimateSize: 32, overscan: 12 }`.

> \[!WARNING]
>
> Quando a virtualização está habilitada, a estrutura em árvore é achatada, de forma semelhante a definir a prop `nested` como `false`.

::component-example
---
prettier: true
props:
  class: w-60
name: tree-virtualize-example
---
::

### Com slot personalizado

Use a propriedade `slot` para personalizar um item específico.

Você terá acesso aos seguintes slots:

- `#{{ item.slot }}-wrapper`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `#{{ item.slot }}`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `#{{ item.slot }}-leading`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `#{{ item.slot }}-label`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}
- `#{{ item.slot }}-trailing`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

::component-example
---
collapse: true
props:
  class: w-60
name: tree-custom-slot-example
---
::

## API

### Props

```ts
/**
 * Props for the Tree component
 */
interface TreeProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  color?: "primary" | "secondary" | "accent" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
  size?: "md" | "xs" | "sm" | "lg" | "xl" | undefined;
  /**
   * This function is passed the index of each item and should return a unique key for that item
   */
  getKey?: ((val: T[number]) => string) | undefined;
  /**
   * The key used to get the label from the item.
   * @default "\"label\""
   */
  labelKey?: GetItemKeys<T> | undefined;
  /**
   * The icon displayed on the right side of a parent node.
   */
  trailingIcon?: any;
  /**
   * The icon displayed when a parent node is expanded.
   */
  expandedIcon?: any;
  /**
   * The icon displayed when a parent node is collapsed.
   */
  collapsedIcon?: any;
  items?: T | undefined;
  /**
   * The controlled value of the Tree. Can be bind as `v-model`.
   */
  modelValue?: (M extends true ? T[number][] : T[number]) | undefined;
  /**
   * The value of the Tree when initially rendered. Use when you do not need to control the state of the Tree.
   */
  defaultValue?: (M extends true ? T[number][] : T[number]) | undefined;
  /**
   * Whether multiple options can be selected or not.
   */
  multiple?: M | undefined;
  /**
   * Use nested DOM structure (children inside parents) vs flattened structure (all items at same level).
   * When `virtualize` is enabled, this is automatically set to `false`.
   * @default "true"
   */
  nested?: boolean | undefined;
  /**
   * Enable virtualization for large lists.
   * Note: when enabled, the tree structure is flattened like if `nested` was set to `false`.
   * @default "false"
   */
  virtualize?: boolean | { overscan?: number | undefined; estimateSize?: number | ((index: number) => number) | undefined; } | undefined;
  onSelect?: ((e: SelectEvent<T[number]>, item: T[number]) => void) | undefined;
  onToggle?: ((e: ToggleEvent<T[number]>, item: T[number]) => void) | undefined;
  ui?: { root?: SlotClass; item?: SlotClass; listWithChildren?: SlotClass; itemWithChildren?: SlotClass; link?: SlotClass; linkLeadingIcon?: SlotClass; linkLabel?: SlotClass; linkTrailing?: SlotClass; linkTrailingIcon?: SlotClass; } | undefined;
  /**
   * The controlled value of the expanded item. Can be binded with `v-model`.
   */
  expanded?: string[] | undefined;
  /**
   * The value of the expanded tree when initially rendered. Use when you do not need to control the state of the expanded tree
   */
  defaultExpanded?: string[] | undefined;
  /**
   * How multiple selection should behave in the collection.
   */
  selectionBehavior?: "replace" | "toggle" | undefined;
  /**
   * When `true`, selecting parent will select the descendants. Requires `multiple` to be `true`.
   */
  propagateSelect?: boolean | undefined;
  /**
   * When `true`, prevents the user from interacting with tree
   */
  disabled?: boolean | undefined;
  /**
   * When `true`, selecting children will update the parent state. Requires `multiple` to be `true`.
   */
  bubbleSelect?: boolean | undefined;
}
```

### Slots

```ts
/**
 * Slots for the Tree component
 */
interface TreeSlots {
  item-wrapper(): any;
  item(): any;
  item-leading(): any;
  item-label(): any;
  item-trailing(): any;
}
```

### Emits

```ts
/**
 * Emitted events for the Tree component
 */
interface TreeEmits {
  update:modelValue: (payload: [val: M extends true ? T[number][] : T[number]]) => void;
  update:expanded: (payload: [val: string[]]) => void;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    tree: {
      slots: {
        root: 'relative isolate',
        item: 'w-full',
        listWithChildren: 'border-s border-default',
        itemWithChildren: 'ps-1.5 -ms-px',
        link: 'relative group w-full flex items-center text-sm select-none before:absolute before:inset-y-px before:inset-x-0 before:z-[-1] before:rounded-md focus:outline-none focus-visible:outline-none focus-visible:before:ring-inset focus-visible:before:ring-2',
        linkLeadingIcon: 'shrink-0 relative',
        linkLabel: 'truncate',
        linkTrailing: 'ms-auto inline-flex gap-1.5 items-center',
        linkTrailingIcon: 'shrink-0 transform transition-transform duration-200 group-data-expanded:rotate-180'
      },
      variants: {
        virtualize: {
          true: {
            root: 'overflow-y-auto'
          }
        },
        color: {
          primary: {
            link: 'focus-visible:before:ring-primary'
          },
          secondary: {
            link: 'focus-visible:before:ring-secondary'
          },
          accent: {
            link: 'focus-visible:before:ring-accent'
          },
          success: {
            link: 'focus-visible:before:ring-success'
          },
          info: {
            link: 'focus-visible:before:ring-info'
          },
          warning: {
            link: 'focus-visible:before:ring-warning'
          },
          error: {
            link: 'focus-visible:before:ring-error'
          },
          neutral: {
            link: 'focus-visible:before:ring-inverted'
          }
        },
        size: {
          xs: {
            listWithChildren: 'ms-4',
            link: 'px-2 py-1 text-xs gap-1',
            linkLeadingIcon: 'size-4',
            linkTrailingIcon: 'size-4'
          },
          sm: {
            listWithChildren: 'ms-4.5',
            link: 'px-2.5 py-1.5 text-xs gap-1.5',
            linkLeadingIcon: 'size-4',
            linkTrailingIcon: 'size-4'
          },
          md: {
            listWithChildren: 'ms-5',
            link: 'px-2.5 py-1.5 text-sm gap-1.5',
            linkLeadingIcon: 'size-5',
            linkTrailingIcon: 'size-5'
          },
          lg: {
            listWithChildren: 'ms-5.5',
            link: 'px-3 py-2 text-sm gap-2',
            linkLeadingIcon: 'size-5',
            linkTrailingIcon: 'size-5'
          },
          xl: {
            listWithChildren: 'ms-6',
            link: 'px-3 py-2 text-base gap-2',
            linkLeadingIcon: 'size-6',
            linkTrailingIcon: 'size-6'
          }
        },
        selected: {
          true: {
            link: 'before:bg-elevated'
          }
        },
        disabled: {
          true: {
            link: 'cursor-not-allowed opacity-75'
          }
        }
      },
      compoundVariants: [
        {
          color: 'primary',
          selected: true,
          class: {
            link: 'text-primary'
          }
        },
        {
          color: 'secondary',
          selected: true,
          class: {
            link: 'text-secondary'
          }
        },
        {
          color: 'accent',
          selected: true,
          class: {
            link: 'text-accent'
          }
        },
        {
          color: 'success',
          selected: true,
          class: {
            link: 'text-success'
          }
        },
        {
          color: 'info',
          selected: true,
          class: {
            link: 'text-info'
          }
        },
        {
          color: 'warning',
          selected: true,
          class: {
            link: 'text-warning'
          }
        },
        {
          color: 'error',
          selected: true,
          class: {
            link: 'text-error'
          }
        },
        {
          color: 'neutral',
          selected: true,
          class: {
            link: 'text-highlighted'
          }
        },
        {
          selected: false,
          disabled: false,
          class: {
            link: [
              'hover:text-highlighted hover:before:bg-elevated/50',
              'transition-colors before:transition-colors'
            ]
          }
        }
      ],
      defaultVariants: {
        color: 'primary',
        size: 'md'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/Tree.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/tree.ts).


# User

## Uso

### Nome

Use a prop `name` para exibir um nome para o usuário.

```vue
<template>
  <UUser name="John Doe" />
</template>
```

### Descrição

Use a prop `description` para exibir uma descrição para o usuário.

```vue
<template>
  <UUser name="John Doe" description="Software Engineer" />
</template>
```

### Avatar

Use a prop `avatar` para exibir um componente [Avatar](https://ui.nitro.news/docs/components/avatar).

```vue
<template>
  <UUser name="John Doe" description="Software Engineer" :avatar="{
  src: 'https://i.pravatar.cc/150?u=john-doe',
  loading: 'lazy',
  icon: 'i-lucide-image'
}" />
</template>
```

```ts
/**
 * Props for the Avatar component
 */
interface AvatarProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  src?: string | undefined;
  alt?: string | undefined;
  icon?: any;
  text?: string | undefined;
  size?: "md" | "xs" | "sm" | "lg" | "xl" | "3xs" | "2xs" | "2xl" | "3xl" | undefined;
  color?: "error" | "primary" | "secondary" | "accent" | "success" | "info" | "warning" | "neutral" | undefined;
  chip?: boolean | ChipProps | undefined;
  ui?: { root?: SlotClass; image?: SlotClass; fallback?: SlotClass; icon?: SlotClass; } | undefined;
  loading?: "lazy" | "eager" | undefined;
  referrerpolicy?: HTMLAttributeReferrerPolicy | undefined;
  crossorigin?: "" | "anonymous" | "use-credentials" | undefined;
  decoding?: "async" | "auto" | "sync" | undefined;
  height?: Numberish | undefined;
  sizes?: string | undefined;
  srcset?: string | undefined;
  usemap?: string | undefined;
  width?: Numberish | undefined;
}
```

### Chip

Use a prop `chip` para exibir um componente [Chip](https://ui.nitro.news/docs/components/chip).

```vue
<template>
  <UUser name="John Doe" description="Software Engineer" :avatar="{
  src: 'https://i.pravatar.cc/150?u=john-doe'
}" :chip="{
  color: 'primary',
  position: 'top-right'
}" />
</template>
```

```ts
/**
 * Props for the Chip component
 */
interface ChipProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  /**
   * Display some text inside the chip.
   */
  text?: string | number | undefined;
  color?: "primary" | "secondary" | "accent" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
  size?: "xs" | "sm" | "md" | "lg" | "xl" | "3xs" | "2xs" | "2xl" | "3xl" | undefined;
  /**
   * The position of the chip.
   */
  position?: "top-right" | "bottom-right" | "top-left" | "bottom-left" | undefined;
  /**
   * When `true`, keep the chip inside the component for rounded elements.
   * @default "false"
   */
  inset?: boolean | undefined;
  /**
   * When `true`, render the chip relatively to the parent.
   * @default "false"
   */
  standalone?: boolean | undefined;
  ui?: { root?: SlotClass; base?: SlotClass; } | undefined;
  /**
   * @default "true"
   */
  show?: boolean | undefined;
}
```

### Tamanho

Use a prop `size` para alterar o tamanho do avatar e do texto do usuário.

```vue
<template>
  <UUser name="John Doe" description="Software Engineer" :avatar="{
  src: 'https://i.pravatar.cc/150?u=john-doe'
}" chip size="xl" />
</template>
```

### Orientação

Use a prop `orientation` para alterar a orientação. O padrão é `horizontal`.

```vue
<template>
  <UUser orientation="vertical" name="John Doe" description="Software Engineer" :avatar="{
  src: 'https://i.pravatar.cc/150?u=john-doe'
}" />
</template>
```

### Link

Você pode passar qualquer propriedade do componente [`<NuxtLink>`](https://nuxt.com/docs/api/components/nuxt-link){rel="&#x22;nofollow&#x22;"}, como `to`, `target`, `rel`, etc.

```vue
<template>
  <UUser to="https://github.com/benjamincanac" target="_blank" name="Benjamin Canac" description="Software Engineer" :avatar="{
  src: 'https://github.com/benjamincanac.png'
}" />
</template>
```

> \[!NOTE]
>
> O componente `NuxtLink` herdará todos os outros atributos que você passar para o componente `User`.

## API

### Props

```ts
/**
 * Props for the User component
 */
interface UserProps {
  /**
   * The element or component this component should render as.
   */
  as?: any;
  name?: string | undefined;
  description?: string | undefined;
  avatar?: (Omit<AvatarProps, "size"> & { [key: string]: any; }) | undefined;
  chip?: boolean | Omit<ChipProps, "size" | "inset"> | undefined;
  size?: "md" | "3xs" | "2xs" | "xs" | "sm" | "lg" | "xl" | "2xl" | "3xl" | undefined;
  /**
   * The orientation of the user.
   * @default "\"horizontal\""
   */
  orientation?: "horizontal" | "vertical" | undefined;
  to?: string | it | et | undefined;
  target?: "_blank" | "_parent" | "_self" | "_top" | (string & {}) | null | undefined;
  onClick?: ((event: MouseEvent) => void) | undefined;
  ui?: { root?: SlotClass; wrapper?: SlotClass; name?: SlotClass; description?: SlotClass; avatar?: SlotClass; } | undefined;
}
```

### Slots

```ts
/**
 * Slots for the User component
 */
interface UserSlots {
  avatar(): any;
  name(): any;
  description(): any;
  default(): any;
}
```

## Tema

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    user: {
      slots: {
        root: 'relative group/user',
        wrapper: '',
        name: 'font-medium',
        description: 'text-muted',
        avatar: 'shrink-0'
      },
      variants: {
        orientation: {
          horizontal: {
            root: 'flex items-center'
          },
          vertical: {
            root: 'flex flex-col'
          }
        },
        to: {
          true: {
            name: [
              'text-default peer-hover:text-highlighted peer-focus-visible:text-highlighted',
              'transition-colors'
            ],
            description: [
              'peer-hover:text-toned peer-focus-visible:text-toned',
              'transition-colors'
            ],
            avatar: 'transform transition-transform duration-200 group-hover/user:scale-115 group-has-focus-visible/user:scale-115'
          },
          false: {
            name: 'text-highlighted',
            description: ''
          }
        },
        size: {
          '3xs': {
            root: 'gap-1',
            wrapper: 'flex items-center gap-1',
            name: 'text-xs',
            description: 'text-xs'
          },
          '2xs': {
            root: 'gap-1.5',
            wrapper: 'flex items-center gap-1.5',
            name: 'text-xs',
            description: 'text-xs'
          },
          xs: {
            root: 'gap-1.5',
            wrapper: 'flex items-center gap-1.5',
            name: 'text-xs',
            description: 'text-xs'
          },
          sm: {
            root: 'gap-2',
            name: 'text-xs',
            description: 'text-xs'
          },
          md: {
            root: 'gap-2',
            name: 'text-sm',
            description: 'text-xs'
          },
          lg: {
            root: 'gap-2.5',
            name: 'text-sm',
            description: 'text-sm'
          },
          xl: {
            root: 'gap-2.5',
            name: 'text-base',
            description: 'text-sm'
          },
          '2xl': {
            root: 'gap-3',
            name: 'text-base',
            description: 'text-base'
          },
          '3xl': {
            root: 'gap-3',
            name: 'text-lg',
            description: 'text-base'
          }
        }
      },
      defaultVariants: {
        size: 'md'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/nuxt/ui/commits/v4/src/runtime/components/User.vue) and [theme](https://github.com/nuxt/ui/commits/v4/src/theme/user.ts).


# defineLocale

## Uso

Use o utilitário `defineLocale` para criar um locale personalizado com suas próprias traduções.

```vue
<script setup lang="ts">
import type { Messages } from '@nitro/ui'

const locale = defineLocale<Messages>({
  name: 'My custom locale',
  code: 'en',
  dir: 'ltr',
  messages: {
    // implement pairs
  }
})
</script>

<template>
  <NApp :locale="locale">
    <NuxtPage />
  </NApp>
</template>
```

> \[!TIP]
> See: /docs/getting-started/integrations/i18n
>
> Saiba mais sobre internacionalização na documentação de **integração com i18n**.

## API

`defineLocale<M>(options: DefineLocaleOptions<M>): Locale<M>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Cria um novo objeto de locale com as opções fornecidas.

#### Parâmetros

**options** (`DefineLocaleOptions<M>`) *required*: The locale configuration object with the following properties\:The display name of the locale (e.g., 'English', 'Français').The ISO code of the locale (e.g., 'en', 'fr', 'de-AT').The text direction of the locale. Defaults to 'ltr'.The translation messages object. Use the Messages type from @nitro/ui for type safety.

**Returns:** A `Locale<M>` object that can be passed to the `locale` prop of the [App](https://ui.nitro.news/docs/components/app) component.

## Exemplo

Aqui está um exemplo completo de criação de um locale personalizado:

```vue
<script setup lang="ts">
import type { Messages } from '@nitro/ui'

const locale = defineLocale<Messages>({
  name: 'Español',
  code: 'es',
  dir: 'ltr',
  messages: {
    alert: {
      close: 'Cerrar'
    },
    modal: {
      close: 'Cerrar'
    },
    commandPalette: {
      back: 'Atrás',
      close: 'Cerrar',
      noData: 'Sin datos',
      noMatch: 'Sin resultados',
      placeholder: 'Escribe un comando o busca…'
    }
    // ... other component messages
  }
})
</script>

<template>
  <NApp :locale="locale">
    <NuxtPage />
  </NApp>
</template>
```

> \[!NOTE]
>
> Você pode consultar os [locales embutidos](https://github.com/nuxt/ui/tree/v4/src/runtime/locale){rel="&#x22;nofollow&#x22;"} como referência de como estruturar o objeto messages.


# defineShortcuts

## Uso

Use o composable `defineShortcuts`, importado automaticamente, para definir atalhos de teclado.

```vue
<script setup lang="ts">
const open = ref(false)

defineShortcuts({
  meta_k: () => {
    open.value = !open.value
  }
})
</script>
```

- Shortcuts are automatically adjusted for non-macOS platforms, converting `meta` to `ctrl`.
- The composable uses VueUse's [`useEventListener`](https://vueuse.org/core/useEventListener/){rel="&#x22;nofollow&#x22;"} to handle keydown events.
- For a complete list of available shortcut keys, refer to the [`KeyboardEvent.key`](https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_key_values){rel="&#x22;nofollow&#x22;"} API documentation. Note that the key should be written in lowercase.

> \[!TIP]
> See: /docs/components/kbd
>
> Aprenda a exibir atalhos nos componentes na documentação do componente **Kbd**.

## API

`defineShortcuts(config: ShortcutsConfig, options?: ShortcutsOptions): void`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Defina atalhos de teclado para a sua aplicação.

#### Parâmetros

**config** (`ShortcutsConfig`) *required*: An object where keys are shortcut definitions and values are either handler functions or shortcut configuration objects.

**options** (`ShortcutsOptions`): Optional configuration for the shortcuts behavior.The delay between key presses to consider the shortcut as chained. Default is 800.When enabled, shortcuts work consistently across different keyboard layouts (Arabic, Hebrew) by matching physical key positions rather than character values.false (default): Uses e.key for character-based matching (Layout specific)true: Uses e.code for physical key matching (Layout agnostic)

#### Definição do atalho

Os atalhos são definidos usando o seguinte formato:

- Single key: `'a'`, `'b'`, `'1'`, `'?'`, etc.
- Key combinations: Use `_` to separate keys, e.g., `'meta_k'`, `'ctrl_shift_f'`
- Key sequences: Use `-` to define a sequence, e.g., `'g-d'`

#### Modificadores

- `meta`: Represents `⌘ Command` on macOS and `Ctrl` on other platforms
- `ctrl`: Represents `Ctrl` on all platforms
- `shift`: Used for alphabetic keys when Shift is required

#### Teclas especiais

- `escape`: Triggers on Esc key
- `enter`: Triggers on Enter key
- `arrowleft`, `arrowright`, `arrowup`, `arrowdown`: Trigger on respective arrow keys

#### Configuração do atalho

Cada atalho pode ser definido como uma função ou um objeto com as seguintes propriedades:

`interface ShortcutConfig { handler: () => void; usingInput?: boolean | string }`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

#### Parâmetros

**handler** (`() => void`) *required*: Function to be executed when the shortcut is triggered.

**usingInput** (`boolean | string`): Controls when the shortcut should trigger based on input focus\:false (default): Shortcut only triggers when no input is focusedtrue: Shortcut triggers even when any input is focusedstring: Shortcut only triggers when the specified input (by name) is focused

## Exemplos

### Uso básico

```vue
<script setup lang="ts">
defineShortcuts({
  '?': () => openHelpModal(),
  'meta_k': () => openCommandPalette(),
  'g-d': () => navigateToDashboard()
})
</script>
```

### Com tratamento de foco do input

A opção `usingInput` permite especificar que um atalho só deve ser disparado quando um input específico estiver em foco.

```vue
<template>
  <NInput v-model="query" name="queryInput" />
</template>

<script setup lang="ts">
const query = ref('')

defineShortcuts({
  enter: {
    usingInput: 'queryInput',
    handler: () => performSearch()
  },
  escape: {
    usingInput: true,
    handler: () => clearSearch()
  }
})
</script>
```

### Extraindo atalhos dos itens de menu

Use o utilitário `extractShortcuts` para definir atalhos automaticamente a partir de itens de menu.

> \[!TIP]
> See: /docs/composables/extract-shortcuts
>
> Learn more about the **extractShortcuts** utility.


# extendLocale

## Uso

Use o utilitário `extendLocale` para personalizar um locale existente sobrescrevendo propriedades ou mensagens específicas.

```vue
<script setup lang="ts">
import { en } from '@nitro/ui/locale'

const locale = extendLocale(en, {
  code: 'en-AU',
  messages: {
    commandPalette: {
      placeholder: 'Search a component...'
    }
  }
})
</script>

<template>
  <NApp :locale="locale">
    <NuxtPage />
  </NApp>
</template>
```

Isso é útil quando você quer:

- Create a regional variant of a language (e.g., `en-AU` from `en`)
- Override specific translations without redefining the entire locale
- Customize component labels for your application

> \[!TIP]
> See: /docs/getting-started/integrations/i18n
>
> Saiba mais sobre internacionalização na documentação de **integração com i18n**.

## API

`extendLocale<M>(locale: Locale<M>, options: Partial<DefineLocaleOptions<DeepPartial<M>>>): Locale<M>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Estende um locale existente com as opções fornecidas, mesclando as mensagens em profundidade.

#### Parâmetros

**locale** (`Locale<M>`) *required*: The base locale to extend. Import from @nitro/ui/locale.

**options** (`Partial<DefineLocaleOptions<DeepPartial<M>>>`) *required*: The properties to override\:Override the display name of the locale.Override the ISO code of the locale (e.g., 'en-GB', 'fr-CA').Override the text direction of the locale.Partial messages object to merge with the base locale. Only specify the messages you want to override.

**Returns:** A new `Locale<M>` object with the merged properties.

## Exemplo

Aqui está um exemplo estendendo o locale em inglês para uma variante australiana:

```vue
<script setup lang="ts">
import { en } from '@nitro/ui/locale'

const locale = extendLocale(en, {
  name: 'English (Australia)',
  code: 'en-AU',
  messages: {
    colorMode: {
      dark: 'Dark',
      light: 'Light',
      system: 'System'
    },
    selectMenu: {
      search: 'Search…',
      noData: 'No results found',
      noMatch: 'No matching results'
    }
  }
})
</script>

<template>
  <NApp :locale="locale">
    <NuxtPage />
  </NApp>
</template>
```

> \[!NOTE]
>
> O utilitário `extendLocale` usa mesclagem profunda, então você só precisa especificar as mensagens que quer sobrescrever. Todas as outras mensagens serão herdadas do locale base.


# extractShortcuts

## Uso

Use o utilitário `extractShortcuts`, importado automaticamente, para definir atalhos de teclado a partir de itens de menu. Ele extrai atalhos de componentes como [DropdownMenu](https://ui.nitro.news/docs/components/dropdown-menu), [ContextMenu](https://ui.nitro.news/docs/components/context-menu) ou [CommandPalette](https://ui.nitro.news/docs/components/command-palette) em que os itens têm `kbds` definidos.

```vue
<script setup lang="ts">
const items = [{
  label: 'Save',
  icon: 'i-lucide-file-down',
  kbds: ['meta', 'S'],
  onSelect() {
    save()
  }
}, {
  label: 'Copy',
  icon: 'i-lucide-copy',
  kbds: ['meta', 'C'],
  onSelect() {
    copy()
  }
}]

defineShortcuts(extractShortcuts(items))
</script>
```

> \[!TIP]
> See: /docs/composables/define-shortcuts
>
> Saiba mais sobre atalhos de teclado na documentação do composable **defineShortcuts**.

## API

`extractShortcuts(items: any[] | any[][], separator?: '_' | '-'): ShortcutsConfig`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Extrai atalhos de teclado de um array de itens de menu e retorna um objeto de configuração compatível com `defineShortcuts`.

#### Parâmetros

**items** (`any[] | any[][]`) *required*: An array of menu items (or nested arrays) containing shortcut definitions. Each item can have the following properties\:An array of keyboard keys that form the shortcut (e.g., \['meta', 'S']).A callback function to execute when the shortcut is triggered.An alternative callback function (used if onSelect is not defined).Nested menu items to recursively extract shortcuts from.Alternative property for nested menu items.

**separator** (`'_' | '-'`): The separator used to join keyboard keys. Use '\_' for key combinations (e.g., meta\_k) or '-' for key sequences (e.g., g-d). Defaults to '\_'.

**Returns:** A `ShortcutsConfig` object that can be passed directly to `defineShortcuts`.

## Exemplos

### Com itens aninhados

O utilitário percorre recursivamente as propriedades `children` e `items` para extrair atalhos de estruturas de menu aninhadas.

```vue
<script setup lang="ts">
import type { DropdownMenuItem } from '@nitro/ui'

const items: DropdownMenuItem[][] = [[{
  label: 'Edit',
  icon: 'i-lucide-pencil',
  kbds: ['E'],
  onSelect() {
    edit()
  }
}, {
  label: 'Duplicate',
  icon: 'i-lucide-copy',
  kbds: ['D'],
  onSelect() {
    duplicate()
  }
}], [{
  label: 'Invite users',
  icon: 'i-lucide-user-plus',
  children: [[{
    label: 'Invite by email',
    icon: 'i-lucide-send-horizontal',
    kbds: ['meta', 'E'],
    onSelect() {
      inviteByEmail()
    }
  }, {
    label: 'Invite by link',
    icon: 'i-lucide-link',
    kbds: ['meta', 'I'],
    onSelect() {
      inviteByLink()
    }
  }]]
}], [{
  label: 'Delete',
  icon: 'i-lucide-trash',
  kbds: ['meta', 'backspace'],
  onSelect() {
    remove()
  }
}]]

defineShortcuts(extractShortcuts(items))
</script>

<template>
  <NDropdownMenu :items="items">
    <NButton label="Actions" />
  </NDropdownMenu>
</template>
```

### Com sequências de teclas

Use o parâmetro `separator` para criar sequências de teclas em vez de combinações de teclas.

```vue
<script setup lang="ts">
const items = [{
  label: 'Go to Dashboard',
  kbds: ['G', 'D'],
  onSelect() {
    navigateTo('/dashboard')
  }
}, {
  label: 'Go to Settings',
  kbds: ['G', 'S'],
  onSelect() {
    navigateTo('/settings')
  }
}]

// Using '-' creates key sequences: 'g-d', 'g-s'
defineShortcuts(extractShortcuts(items, '-'))
</script>
```


# useOverlay

## Uso

Use o composable `useOverlay`, importado automaticamente, para controlar programaticamente os componentes [Modal](https://ui.nitro.news/docs/components/modal) e [Slideover](https://ui.nitro.news/docs/components/slideover).

:component-example{name="use-overlay-example"}

- The `useOverlay` composable is created using `createSharedComposable`, ensuring that the same overlay state is shared across your entire application.

> \[!NOTE]
>
> Para retornar um valor do overlay, você pode usar `await` em `overlay.open()`. Para que isso funcione, no entanto, o &#x2A;*componente de overlay precisa emitir um evento `close`**. Veja o exemplo abaixo para mais detalhes.

## API

`useOverlay()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

O composable `useOverlay` fornece métodos para gerenciar overlays globalmente. Cada overlay criado retorna uma instância com seus próprios métodos.

### create()

`create(component: T, options: OverlayOptions): OverlayInstance`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Cria um overlay e retorna uma instância de fábrica.

#### Parâmetros

**component** (`T`) *required*: The overlay component to render.

**options** (`OverlayOptions`): Configuration options for the overlay.Open the overlay immediately after being created. Defaults to false.An optional object of props to pass to the rendered component.Removes the overlay from memory when closed. Defaults to false.

### open()

`open(id: symbol, props?: ComponentProps<T>): OpenedOverlay<T>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Open an overlay by its `id`.

#### Parâmetros

**id** (`symbol`) *required*: The identifier of the overlay.

**props** (`ComponentProps<T>`): An optional object of props to pass to the rendered component.

### close()

`close(id: symbol, value?: any): void`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Close an overlay by its `id`.

#### Parâmetros

**id** (`symbol`) *required*: The identifier of the overlay.

**value** (`any`): A value to resolve the overlay promise with.

### closeAll()

`closeAll(): void`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Close all open overlays.

### patch()

`patch(id: symbol, props: Partial<ComponentProps<T>>): void`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Update an overlay by its `id`.

#### Parâmetros

**id** (`symbol`) *required*: The identifier of the overlay.

**props** (`Partial<ComponentProps<T>>`) *required*: An object of props to update on the rendered component.

### unmount()

`unmount(id: symbol): void`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Remove um overlay do DOM pelo seu `id`.

#### Parâmetros

**id** (`symbol`) *required*: The identifier of the overlay.

### isOpen()

`isOpen(id: symbol): boolean`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Verifica se um overlay está aberto usando seu `id`.

#### Parâmetros

**id** (`symbol`) *required*: The identifier of the overlay.

### overlays

`overlays: Overlay[]`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Lista em memória de todos os overlays que foram criados.

## API da instância

### open()

`open(props?: ComponentProps<T>): OpenedOverlay<T>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Abre o overlay. Retorna um `OpenedOverlay`, que é uma Promise resolvida com o valor emitido pelo evento `close`.

#### Parâmetros

**props** (`ComponentProps<T>`): An optional object of props to pass to the rendered component.

```vue
<script setup lang="ts">
import { LazyModalExample } from '#components'

const overlay = useOverlay()

const modal = overlay.create(LazyModalExample)

function openModal() {
  modal.open({
    title: 'Welcome'
  })
}
</script>
```

### close()

`close(value?: any): void`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Close the overlay.

#### Parâmetros

**value** (`any`): A value to resolve the overlay promise with.

### patch()

`patch(props: Partial<ComponentProps<T>>): void`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Atualiza as props do overlay.

#### Parâmetros

**props** (`Partial<ComponentProps<T>>`) *required*: An object of props to update on the rendered component.

```vue
<script setup lang="ts">
import { LazyModalExample } from '#components'

const overlay = useOverlay()

const modal = overlay.create(LazyModalExample, {
  props: { title: 'Welcome' }
})

function openModal() {
  modal.open()
}

function updateModalTitle() {
  modal.patch({ title: 'Updated Title' })
}
</script>
```

## Exemplos

### Com múltiplos overlays

Este exemplo demonstra como gerenciar múltiplos overlays e passar dados entre eles:

```vue
<script setup lang="ts">
import { ModalA, ModalB, SlideoverA } from '#components'

const overlay = useOverlay()

// Create with default props
const modalA = overlay.create(ModalA, { props: { title: 'Welcome' } })
const modalB = overlay.create(ModalB)
const slideoverA = overlay.create(SlideoverA)

const openModalA = () => {
  // Open modalA, but override the title prop
  modalA.open({ title: 'Hello' })
}

const openModalB = async () => {
  // Open modalB, and wait for its result
  const input = await modalB.open()

  // Pass the result from modalB to the slideover, and open it
  slideoverA.open({ input })
}
</script>

<template>
  <NButton label="Open Modal" @click="openModalA" />
</template>
```

### Diálogo de confirmação

Este exemplo demonstra como criar um padrão reutilizável de diálogo de confirmação usando um composable `useConfirmDialog` personalizado que envolve o `useOverlay`. Essa abordagem permite diálogos opinativos, adaptados a requisitos de negócio e preferências de design específicos.

1. Crie um componente `ConfirmDialog` que emite um valor booleano quando fechado:

```vue [components/ConfirmDialog.vue]
<script lang="ts" setup>
interface ConfirmDialogProps {
  title?: string
  description?: string
}

defineProps<ConfirmDialogProps>()

const emits = defineEmits<{
  close: [value: boolean]
}>()
</script>

<template>
  <NModal
    :title="title"
    :description="description"
    :dismissible="false"
    :ui="{ footer: 'justify-end' }"
  >
    <template #footer>
      <NButton label="Cancel" color="neutral" variant="outline" @click="emits('close', false)" />
      <NButton label="Confirm" color="neutral" @click="emits('close', true)" />
    </template>
  </NModal>
</template>
```

2. Crie um composable `useConfirmDialog` que retorna uma Promise:

```ts [composables/useConfirmDialog.ts]
import { ConfirmDialog } from '#components'

export interface ConfirmDialogOptions {
  title: string
  description?: string
}

export const useConfirmDialog = () => {
  const overlay = useOverlay()

  return (options: ConfirmDialogOptions): Promise<boolean> => {
    const modal = overlay.create(ConfirmDialog, {
      destroyOnClose: true,
      props: options
    })

    return modal.open()
  }
}
```

3. Use o composable nos seus componentes:

```vue
<script setup lang="ts">
const confirm = useConfirmDialog()

const handleDelete = async () => {
  const confirmed = await confirm({
    title: 'Delete item',
    description: 'Are you sure you want to delete this item?'
  })

  if (confirmed) {
    console.log('Item deleted')
  }
}
</script>

<template>
  <NButton label="Delete item" @click="handleDelete" />
</template>
```

## Ressalvas

### Provide / Inject

Ao abrir overlays programaticamente (ex.: modais, slideovers, etc.), o componente de overlay só consegue acessar valores injetados a partir do componente que contém `UApp` (normalmente `app.vue` ou componentes de layout). Isso acontece porque os overlays são montados fora do contexto da página pelo componente `UApp`.

Por isso, usar `provide()` em páginas ou componentes pais não é suportado diretamente. Para passar valores fornecidos aos overlays, a abordagem recomendada é usar props:

```vue
<script setup lang="ts">
import { LazyModalExample } from '#components'

const overlay = useOverlay()

const providedValue = inject('valueProvidedInPage')

const modal = overlay.create(LazyModalExample, {
  props: {
    providedValue
  }
})
</script>
```


# useScrollShadow

## Uso

Use o composable `useScrollShadow`, importado automaticamente, para aplicar sombras de esmaecimento nas bordas de um elemento rolável, indicando que há mais conteúdo disponível na direção da rolagem.

:component-example{name="use-scroll-shadow-example"}

- Uses CSS `mask-image` to fade content at the edges rather than overlay elements, so it works on any background.
- Automatically detects whether the element is overflowing and only applies shadows when needed.
- Supports both vertical and horizontal orientations.

## API

`useScrollShadow(element, options?)`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

### Parâmetros

**element** (`MaybeRef<HTMLElement | null | undefined>`) *required*: A template ref or reactive reference to the scrollable element.

**options** (`UseScrollShadowOptions`): Configuration options for the scroll shadow\.The shadow size in pixels.The scroll direction to apply shadows.

### Retorno

**style** (`ComputedRef<CSSProperties | undefined>`): A reactive style object to bind on the scrollable element with \:style. Contains maskImage when shadows are active, undefined otherwise.

**isOverflowing** (`ComputedRef<boolean>`): Whether the element's content overflows its visible area.

**arrivedState** (`{ top: boolean, bottom: boolean, left: boolean, right: boolean }`): Reactive scroll arrival state from useScroll.

## Exemplos

### Horizontal

Use a opção `orientation` para containers roláveis na horizontal:

```vue
<script setup lang="ts">
const el = useTemplateRef('el')

const { style } = useScrollShadow(el, { orientation: 'horizontal' })
</script>

<template>
  <div ref="el" class="overflow-x-auto whitespace-nowrap" :style="style">
    <!-- Horizontally scrollable content -->
  </div>
</template>
```

### Tamanho personalizado

Use a opção `size` para alterar o tamanho da sombra em pixels:

```vue
<script setup lang="ts">
const el = useTemplateRef('el')

const { style } = useScrollShadow(el, { size: 48 })
</script>

<template>
  <div ref="el" class="max-h-[300px] overflow-y-auto" :style="style">
    <!-- Scrollable content -->
  </div>
</template>
```


# useToast

## Uso

Use o composable `useToast`, importado automaticamente, para exibir notificações [Toast](https://ui.nitro.news/docs/components/toast).

:component-example{name="use-toast-example"}

- The `useToast` composable uses Nuxt's `useState` to manage the toast state, ensuring reactivity across your application.
- A maximum of 5 toasts are displayed at a time. When adding a new toast that would exceed this limit, the oldest toast is automatically removed.
- When removing a toast, there's a 200ms delay before it's actually removed from the state, allowing for exit animations.

> \[!WARNING]
>
> Certifique-se de envolver seu app com o componente [`App`](https://ui.nitro.news/docs/components/app), que usa nosso componente [`Toaster`](https://github.com/nuxt/ui/blob/v4/src/runtime/components/Toaster.vue){rel="&#x22;nofollow&#x22;"}, que por sua vez usa o componente [`ToastProvider`](https://reka-ui.com/docs/components/toast#provider){rel="&#x22;nofollow&#x22;"} do Reka UI.

> \[!TIP]
> See: /docs/components/toast
>
> Aprenda a personalizar a aparência e o comportamento dos toasts na documentação do componente **Toast**.

## API

`useToast()`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

O composable `useToast` fornece métodos para gerenciar as notificações toast globalmente.

### add()

`add(toast: Partial<Toast>): Toast`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Adds a new toast notification.

#### Parâmetros

**toast** (`Partial<Toast>`) *required*: A partial Toast object with the following properties\:A unique identifier for the toast. If not provided, a timestamp will be used.Whether the toast is open. Defaults to true.The title displayed in the toast.The description displayed in the toast.The icon displayed in the toast.The avatar displayed in the toast. See Avatar.The color of the toast.The orientation between the content and the actions. Defaults to vertical.Customize or hide the close button (with false value). Defaults to true.The icon displayed in the close button.The actions displayed in the toast. See Button.Customize or hide the progress bar (with false value). Defaults to true.The duration in milliseconds before the toast auto-closes. Can also be set globally on the App component.A callback function invoked when the toast is clicked.A callback function invoked when the toast open state changes. Useful to perform an action when the toast closes (expired or dismissed).

**Returns:** The complete `Toast` object that was added.

```vue
<script setup lang="ts">
const toast = useToast()

function showToast() {
  toast.add({
    title: 'Success',
    description: 'Your action was completed successfully.',
    color: 'success'
  })
}
</script>
```

### update()

`update(id: string | number, toast: Partial<Toast>): void`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Updates an existing toast notification.

#### Parâmetros

**id** (`string | number`) *required*: The unique identifier of the toast to update.

**toast** (`Partial<Toast>`) *required*: A partial Toast object with the properties to update.

```vue
<script setup lang="ts">
const toast = useToast()

function updateToast(id: string | number) {
  toast.update(id, {
    title: 'Updated Toast',
    description: 'This toast has been updated.'
  })
}
</script>
```

### remove()

`remove(id: string | number): void`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Removes a toast notification.

#### Parâmetros

**id** (`string | number`) *required*: The unique identifier of the toast to remove.

```vue
<script setup lang="ts">
const toast = useToast()

function removeToast(id: string | number) {
  toast.remove(id)
}
</script>
```

### clear()

`clear(): void`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

Removes all toast notifications.

```vue
<script setup lang="ts">
const toast = useToast()

function clearAllToasts() {
  toast.clear()
}
</script>
```

### toasts

`toasts: Ref<Toast[]>`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

A reactive array containing all current toast notifications.

```vue
<script setup lang="ts">
const { toasts } = useToast()
</script>

<template>
  <div>
    <pre>{{ toasts }}</pre>
  </div>
</template>
```


# useTour

## Uso

Use o composable `useTour`, importado automaticamente, para conduzir um tour guiado com um único [Popover](https://ui.nitro.news/docs/components/popover) cuja âncora se move entre as etapas. O composable controla o estado das etapas e resolve o `target` de cada etapa em uma `reference` que você vincula ao `<NPopover>`, enquanto você mantém controle total sobre o conteúdo e a navegação.

::component-example{collapse name="use-tour-example"}
::

Cada etapa exige um `target` no qual o popover se ancora. Ele aceita um seletor CSS, um elemento, um elemento virtual (qualquer coisa com `getBoundingClientRect`) ou um ref/getter que retorne um deles. Passe `null` para ancorar a etapa no centro da viewport. Qualquer outro campo de uma etapa (`title`, `body`, `side`, …) é repassado sem alterações e fica disponível via `current`.

```vue
<script setup lang="ts">
const card = useTemplateRef('card')

const tour = useTour([
  { target: '#cta', title: 'Get started' },
  { target: () => card.value, title: 'Profile', side: 'right' },
  { target: null, title: 'All set' }
])
</script>

<template>
  <NButton @click="tour.start()">Start tour</NButton>

  <NPopover :open="tour.open.value" :reference="tour.reference.value" :dismissible="false">
    <template #content>
      <!-- your content + buttons -->
      <NButton :disabled="!tour.hasPrev.value" @click="tour.prev()">Back</NButton>
      <NButton @click="tour.next()">{{ tour.hasNext.value ? 'Next' : 'Finish' }}</NButton>
    </template>
  </NPopover>
</template>
```

- Built on the Popover's reactive `reference` prop, so the popover smoothly repositions when the active step changes.
- The active target is scrolled into view automatically when a step becomes active.
- Since you render the content yourself, there is no extra theme or locale to maintain.

## API

`useTour(steps, options?)`{.shiki,shiki-themes,material-theme-lighter,material-theme,material-theme-palenight lang="ts-type"}

### Parâmetros

**steps** (`MaybeRefOrGetter<TourStep[]>`) *required*: The list of tour steps. Can be a static array, a ref, or a getter for reactive steps.The element the step anchors to. Accepts a CSS selector ('#id', '.class', or a bare id resolved as #id), an element, a virtual element, or a ref/getter returning one. Use null to center the step in the viewport.Any additional fields (title, body, side, …) are passed through and available via current.

**options** (`UseTourOptions`): Configuration options for the tour.The step index the tour starts on.Loop back to the first step after the last one.Scroll the target into view when a step becomes active.

### Retorno

**open** (`Ref<boolean>`): Whether the tour is currently open.

**index** (`Ref<number>`): The current step index, clamped to the steps range.

**current** (`ComputedRef<TourStep | undefined>`): The current step object, or undefined when there are no steps.

**reference** (`ComputedRef<ReferenceElement | undefined>`): The resolved anchor for the current step, to pass to \<NPopover \:reference>.

**total** (`ComputedRef<number>`): The total number of steps.

**hasNext** (`ComputedRef<boolean>`): Whether a next step exists.

**hasPrev** (`ComputedRef<boolean>`): Whether a previous step exists.

**start** (`(index?: number) => void`): Open the tour, optionally at a given index.

**next** (`() => void`): Go to the next step. Loops or finishes at the end depending on the loop option.

**prev** (`() => void`): Go to the previous step.

**goTo** (`(index: number) => void`): Jump to a specific step and open the tour.

**finish** (`() => void`): Close the tour.