Instalação

Template
Aprenda a instalar e configurar o Nitro UI na sua aplicação Nuxt.

Configuração

Adicionar a um projeto Nuxt

Instale o pacote do Nitro UI

pnpm add @nitro/ui tailwindcss

Adicione o módulo do Nitro UI no seu nuxt.config.ts

nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nitro/ui']
})
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

@import "tailwindcss";
@import "@nitro/ui";
Ao usar Nuxt Layers, o módulo gera automaticamente diretivas @source 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.
É recomendado instalar a extensão Tailwind CSS IntelliSense para o VSCode e adicionar as seguintes configurações:
.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

app.vue
<template>
  <NApp>
    <NuxtPage />
  </NApp>
</template>
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:

npm create nuxt@latest -- -t ui

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
nuxt.config.ts
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.

  • Default: true
nuxt.config.ts
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.

  • Default: true
nuxt.config.ts
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']
nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nitro/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    theme: {
      colors: ['primary', 'error']
    }
  }
})
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
nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nitro/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    theme: {
      transitions: false
    }
  }
})
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
nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nitro/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    theme: {
      unstyled: true
    }
  }
})
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' }
nuxt.config.ts
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.

export default defineNuxtConfig({
  modules: ['@nitro/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    theme: {
      prefix: 'tw'
    }
  }
})
Você pode precisar habilitar fonts.processCSSVariables para usar a opção de prefixo com o módulo @nuxt/fonts:
nuxt.config.ts
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:

<!-- 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>
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 do Nitro UI mesmo que o @nuxtjs/mdc ou o @nuxt/content não estejam instalados.

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

mdc Deprecated

Use a opção 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
nuxt.config.ts
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
  • Type: boolean | string[]

Enable automatic detection:

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

Include additional components for dynamic usage:

nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nitro/ui'],
  css: ['~/assets/css/main.css'],
  ui: {
    experimental: {
      componentDetection: ['Modal', 'Dropdown', 'Popover']
    }
  }
})
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 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.

package.json
{
  "dependencies": {
-   "@nitro/ui": "^4.0.0",
+   "@nitro/ui": "https://pkg.pr.new/@nitro/ui@4c96909",
  }
}
pkg.pr.new will automatically comment on PRs with the installation URL, making it easy to test changes.

Introdução

O Nitro UI é uma biblioteca completa de componentes de UI para Vue (Nuxt opcional), com mais de 125 componentes acessíveis baseados em Tailwind CSS para construir aplicações web modernas.

Contribuição

Um guia completo sobre como contribuir com o Nitro UI, incluindo estrutura do projeto, fluxo de desenvolvimento e boas práticas.