mirror of
https://github.com/ArthurDanjou/ui.git
synced 2026-01-14 20:19:34 +01:00
docs: update
This commit is contained in:
Benjamin Canac
@@ -34,211 +34,41 @@ 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. |
|
||||
You can customize Nuxt UI by providing options in your `nuxt.config`:
|
||||
|
||||
Configure options in your `nuxt.config.ts` as such:
|
||||
### `prefix`
|
||||
|
||||
()
|
||||
|
||||
```ts [nuxt.config.ts]
|
||||
export default defineNuxtConfig({
|
||||
modules: ['@nuxt/ui'],
|
||||
ui: {
|
||||
global: true
|
||||
prefix: 'Nuxt'
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
### `colors`
|
||||
|
||||
```ts [nuxt.config.ts]
|
||||
export default defineNuxtConfig({
|
||||
modules: ['@nuxt/ui'],
|
||||
ui: {
|
||||
colors: ['primary', 'green', 'red']
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
### `transitions`
|
||||
|
||||
```ts [nuxt.config.ts]
|
||||
export default defineNuxtConfig({
|
||||
modules: ['@nuxt/ui'],
|
||||
ui: {
|
||||
transitions: false
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user