mirror of
https://github.com/ArthurDanjou/ui.git
synced 2026-01-22 07:50:36 +01:00
docs: improve
This commit is contained in:
Benjamin Canac
@@ -1,29 +0,0 @@
|
||||
---
|
||||
title: Introduction
|
||||
description: 'Fully styled and customizable components for Nuxt.'
|
||||
---
|
||||
|
||||
Nuxt UI is a module that provides a set of Vue components and composables built with [Tailwind CSS](https://tailwindcss.com/) and [Headless UI](https://headlessui.dev/) to help you build beautiful and accessible user interfaces.
|
||||
|
||||
Its goal is to provide everything related to UI when building a Nuxt app. This includes components, icons, colors, dark mode as well as keyboard shortcuts.
|
||||
|
||||
## Features
|
||||
|
||||
- Built with [Headless UI](https://headlessui.dev/) and [Tailwind CSS](https://tailwindcss.com/)
|
||||
- HMR support through Nuxt App Config
|
||||
- Dark mode support
|
||||
- Support for LTR and RTL languages
|
||||
- Keyboard shortcuts
|
||||
- Bundled icons
|
||||
- Fully typed
|
||||
- [Figma Kit](https://www.figma.com/community/file/1288455405058138934)
|
||||
|
||||
## Credits
|
||||
|
||||
- [nuxt/nuxt](https://github.com/nuxt/nuxt)
|
||||
- [nuxt-modules/color-mode](https://github.com/nuxt-modules/color-mode)
|
||||
- [nuxt-modules/tailwindcss](https://github.com/nuxt-modules/tailwindcss)
|
||||
- [tailwindlabs/tailwindcss](https://github.com/tailwindlabs/tailwindcss)
|
||||
- [tailwindlabs/headlessui](https://github.com/tailwindlabs/headlessui)
|
||||
- [vueuse/vueuse](https://github.com/vueuse/vueuse)
|
||||
- [egoist/tailwindcss-icons](https://github.com/egoist/tailwindcss-icons)
|
||||
@@ -66,42 +66,6 @@ We'd advise you to use those colors in your components and pages, e.g. `text-pri
|
||||
|
||||
The `primary` color also has a `DEFAULT` shade that changes based on the theme. It is `500` in light mode and `400` in dark mode. You can use as a shortcut in your components and pages, e.g. `text-primary`, `bg-primary`, `focus-visible:ring-primary`, etc.
|
||||
|
||||
### Smart Safelisting
|
||||
|
||||
Components having a `color` prop like [Avatar](/components/avatar#chip), [Badge](/components/badge#style), [Button](/components/button#style), [Input](/components/input#style) (inherited in [Select](/components/select) and [SelectMenu](/components/select-menu)), [RadioGroup](/components/radio-group), [Checkbox](/components/checkbox), [Toggle](/components/toggle), [Range](/components/range) and [Notification](/components/notification#timeout) will use the `primary` color by default but will handle all the colors defined in your `tailwind.config.ts` or the default Tailwind CSS colors.
|
||||
|
||||
Variant classes of those components are defined with a syntax like `bg-{color}-500 dark:bg-{color}-400` so they can be used with any color. However, this means that Tailwind will not find those classes and therefore will not generate the corresponding CSS.
|
||||
|
||||
The module uses the [Tailwind CSS safelist](https://tailwindcss.com/docs/content-configuration#safelisting-classes) feature to force the generation of all the classes for the `primary` color **only** as it is the default color for all the components.
|
||||
|
||||
Then, the module will automatically detect when you use one of those components with a color and will safelist it for you. This means that if you use a `red` color for a Button component, the `red` color classes will be safelisted for the Button component only. This will allow to keep the CSS bundle size as small as possible.
|
||||
|
||||
There is one case where you would want to force the safelisting of a color. For example, if you've set the default color of the Button component to `orange` in your `app.config.ts`.
|
||||
|
||||
```ts [app.config.ts]
|
||||
export default defineAppConfig({
|
||||
ui: {
|
||||
button: {
|
||||
default: {
|
||||
color: 'orange'
|
||||
}
|
||||
}
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
This will apply the orange color when using a default `<UButton />`. You'll need to safelist this color manually in your `nuxt.config.ts` ui options as we won't be able to detect it automatically. You can do so through the `safelistColors` option which defaults to `['primary']`.
|
||||
|
||||
```ts [nuxt.config.ts]
|
||||
export default defineNuxtConfig({
|
||||
ui: {
|
||||
safelistColors: ['orange']
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
This can also happen when you bind a dynamic color to a component: `<UBadge :color="color" />`, `<UAvatar :chip-color="statuses[user.status]" />`, etc. In this case, you'll need to safelist the possible color values manually as well.
|
||||
|
||||
## Components
|
||||
|
||||
### `app.config.ts`
|
||||
@@ -218,253 +182,3 @@ export default defineAppConfig({
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
## Dark mode
|
||||
|
||||
All the components are styled with dark mode in mind.
|
||||
|
||||
Thanks to [Tailwind CSS dark mode](https://tailwindcss.com/docs/dark-mode#toggling-dark-mode-manually) class strategy and the [@nuxtjs/color-mode](https://github.com/nuxt-modules/color-mode) module, you literally have nothing to do.
|
||||
|
||||
You can disable dark mode by setting the `preference` to `light` instead of `system` in your `nuxt.config.ts`.
|
||||
|
||||
```ts [nuxt.config.ts]
|
||||
export default defineNuxtConfig({
|
||||
colorMode: {
|
||||
preference: 'light'
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
::callout{icon="i-heroicons-light-bulb"}
|
||||
If you're stuck in dark mode even after changing this setting, you might need to remove the `nuxt-color-mode` entry from your browser's local storage.
|
||||
::
|
||||
|
||||
You can easily build a color mode button by using the `useColorMode` composable from `@nuxtjs/color-mode`.
|
||||
|
||||
::component-example
|
||||
#default
|
||||
:color-mode-button
|
||||
|
||||
#code
|
||||
```vue
|
||||
<script setup lang="ts">
|
||||
const colorMode = useColorMode()
|
||||
const isDark = computed({
|
||||
get () {
|
||||
return colorMode.value === 'dark'
|
||||
},
|
||||
set () {
|
||||
colorMode.preference = colorMode.value === 'dark' ? 'light' : 'dark'
|
||||
}
|
||||
})
|
||||
</script>
|
||||
<template>
|
||||
<ClientOnly>
|
||||
<UButton
|
||||
:icon="isDark ? 'i-heroicons-moon-20-solid' : 'i-heroicons-sun-20-solid'"
|
||||
color="gray"
|
||||
variant="ghost"
|
||||
aria-label="Theme"
|
||||
@click="isDark = !isDark"
|
||||
/>
|
||||
<template #fallback>
|
||||
<div class="w-8 h-8" />
|
||||
</template>
|
||||
</ClientOnly>
|
||||
</template>
|
||||
```
|
||||
::
|
||||
|
||||
## Icons
|
||||
|
||||
You can use any icon (100,000+) from [Iconify](https://iconify.design/).
|
||||
|
||||
Some components have an `icon` prop that allows you to add an icon to the component.
|
||||
|
||||
```vue
|
||||
<template>
|
||||
<UButton icon="i-heroicons-magnifying-glass" />
|
||||
</template>
|
||||
```
|
||||
|
||||
You can also use the [Icon](/components/icon) component to add an icon anywhere in your app by following this pattern: `i-{collection_name}-{icon_name}`.
|
||||
|
||||
```vue
|
||||
<template>
|
||||
<UIcon name="i-heroicons-moon" />
|
||||
</template>
|
||||
```
|
||||
|
||||
### Collections
|
||||
|
||||
By default, the module uses [Heroicons](https://heroicons.com/) but you can change it from the module options in your `nuxt.config.ts`.
|
||||
|
||||
```ts [nuxt.config.ts]
|
||||
export default defineNuxtConfig({
|
||||
ui: {
|
||||
icons: ['mdi', 'simple-icons']
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
::callout{icon="i-heroicons-light-bulb"}
|
||||
Search the icon you want to use on https://icones.js.org built by [@antfu](https://github.com/antfu).
|
||||
::
|
||||
|
||||
Thanks to [@egoist/tailwindcss-icons](https://github.com/egoist/tailwindcss-icons) plugin, only the icons you use in your app will be bundled in your CSS. However, you need to install the icon collections you specified in the `ui.icons` key:
|
||||
|
||||
::code-group
|
||||
|
||||
```bash [pnpm]
|
||||
pnpm i @iconify-json/{collection_name}
|
||||
```
|
||||
|
||||
```bash [yarn]
|
||||
yarn add @iconify-json/{collection_name}
|
||||
```
|
||||
|
||||
```bash [npm]
|
||||
npm install @iconify-json/{collection_name}
|
||||
```
|
||||
|
||||
::
|
||||
|
||||
If you choose to use the full `@iconify/json` icon collection (50MB), you can specifiy `icons: 'all'` or `icons: {}` in your `nuxt.config.ts` to use any icon in your app.
|
||||
|
||||
```ts [nuxt.config.ts]
|
||||
export default defineNuxtConfig({
|
||||
ui: {
|
||||
icons: {}
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
### Custom config
|
||||
|
||||
If you have specific needs, like using a custom icon collection, you can use the `icons` option in your `nuxt.config.ts` as an object to override the config of the [@egoist/tailwindcss-icons](https://github.com/egoist/tailwindcss-icons#plugin-options) plugin.
|
||||
|
||||
```ts [nuxt.config.ts]
|
||||
import { getIconCollections } from '@egoist/tailwindcss-icons'
|
||||
|
||||
export default defineNuxtConfig({
|
||||
ui: {
|
||||
icons: {
|
||||
// might solve stretch bug on generate, see https://github.com/egoist/tailwindcss-icons/issues/23
|
||||
extraProperties: {
|
||||
'mask-size': 'contain',
|
||||
'mask-position': 'center'
|
||||
},
|
||||
collections: {
|
||||
foo: {
|
||||
icons: {
|
||||
'arrow-left': {
|
||||
// svg body
|
||||
body: '<path fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" d="M10.5 19.5L3 12m0 0l7.5-7.5M3 12h18" />',
|
||||
// svg width and height, optional
|
||||
width: 24,
|
||||
height: 24
|
||||
}
|
||||
}
|
||||
},
|
||||
...getIconCollections(['heroicons', 'simple-icons'])
|
||||
}
|
||||
}
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
### Dynamic icons
|
||||
|
||||
The `Icon` component also has a `dynamic` prop to use the [nuxt-icon](https://github.com/nuxt-modules/icon/) module instead of the [@egoist/tailwindcss-icons](https://github.com/egoist/tailwindcss-icons#plugin-options) plugin.
|
||||
|
||||
Read more about this in the [Icon](/components/icon#dynamic) component page.
|
||||
|
||||
### Defaults
|
||||
|
||||
You can easily replace all the default icons of the components in your `app.config.ts`.
|
||||
|
||||
```ts [app.config.ts]
|
||||
export default defineAppConfig({
|
||||
ui: {
|
||||
button: {
|
||||
default: {
|
||||
loadingIcon: 'i-octicon-sync-24'
|
||||
}
|
||||
},
|
||||
input: {
|
||||
default: {
|
||||
loadingIcon: 'i-octicon-sync-24'
|
||||
}
|
||||
},
|
||||
select: {
|
||||
default: {
|
||||
loadingIcon: 'i-octicon-sync-24',
|
||||
trailingIcon: 'i-octicon-chevron-down-24'
|
||||
}
|
||||
},
|
||||
selectMenu: {
|
||||
default: {
|
||||
selectedIcon: 'i-octicon-check-24'
|
||||
}
|
||||
},
|
||||
notification: {
|
||||
default: {
|
||||
closeButton: {
|
||||
icon: 'i-octicon-x-24'
|
||||
}
|
||||
}
|
||||
},
|
||||
commandPalette: {
|
||||
default: {
|
||||
icon: 'i-octicon-search-24',
|
||||
loadingIcon: 'i-octicon-sync-24',
|
||||
selectedIcon: 'i-octicon-check-24',
|
||||
emptyState: {
|
||||
icon: 'i-octicon-search-24'
|
||||
}
|
||||
}
|
||||
},
|
||||
table: {
|
||||
default: {
|
||||
sortAscIcon: 'i-octicon-sort-asc-24',
|
||||
sortDescIcon: 'i-octicon-sort-desc-24',
|
||||
sortButton: {
|
||||
icon: 'i-octicon-arrow-switch-24'
|
||||
},
|
||||
loadingState: {
|
||||
icon: 'i-octicon-sync-24'
|
||||
},
|
||||
emptyState: {
|
||||
icon: 'i-octicon-database-24'
|
||||
}
|
||||
}
|
||||
},
|
||||
pagination: {
|
||||
default: {
|
||||
firstButton: {
|
||||
icon: 'i-octicon-chevron-left-24'
|
||||
},
|
||||
prevButton: {
|
||||
icon: 'i-octicon-arrow-left-24'
|
||||
},
|
||||
nextButton: {
|
||||
icon: 'i-octicon-arrow-right-24'
|
||||
},
|
||||
lastButton: {
|
||||
icon: 'i-octicon-chevron-right-24'
|
||||
}
|
||||
}
|
||||
},
|
||||
accordion: {
|
||||
default: {
|
||||
openIcon: 'i-octicon-chevron-down-24'
|
||||
}
|
||||
},
|
||||
breadcrumb: {
|
||||
default: {
|
||||
divider: 'i-octicon-chevron-right-24'
|
||||
}
|
||||
}
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
195
docs/app/content/1.getting-started/4.icons.md
Normal file
195
docs/app/content/1.getting-started/4.icons.md
Normal file
@@ -0,0 +1,195 @@
|
||||
---
|
||||
description: ''
|
||||
---
|
||||
|
||||
You can use any icon (100,000+) from [Iconify](https://iconify.design/).
|
||||
|
||||
Some components have an `icon` prop that allows you to add an icon to the component.
|
||||
|
||||
```vue
|
||||
<template>
|
||||
<UButton icon="i-heroicons-magnifying-glass" />
|
||||
</template>
|
||||
```
|
||||
|
||||
You can also use the [Icon](/components/icon) component to add an icon anywhere in your app by following this pattern: `i-{collection_name}-{icon_name}`.
|
||||
|
||||
```vue
|
||||
<template>
|
||||
<UIcon name="i-heroicons-moon" />
|
||||
</template>
|
||||
```
|
||||
|
||||
### Collections
|
||||
|
||||
By default, the module uses [Heroicons](https://heroicons.com/) but you can change it from the module options in your `nuxt.config.ts`.
|
||||
|
||||
```ts [nuxt.config.ts]
|
||||
export default defineNuxtConfig({
|
||||
ui: {
|
||||
icons: ['mdi', 'simple-icons']
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
::callout{icon="i-heroicons-light-bulb"}
|
||||
Search the icon you want to use on https://icones.js.org built by [@antfu](https://github.com/antfu).
|
||||
::
|
||||
|
||||
Thanks to [@egoist/tailwindcss-icons](https://github.com/egoist/tailwindcss-icons) plugin, only the icons you use in your app will be bundled in your CSS. However, you need to install the icon collections you specified in the `ui.icons` key:
|
||||
|
||||
::code-group
|
||||
|
||||
```bash [pnpm]
|
||||
pnpm i @iconify-json/{collection_name}
|
||||
```
|
||||
|
||||
```bash [yarn]
|
||||
yarn add @iconify-json/{collection_name}
|
||||
```
|
||||
|
||||
```bash [npm]
|
||||
npm install @iconify-json/{collection_name}
|
||||
```
|
||||
|
||||
::
|
||||
|
||||
If you choose to use the full `@iconify/json` icon collection (50MB), you can specifiy `icons: 'all'` or `icons: {}` in your `nuxt.config.ts` to use any icon in your app.
|
||||
|
||||
```ts [nuxt.config.ts]
|
||||
export default defineNuxtConfig({
|
||||
ui: {
|
||||
icons: {}
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
### Custom config
|
||||
|
||||
If you have specific needs, like using a custom icon collection, you can use the `icons` option in your `nuxt.config.ts` as an object to override the config of the [@egoist/tailwindcss-icons](https://github.com/egoist/tailwindcss-icons#plugin-options) plugin.
|
||||
|
||||
```ts [nuxt.config.ts]
|
||||
import { getIconCollections } from '@egoist/tailwindcss-icons'
|
||||
|
||||
export default defineNuxtConfig({
|
||||
ui: {
|
||||
icons: {
|
||||
// might solve stretch bug on generate, see https://github.com/egoist/tailwindcss-icons/issues/23
|
||||
extraProperties: {
|
||||
'mask-size': 'contain',
|
||||
'mask-position': 'center'
|
||||
},
|
||||
collections: {
|
||||
foo: {
|
||||
icons: {
|
||||
'arrow-left': {
|
||||
// svg body
|
||||
body: '<path fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" d="M10.5 19.5L3 12m0 0l7.5-7.5M3 12h18" />',
|
||||
// svg width and height, optional
|
||||
width: 24,
|
||||
height: 24
|
||||
}
|
||||
}
|
||||
},
|
||||
...getIconCollections(['heroicons', 'simple-icons'])
|
||||
}
|
||||
}
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
### Dynamic icons
|
||||
|
||||
The `Icon` component also has a `dynamic` prop to use the [nuxt-icon](https://github.com/nuxt-modules/icon/) module instead of the [@egoist/tailwindcss-icons](https://github.com/egoist/tailwindcss-icons#plugin-options) plugin.
|
||||
|
||||
Read more about this in the [Icon](/components/icon#dynamic) component page.
|
||||
|
||||
### Defaults
|
||||
|
||||
You can easily replace all the default icons of the components in your `app.config.ts`.
|
||||
|
||||
```ts [app.config.ts]
|
||||
export default defineAppConfig({
|
||||
ui: {
|
||||
button: {
|
||||
default: {
|
||||
loadingIcon: 'i-octicon-sync-24'
|
||||
}
|
||||
},
|
||||
input: {
|
||||
default: {
|
||||
loadingIcon: 'i-octicon-sync-24'
|
||||
}
|
||||
},
|
||||
select: {
|
||||
default: {
|
||||
loadingIcon: 'i-octicon-sync-24',
|
||||
trailingIcon: 'i-octicon-chevron-down-24'
|
||||
}
|
||||
},
|
||||
selectMenu: {
|
||||
default: {
|
||||
selectedIcon: 'i-octicon-check-24'
|
||||
}
|
||||
},
|
||||
notification: {
|
||||
default: {
|
||||
closeButton: {
|
||||
icon: 'i-octicon-x-24'
|
||||
}
|
||||
}
|
||||
},
|
||||
commandPalette: {
|
||||
default: {
|
||||
icon: 'i-octicon-search-24',
|
||||
loadingIcon: 'i-octicon-sync-24',
|
||||
selectedIcon: 'i-octicon-check-24',
|
||||
emptyState: {
|
||||
icon: 'i-octicon-search-24'
|
||||
}
|
||||
}
|
||||
},
|
||||
table: {
|
||||
default: {
|
||||
sortAscIcon: 'i-octicon-sort-asc-24',
|
||||
sortDescIcon: 'i-octicon-sort-desc-24',
|
||||
sortButton: {
|
||||
icon: 'i-octicon-arrow-switch-24'
|
||||
},
|
||||
loadingState: {
|
||||
icon: 'i-octicon-sync-24'
|
||||
},
|
||||
emptyState: {
|
||||
icon: 'i-octicon-database-24'
|
||||
}
|
||||
}
|
||||
},
|
||||
pagination: {
|
||||
default: {
|
||||
firstButton: {
|
||||
icon: 'i-octicon-chevron-left-24'
|
||||
},
|
||||
prevButton: {
|
||||
icon: 'i-octicon-arrow-left-24'
|
||||
},
|
||||
nextButton: {
|
||||
icon: 'i-octicon-arrow-right-24'
|
||||
},
|
||||
lastButton: {
|
||||
icon: 'i-octicon-chevron-right-24'
|
||||
}
|
||||
}
|
||||
},
|
||||
accordion: {
|
||||
default: {
|
||||
openIcon: 'i-octicon-chevron-down-24'
|
||||
}
|
||||
},
|
||||
breadcrumb: {
|
||||
default: {
|
||||
divider: 'i-octicon-chevron-right-24'
|
||||
}
|
||||
}
|
||||
}
|
||||
})
|
||||
```
|
||||
58
docs/app/content/1.getting-started/5.dark-mode.md
Normal file
58
docs/app/content/1.getting-started/5.dark-mode.md
Normal file
@@ -0,0 +1,58 @@
|
||||
---
|
||||
title: 'Dark mode'
|
||||
description: ''
|
||||
---
|
||||
|
||||
All the components are styled with dark mode in mind.
|
||||
|
||||
Thanks to [Tailwind CSS dark mode](https://tailwindcss.com/docs/dark-mode#toggling-dark-mode-manually) class strategy and the [@nuxtjs/color-mode](https://github.com/nuxt-modules/color-mode) module, you literally have nothing to do.
|
||||
|
||||
You can disable dark mode by setting the `preference` to `light` instead of `system` in your `nuxt.config.ts`.
|
||||
|
||||
```ts [nuxt.config.ts]
|
||||
export default defineNuxtConfig({
|
||||
colorMode: {
|
||||
preference: 'light'
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
::callout{icon="i-heroicons-light-bulb"}
|
||||
If you're stuck in dark mode even after changing this setting, you might need to remove the `nuxt-color-mode` entry from your browser's local storage.
|
||||
::
|
||||
|
||||
You can easily build a color mode button by using the `useColorMode` composable from `@nuxtjs/color-mode`.
|
||||
|
||||
::component-example
|
||||
#default
|
||||
:color-mode-button
|
||||
|
||||
#code
|
||||
```vue
|
||||
<script setup lang="ts">
|
||||
const colorMode = useColorMode()
|
||||
const isDark = computed({
|
||||
get () {
|
||||
return colorMode.value === 'dark'
|
||||
},
|
||||
set () {
|
||||
colorMode.preference = colorMode.value === 'dark' ? 'light' : 'dark'
|
||||
}
|
||||
})
|
||||
</script>
|
||||
<template>
|
||||
<ClientOnly>
|
||||
<UButton
|
||||
:icon="isDark ? 'i-heroicons-moon-20-solid' : 'i-heroicons-sun-20-solid'"
|
||||
color="gray"
|
||||
variant="ghost"
|
||||
aria-label="Theme"
|
||||
@click="isDark = !isDark"
|
||||
/>
|
||||
<template #fallback>
|
||||
<div class="w-8 h-8" />
|
||||
</template>
|
||||
</ClientOnly>
|
||||
</template>
|
||||
```
|
||||
::
|
||||
Reference in New Issue
Block a user