Instalação

Aprenda a instalar e configurar o Nitro UI na sua aplicação Vue, compatível tanto com o Vite puro quanto com o Inertia.

Configuração

Adicionar a um projeto Vue

Instale o pacote do Nitro UI

pnpm add @nitro/ui tailwindcss

yarn add @nitro/ui tailwindcss

npm install @nitro/ui tailwindcss

bun add @nitro/ui tailwindcss

Adicione o plugin Vite do Nitro UI no seu `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()
  ]
})

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'
    })
  ]
})

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'
    })
  ]
})

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.

tsconfig.app.json

{
  "include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.vue", "auto-imports.d.ts", "components.d.ts"]
}

.gitignore

# Auto-generated type declarations
auto-imports.d.ts
components.d.ts

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.

tsconfig.node.json

{
  "compilerOptions": {
    "paths": {
      "#build/ui": [
        "./node_modules/.nuxt-ui/ui"
      ]
    }
  }
}

tsconfig.app.json

{
  "compilerOptions": {
    "paths": {
      "#build/ui/*": [
        "./node_modules/.nuxt-ui/ui/*"
      ]
    }
  }
}

Use o plugin Vue do Nitro UI

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')

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)
  }
})

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

@import "tailwindcss";
@import "@nitro/ui";

@import "tailwindcss";
@import "@nitro/ui";

@import "tailwindcss";
@import "@nitro/ui";

Importe o arquivo CSS no seu ponto de entrada.

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')

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)
  }
})

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)
  }
})

É 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

<template>
  <NApp>
    <RouterView />
  </NApp>
</template>

<template>
  <NApp>
    <!-- Your content goes here -->
  </NApp>
</template>

<template>
  <NApp>
    <!-- Your content goes here -->
  </NApp>
</template>

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

<!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>

<!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>

<!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>

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

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({
      prefix: 'Nuxt'
    })
  ]
})

`ui`

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

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: '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

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
    })
  ]
})

`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']

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({
      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

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({
      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

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({
      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' }

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({
      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.

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'
      }
    })
  ]
})

@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:

<!-- 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 habilitar os componentes Prose do Nitro UI e o tema deles.

Default: false

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({
      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.

Default: {}

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({
      autoImport: false
    })
  ]
})

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.

Default: {}

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({
      components: false
    })
  ]
})

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 ou Hybridly.

Default: true

Value	Description
`true`	Uses `vue-router` for navigation with `RouterLink` component.
`false`	Disables routing integration, links render as plain `<a>` tags.
`'inertia'`	Uses Inertia.js for navigation with its `Link` component.

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({
      router: false
    })
  ]
})

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:

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 })
  }
})

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.

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({
      scanPackages: ['@my-org/ui-components']
    })
  ]
})

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 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.

electron.vite.config.ts

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
      })
    ]
  }
})

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 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.