arthur/ui
1
0
Fork 0
mirror of https://github.com/ArthurDanjou/ui.git synced 2026-01-14 12:14:41 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs: update

Browse Source
This commit is contained in:
Benjamin Canac
2024-07-01 19:35:59 +02:00
parent c8e353e599
commit ca029a4b6c
7 changed files with 141 additions and 374 deletions
Download Patch File Download Diff File Expand all files Collapse all files

224
docs/content/1.getting-started/2.installation.md
View File

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

54
docs/content/1.getting-started/3.typescript.md Normal file
View File

@@ -0,0 +1,54 @@
---
title: 'TypeScript'
description: ''
---
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.
::

119
docs/content/1.getting-started/4.colors.md
View File

@@ -4,8 +4,6 @@ description: 'Learn how to customize the look and feel of the components.'
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
### Configuration
Components are based on a `primary` and a `gray` color. You can change them in your `app.config.ts`.
@@ -65,120 +63,3 @@ 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.
## Components
### `app.config.ts`
You can find the config of each component in the [`ui.config/`](https://github.com/nuxt/ui/tree/dev/src/runtime/ui.config) directory. You can override those classes in your own `app.config.ts`.
```ts [app.config.ts]
export default defineAppConfig({
ui: {
container: {
constrained: 'max-w-5xl'
}
}
})
```
Thanks to [tailwind-merge](https://github.com/dcastil/tailwind-merge), the `app.config.ts` is smartly merged with the default config. This means you don't have to rewrite everything.
You can change this behavior by setting `strategy` to `override` in your `app.config.ts`:
```ts [app.config.ts]
export default defineAppConfig({
ui: {
strategy: 'override',
button: {
color: {
white: {
solid: 'bg-white dark:bg-gray-900'
}
}
}
}
})
```
### `ui` prop
Each component has a `ui` prop that allows you to customize everything specifically.
```vue
<template>
<UContainer :ui="{ constrained: 'max-w-2xl' }">
<slot />
</UContainer>
</template>
```
::callout{icon="i-heroicons-light-bulb"}
You can find the default classes for each component under the `Config` section.
::
Thanks to [tailwind-merge](https://github.com/dcastil/tailwind-merge), the `ui` prop is smartly merged with the config. This means you don't have to rewrite everything.
For example, the default preset of the `FormGroup` component looks like this:
```json
{
"label": {
"base": "block font-medium text-gray-700 dark:text-gray-200"
}
}
```
To change the font of the `label`, you only need to write:
```vue
<UFormGroup name="email" label="Email" :ui="{ label: { base: 'font-semibold' } }" />
```
This will smartly replace the `font-medium` by `font-semibold` and prevent any class duplication and any class priority issue.
You can change this behavior by setting `strategy` to `override` inside the `ui` prop:
```vue
<UButton
to="https://github.com/nuxt/ui"
:ui="{
strategy: 'override',
color: {
white: {
solid: 'bg-white dark:bg-gray-900'
}
}
}"
/>
```
### `class` attribute
You can also use the `class` attribute to add classes to the component.
```vue
<template>
<UButton label="Button" class="rounded-full" />
</template>
```
Again, with [tailwind-merge](https://github.com/dcastil/tailwind-merge), this will smartly merge the classes with the `ui` prop and the config.
### Default values
Some component props like `size`, `color`, `variant`, etc. have a default value that you can override in your `app.config.ts`.
```ts [app.config.ts]
export default defineAppConfig({
ui: {
button: {
default: {
size: 'md',
color: 'gray',
variant: 'ghost'
}
}
}
})
```

4
docs/content/1.getting-started/3.icons.md → docs/content/1.getting-started/5.icons.md
View File

@@ -137,3 +137,7 @@ export default defineAppConfig({
}
})
```
## Theme
:component-theme

58
docs/content/1.getting-started/6.dark-mode.md
View File

@@ -1,58 +0,0 @@
---
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>
```
::

56
docs/content/1.getting-started/5.theming.md → docs/content/1.getting-started/6.theme.md
View File

@@ -182,3 +182,59 @@ 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>
```
::

0
docs/content/1.getting-started/8.contributing.md → docs/content/1.getting-started/contributing.md
View File