mirror of
https://github.com/ArthurDanjou/ui.git
synced 2026-01-23 16:30:45 +01:00
docs: new structure (#1282)
Co-authored-by: Sébastien Chopin <seb@nuxt.com>
This commit is contained in:
Benjamin Canac
GitHub
@@ -3,11 +3,9 @@ title: Introduction
|
||||
description: 'Fully styled and customizable components for Nuxt.'
|
||||
---
|
||||
|
||||
This module has been developed by the [NuxtLabs](https://nuxtlabs.com/) team for [Volta](https://volta.net) and [Nuxt Studio](https://nuxt.studio/), its goal is to provide everything related to UI when building a Nuxt app. This includes components, icons, colors, dark mode but also keyboard shortcuts.
|
||||
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.
|
||||
|
||||
::callout{icon="i-heroicons-light-bulb"}
|
||||
[Volta](https://volta.net/) entire UI is built with this module alongside the 50+ keyboard shortcuts defined.
|
||||
::
|
||||
Its goal is to provide everything related to UI when building a Nuxt app. This includes components, icons, colors, dark mode but also keyboard shortcuts.
|
||||
|
||||
## Features
|
||||
|
||||
|
||||
@@ -1,8 +1,9 @@
|
||||
---
|
||||
description: 'Learn how to install and configure the module in your Nuxt app.'
|
||||
title: Installation
|
||||
description: 'Learn how to install and configure Nuxt UI in your application.'
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
## Setup
|
||||
|
||||
1. Install `@nuxt/ui` dependency to your project:
|
||||
|
||||
@@ -91,7 +92,7 @@ You can read more about this in the [Theming](/getting-started/theming#dark-mode
|
||||
This module is installed when using the `dynamic` prop on the `Icon` component or globally through the `ui.icons.dynamic` option in your `app.config.ts`.
|
||||
|
||||
::callout{icon="i-heroicons-light-bulb"}
|
||||
You can read more about this in the [Theming](/getting-started/theming#dynamic-icons) section and on the [Icon](/elements/icon) component page.
|
||||
You can read more about this in the [Theming](/getting-started/theming#dynamic-icons) section and on the [Icon](/components/icon) component page.
|
||||
::
|
||||
|
||||
## TypeScript
|
||||
|
||||
@@ -2,8 +2,6 @@
|
||||
description: 'Learn how to customize the look and feel of the components.'
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
This module relies on Nuxt [App Config](https://nuxt.com/docs/guide/directory-structure/app-config#app-config-file) file to customize the look and feel of the components at runtime with HMR (hot-module-replacement).
|
||||
|
||||
## Colors
|
||||
@@ -70,7 +68,7 @@ The `primary` color also has a `DEFAULT` shade that changes based on the theme.
|
||||
|
||||
### Smart Safelisting
|
||||
|
||||
Components having a `color` prop like [Avatar](/elements/avatar#chip), [Badge](/elements/badge#style), [Button](/elements/button#style), [Input](/forms/input#style) (inherited in [Select](/forms/select) and [SelectMenu](/forms/select-menu)), [RadioGroup](/forms/radio-group), [Checkbox](/forms/checkbox), [Toggle](/forms/toggle), [Range](/forms/range) and [Notification](/overlays/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.
|
||||
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.
|
||||
|
||||
@@ -227,10 +225,6 @@ 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.
|
||||
|
||||
::callout{icon="i-heroicons-puzzle-piece"}
|
||||
Learn how to build a color mode button in the [Examples](/getting-started/examples#color-mode-button) page.
|
||||
::
|
||||
|
||||
You can disable dark mode by setting the `preference` to `light` instead of `system` in your `nuxt.config.ts`.
|
||||
|
||||
```ts [nuxt.config.ts]
|
||||
@@ -245,6 +239,42 @@ export default defineNuxtConfig({
|
||||
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>
|
||||
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/).
|
||||
@@ -257,7 +287,7 @@ Some components have an `icon` prop that allows you to add an icon to the compon
|
||||
</template>
|
||||
```
|
||||
|
||||
You can also use the [Icon](/elements/icon) component to add an icon anywhere in your app by following this pattern: `i-{collection_name}-{icon_name}`.
|
||||
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>
|
||||
@@ -347,7 +377,7 @@ export default defineNuxtConfig({
|
||||
|
||||
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](/elements/icon#dynamic) component page.
|
||||
Read more about this in the [Icon](/components/icon#dynamic) component page.
|
||||
|
||||
### Defaults
|
||||
|
||||
|
||||
@@ -2,15 +2,13 @@
|
||||
description: 'Learn how to display and define keyboard shortcuts in your app.'
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Some components like [Dropdown](/elements/dropdown), [Command Palette](/navigation/command-palette) and [Tooltip](/overlays/tooltip) support the display of keyboard shortcuts.
|
||||
Some components like [Dropdown](/components/dropdown), [Command Palette](/components/command-palette) and [Tooltip](/components/tooltip) support the display of keyboard shortcuts.
|
||||
|
||||
```vue
|
||||
<UDropdown :items="[[{ label: 'Edit', shortcuts: ['E'] }]]" />
|
||||
```
|
||||
|
||||
Shortcuts are displayed and styled through the [Kbd](/elements/kbd) component.
|
||||
Shortcuts are displayed and styled through the [Kbd](/components/kbd) component.
|
||||
|
||||
```vue
|
||||
<template>
|
||||
|
||||
@@ -1,182 +0,0 @@
|
||||
---
|
||||
title: Examples
|
||||
description: Discover some real-life examples of components you can build.
|
||||
---
|
||||
|
||||
::callout{icon="i-heroicons-wrench-screwdriver"}
|
||||
If you have any ideas of examples you'd like to see, please comment on [this issue](https://github.com/nuxt/ui/issues/297).
|
||||
::
|
||||
|
||||
## Components
|
||||
|
||||
You can mix and match components to build your own UI.
|
||||
|
||||
### ColorModeButton
|
||||
|
||||
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>
|
||||
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>
|
||||
```
|
||||
::
|
||||
|
||||
### DatePicker
|
||||
|
||||
Here is an example of a date picker component built with [v-calendar](https://github.com/nathanreyes/v-calendar).
|
||||
|
||||
```vue [components/DatePicker.vue]
|
||||
<script setup lang="ts">
|
||||
import { DatePicker as VCalendarDatePicker } from 'v-calendar'
|
||||
import 'v-calendar/dist/style.css'
|
||||
|
||||
const props = defineProps({
|
||||
modelValue: {
|
||||
type: Date,
|
||||
default: null
|
||||
}
|
||||
})
|
||||
|
||||
const emit = defineEmits(['update:model-value', 'close'])
|
||||
|
||||
const colorMode = useColorMode()
|
||||
|
||||
const isDark = computed(() => colorMode.value === 'dark')
|
||||
|
||||
const date = computed({
|
||||
get: () => props.modelValue,
|
||||
set: (value) => {
|
||||
emit('update:model-value', value)
|
||||
emit('close')
|
||||
}
|
||||
})
|
||||
|
||||
const attrs = [{
|
||||
key: 'today',
|
||||
highlight: {
|
||||
color: 'blue',
|
||||
fillMode: 'outline',
|
||||
class: '!bg-gray-100 dark:!bg-gray-800'
|
||||
},
|
||||
dates: new Date()
|
||||
}]
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<VCalendarDatePicker
|
||||
v-model="date"
|
||||
transparent
|
||||
borderless
|
||||
:attributes="attrs"
|
||||
:is-dark="isDark"
|
||||
title-position="left"
|
||||
trim-weeks
|
||||
:first-day-of-week="2"
|
||||
/>
|
||||
</template>
|
||||
```
|
||||
|
||||
You can use it inside a [Popover](/overlays/popover) component to display it when clicking on a [Button](/elements/button).
|
||||
|
||||
:component-example{component="date-picker-example"}
|
||||
|
||||
### Table
|
||||
|
||||
Here is an example of a Table component with all its features implemented.
|
||||
|
||||
:component-example{component="table-example-advanced" hiddenCode :padding="false" }
|
||||
|
||||
::callout{icon="i-simple-icons-github" to="https://github.com/nuxt/ui/blob/dev/docs/components/content/examples/TableExampleAdvanced.vue" target="_blank"}
|
||||
Take a look at the component!
|
||||
::
|
||||
|
||||
## Theming
|
||||
|
||||
Our theming system provides a lot of flexibility to customize the components.
|
||||
|
||||
### CommandPalette
|
||||
|
||||
Here is some examples of what you can do with the [CommandPalette](/navigation/command-palette).
|
||||
|
||||
#### Algolia
|
||||
|
||||
::component-example
|
||||
---
|
||||
padding: false
|
||||
component: 'command-palette-example-theme-algolia'
|
||||
componentProps:
|
||||
class: 'max-h-[480px] rounded-md'
|
||||
hiddenCode: true
|
||||
---
|
||||
::
|
||||
|
||||
::callout{icon="i-simple-icons-github" to="https://github.com/nuxt/ui/blob/dev/docs/components/content/examples/CommandPaletteExampleThemeAlgolia.vue#L23" target="_blank"}
|
||||
Take a look at the component!
|
||||
::
|
||||
|
||||
#### Raycast
|
||||
|
||||
::component-example
|
||||
---
|
||||
padding: false
|
||||
component: 'command-palette-example-theme-raycast'
|
||||
componentProps:
|
||||
class: 'max-h-[480px] rounded-md'
|
||||
hiddenCode: true
|
||||
---
|
||||
::
|
||||
|
||||
::callout{icon="i-simple-icons-github" to="https://github.com/nuxt/ui/blob/dev/docs/components/content/examples/CommandPaletteExampleThemeRaycast.vue#L30" target="_blank"}
|
||||
Take a look at the component!
|
||||
::
|
||||
|
||||
### VerticalNavigation
|
||||
|
||||
:component-example{component="vertical-navigation-example-theme-tailwind"}
|
||||
|
||||
### Pagination
|
||||
|
||||
:component-example{component="pagination-example-theme-rounded"}
|
||||
|
||||
## RTL Support
|
||||
|
||||
Here are some examples of how components look like in RTL mode.
|
||||
|
||||
### Pagination
|
||||
|
||||
:component-example{component="pagination-example-r-t-l" hiddenCode}
|
||||
|
||||
::callout{icon="i-simple-icons-github" to="https://github.com/nuxt/ui/blob/dev/docs/components/content/examples/PaginationExampleRTL.vue" target="_blank"}
|
||||
Take a look at the component!
|
||||
::
|
||||
@@ -1,10 +1,9 @@
|
||||
---
|
||||
title: Contributing
|
||||
description: Learn how to contribute to Nuxt UI.
|
||||
navigation: false
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Nuxt UI thrives thanks to its fantastic community ❤️, which contributes by submitting issues, creating pull requests, and offering valuable feedback.
|
||||
|
||||
Before reporting a bug or reporting a feature, please make sure that you have read through our documentation and existing [issues](https://github.com/nuxt/ui/issues).
|
||||
|
||||
Reference in New Issue
Block a user