mirror of
https://github.com/ArthurDanjou/ui.git
synced 2026-01-14 20:19:34 +01:00
264 lines
8.0 KiB
Markdown
264 lines
8.0 KiB
Markdown
---
|
|
title: Installation
|
|
description: 'Learn how to install and configure Nuxt UI in your application.'
|
|
---
|
|
|
|
## Setup
|
|
|
|
### Add to a Nuxt project
|
|
|
|
1. Add `@nuxt/ui` module to your project:
|
|
|
|
```bash
|
|
npx nuxi@latest module add ui
|
|
```
|
|
|
|
2. Add it to the `modules` section in your `nuxt.config.ts`:
|
|
|
|
```ts [nuxt.config.ts]
|
|
export default defineNuxtConfig({
|
|
modules: ['@nuxt/ui']
|
|
})
|
|
```
|
|
|
|
That's it! You can now use all the components and composables in your Nuxt app ✨
|
|
|
|
### Use Nuxt starter
|
|
|
|
[Nuxt Starter](https://nuxt.new/) template makes it easy to get started with Nuxt UI.
|
|
The Nuxt Starter template is available from the `nuxi init` command.
|
|
|
|
```bash
|
|
npx nuxi@latest init -t ui
|
|
```
|
|
|
|
Please check [nuxt/starter](https://github.com/nuxt/starter/tree/ui) for details.
|
|
|
|
## Modules
|
|
|
|
Nuxt UI will automatically install the [@nuxt/icon](https://github.com/nuxt/icon), [@nuxtjs/tailwindcss](https://tailwindcss.nuxtjs.org/) and [@nuxtjs/color-mode](https://color-mode.nuxtjs.org/) modules for you.
|
|
|
|
::callout{icon="i-heroicons-exclamation-triangle"}
|
|
You should remove them from your `modules` and `dependencies` if you've previously installed them.
|
|
::
|
|
|
|
### `@nuxt/icon`
|
|
|
|
This module is installed to provide an easy way to use icons in your application. You can use the `UIcon` component to display any icon from Iconify.
|
|
|
|
::callout{icon="i-heroicons-light-bulb"}
|
|
You can read more about this in the [Theming](/getting-started/theming#icons) section.
|
|
::
|
|
|
|
### `@nuxtjs/tailwindcss`
|
|
|
|
This module is pre-configured and will automatically load the following plugins:
|
|
|
|
- [@tailwindcss/forms](https://github.com/tailwindlabs/tailwindcss-forms)
|
|
- [@tailwindcss/typography](https://github.com/tailwindlabs/tailwindcss-typography)
|
|
- [@tailwindcss/aspect-ratio](https://github.com/tailwindlabs/tailwindcss-aspect-ratio)
|
|
- [@tailwindcss/container-queries](https://github.com/tailwindlabs/tailwindcss-container-queries)
|
|
- [@headlessui/tailwindcss](https://github.com/tailwindlabs/headlessui/tree/main/packages/%40headlessui-vue)
|
|
|
|
Note that the `@tailwindcss/aspect-ratio` plugin disables the default aspect ratio utilities:
|
|
|
|
- `aspect-auto`
|
|
- `aspect-square`
|
|
- `aspect-video`
|
|
|
|
You can re-enable them by adding the following to your `tailwind.config.ts`:
|
|
|
|
```ts [tailwind.config.ts]
|
|
import type { Config } from 'tailwindcss'
|
|
|
|
export default <Partial<Config>>{
|
|
theme: {
|
|
extend: {
|
|
aspectRatio: {
|
|
auto: 'auto',
|
|
square: '1 / 1',
|
|
video: '16 / 9'
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### `@nuxtjs/color-mode`
|
|
|
|
This module is installed to provide dark mode support out of the box thanks to the Tailwind CSS dark mode `class` strategy.
|
|
|
|
::callout{icon="i-heroicons-light-bulb"}
|
|
You can read more about this in the [Theming](/getting-started/theming#dark-mode) section.
|
|
::
|
|
|
|
## TypeScript
|
|
|
|
This module is written in TypeScript and provides typings for all the components and composables. You can look at the [source code](https://github.com/nuxt/ui/tree/dev/src/runtime/types) to see all the available types.
|
|
|
|
::callout{icon="i-heroicons-light-bulb" to="https://nuxt.com/docs/guide/concepts/typescript" target="_blank"}
|
|
You can read more about TypeScript on the official Nuxt documentation.
|
|
::
|
|
|
|
You can use those types in your own components by importing them from `#ui/types`, for example when defining wrapper components:
|
|
|
|
```vue
|
|
<template>
|
|
<UBreadcrumb :links="links">
|
|
<template #icon="{ link }">
|
|
<UIcon :name="link.icon" />
|
|
</template>
|
|
</UBreadcrumb>
|
|
</template>
|
|
|
|
<script setup lang="ts">
|
|
import type { BreadcrumbLink } from '#ui/types'
|
|
|
|
export interface Props {
|
|
links: BreadcrumbLink[]
|
|
}
|
|
|
|
defineProps<Props>()
|
|
</script>
|
|
```
|
|
|
|
You don't have to use TypeScript yourself, but doing so will give you access to prop validation and autocomplete.
|
|
|
|
We've managed to provide dynamic typings on props such as `color`, `size`, `variant`, etc. based on your custom config. For example, you'll be suggested the `custom` color and the `subtle` variant when using the `Button` component with an `app.config.ts` as such:
|
|
|
|
```ts [app.config.ts]
|
|
export default defineAppConfig({
|
|
ui: {
|
|
button: {
|
|
color: {
|
|
custom: {
|
|
subtle: '...'
|
|
}
|
|
}
|
|
}
|
|
}
|
|
})
|
|
```
|
|
|
|
::callout{icon="i-heroicons-light-bulb"}
|
|
You can read more about components configuration in the [Theming](/getting-started/theming#appconfigts) section.
|
|
::
|
|
|
|
## IntelliSense
|
|
|
|
If you're using VSCode, you can install the [Tailwind CSS IntelliSense](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss) extension to get autocompletion for the classes.
|
|
|
|
You can read more on how to set it up on the [@nuxtjs/tailwindcss](https://tailwindcss.nuxtjs.org/tailwind/editor-support) module documentation, but to summarize, you'll need to add the following to your `.vscode/settings.json`:
|
|
|
|
```json [.vscode/settings.json]
|
|
{
|
|
"files.associations": {
|
|
"*.css": "tailwindcss"
|
|
},
|
|
"editor.quickSuggestions": {
|
|
"strings": true
|
|
}
|
|
}
|
|
```
|
|
|
|
You can write your `tailwind.config` in TypeScript as such:
|
|
|
|
```ts [tailwind.config.ts]
|
|
import type { Config } from 'tailwindcss'
|
|
|
|
export default <Partial<Config>> {
|
|
content: [
|
|
'docs/content/**/*.md'
|
|
]
|
|
}
|
|
```
|
|
|
|
If you do so, you'll need to add the following to your `.vscode/settings.json`:
|
|
|
|
```json [.vscode/settings.json]
|
|
{
|
|
"tailwindCSS.experimental.configFile": "tailwind.config.ts"
|
|
}
|
|
```
|
|
|
|
Note, the extension won't work when writing classes in your `app.config.ts` by default.
|
|
|
|
Also, you might want IntelliSense on objects in your SFC by prefixing with `/*ui*/`.
|
|
|
|
To enable these two features, you can add the following to your `.vscode/settings.json`:
|
|
|
|
```json [.vscode/settings.json]
|
|
{
|
|
"tailwindCSS.experimental.classRegex": [
|
|
["ui:\\s*{([^)]*)\\s*}", "[\"'`]([^\"'`]*).*?[\"'`]"],
|
|
["/\\*\\s?ui\\s?\\*/\\s*{([^;]*)}", ":\\s*[\"'`]([^\"'`]*).*?[\"'`]"]
|
|
]
|
|
}
|
|
```
|
|
|
|
An example SFC using IntelliSense (note the `/*ui*/` prefix, also works with `ref()`):
|
|
|
|
```vue [example.vue]
|
|
<template>
|
|
<UCard :ui="ui" />
|
|
</template>
|
|
|
|
<script setup lang="ts">
|
|
const ui = /* ui */ {
|
|
background: 'bg-white dark:bg-slate-900'
|
|
}
|
|
</script>
|
|
```
|
|
|
|
You can also add the following to your `.vscode/settings.json` to enable IntelliSense when using the `ui` prop:
|
|
|
|
```json [.vscode/settings.json]
|
|
{
|
|
"tailwindCSS.classAttributes": [
|
|
"class",
|
|
"className",
|
|
"ngClass",
|
|
"ui"
|
|
]
|
|
}
|
|
```
|
|
|
|
## Options
|
|
|
|
| Key | Default | Description |
|
|
|-----------------------|-----------------|-------------------------------------------------------------------------------------------------------------|
|
|
| `prefix` | `u` | Define the prefix of the imported components. |
|
|
| `global` | `false` | Expose components globally. |
|
|
| `safelistColors` | `['primary']` | Force safelisting of colors to need be purged. |
|
|
| `disableGlobalStyles` | `false` | Disable [global CSS styles](https://github.com/nuxt/ui/blob/dev/src/runtime/ui.css) injected by the module. |
|
|
|
|
Configure options in your `nuxt.config.ts` as such:
|
|
|
|
```ts [nuxt.config.ts]
|
|
export default defineNuxtConfig({
|
|
modules: ['@nuxt/ui'],
|
|
ui: {
|
|
global: true
|
|
}
|
|
})
|
|
```
|
|
|
|
## Continuous Releases
|
|
|
|
Nuxt UI uses [pkg.pr.new](https://github.com/stackblitz-labs/pkg.pr.new) for continuous preview releases, providing developers with instant access to the latest features and bug fixes without waiting for official releases.
|
|
|
|
Preview releases are automatically generated for every commit to the `dev` branch and pull requests targeting the `dev` branch. To use it into your project, replace the version in your `package.json` with the commit hash or pull request number.
|
|
|
|
```diff [package.json]
|
|
{
|
|
"dependencies": {
|
|
- "@nuxt/ui": "^2.21.0",
|
|
+ "@nuxt/ui": "https://pkg.pr.new/@nuxt/ui@bf1c9e7",
|
|
}
|
|
}
|
|
```
|
|
|
|
::note
|
|
**pkg.pr.new** will automatically comment on PRs with the installation URL, making it easy to test changes.
|
|
::
|