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(getting-started): update

Browse Source
This commit is contained in:
Benjamin Canac
2024-09-17 16:36:14 +02:00
parent 1f5372baba
commit df72003516
7 changed files with 237 additions and 80 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -91,7 +91,7 @@ export default defineNuxtConfig({
})
```
::note{to="/getting-started/colors#color-variant"}
::note{to="/getting-started/colors#build-colors"}
This can help reduce the number of CSS classes generated in your bundle.
::

8
docs/content/1.getting-started/3.theme.md
View File

@@ -33,12 +33,12 @@ Tailwind CSS v4 takes a CSS-first configuration approach, you now customize your
The `@theme` directive tells Tailwind to make new utilities and variants available based on those variables. It's the equivalent of the `theme.extend` key in Tailwind CSS v3 `tailwind.config.ts` file.
This is exactly what the [`@nuxt/ui`](https://github.com/nuxt/ui/blob/v3/src/runtime/index.css) import is all about, it declares the `primary`, `error` and `gray` colors to be configurable through the [App Config](https://nuxt.com/docs/guide/directory-structure/app-config#app-config-file) but we'll talk more about that in the [Colors](/getting-started/colors) section.
::note
You can learn more about this on https://tailwindcss.com/blog/tailwindcss-v4-alpha#css-first-configuration.
You can learn more about this on [https://tailwindcss.com/blog/tailwindcss-v4-alpha](https://tailwindcss.com/blog/tailwindcss-v4-alpha#css-first-configuration).
::
This is exactly what the [`@import "@nuxt/ui";`](https://github.com/nuxt/ui/blob/v3/src/runtime/index.css) is all about, it extends the default Tailwind CSS theme and declares the `primary`, `error` and `gray` colors to be configurable through the [App Config](https://nuxt.com/docs/guide/directory-structure/app-config#app-config-file) but we'll talk more about that in the [Colors](/getting-started/colors) section.
## Tailwind Variants API
Nuxt UI components are styled using the [Tailwind Variants](https://www.tailwind-variants.org/) API, which provides a powerful way to create variants and manage component styles. Let's explore the key features of this API:
@@ -213,7 +213,7 @@ In this example, the `leadingIcon` slot is overwritten even though the `md` size
### `class` prop
The `class` prop allows you to override the classes of the `root` slot or the `base` slot when the component has no slots.
The `class` prop allows you to override the classes of the `root` or `base` slot. This has priority over the `app.config.ts` configuration and `variants` resolution.
::component-code{slug="button"}
---

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

@@ -1,13 +1,10 @@
---
description: 'Learn how to customize the look and feel of the components.'
navigation:
badge:
label: Todo
description: 'Learn how to customize colors and optimize your color palette for Nuxt UI components.'
---
## Color variant
## Build colors
In the previous section, we explored how components have themes that can include `variants`, which are reflected in their props. One common variant is `color`. Let's examine this using the [Button](/components/button) component as an example:
Nuxt UI components provide dynamic `color` variants. By default, these variants classes are generated based on the default Tailwind CSS colors. Let's take the [Button](/components/button) component as an example:
::component-code{slug="button"}
---
@@ -18,28 +15,11 @@ slots:
---
::
These `color` variants are generated based on the default Tailwind CSS colors, you can change this by using the [`colors`](/getting-started/installation#colors) option in your `nuxt.config.ts` to select only the colors you're actually using.
You can change these colors with the [`colors`](/getting-started/installation#colors) option in your `nuxt.config.ts` to select only the colors you're actually using.
For example, you've added a custom `cerise` color and only use the default `blue` and `green` colors in your application.
For example, if you added a custom `cerise` color and only use the default `blue` and `green` colors in your application, you can configure the `colors` option like this:
```css [main.css]
@import "tailwindcss";
@import "@nuxt/ui";
@theme {
--color-cerise-50: #fef2f4;
--color-cerise-100: #fde6e9;
--color-cerise-200: #fbd0d9;
--color-cerise-300: #f7aab9;
--color-cerise-400: #f27a93;
--color-cerise-500: #e63f66;
--color-cerise-600: #d42a5b;
--color-cerise-700: #b21e4b;
--color-cerise-800: #951c45;
--color-cerise-900: #801b40;
--color-cerise-950: #470a1f;
}
```
::code-group
```ts [nuxt.config.ts]
export default defineNuxtConfig({
@@ -50,7 +30,31 @@ export default defineNuxtConfig({
})
```
This configuration will ensure that only classes for those three colors are generated in your final CSS bundle and that the `color` prop will be typed and provide autocompletion in your editor with those three colors.
```css [main.css]
@import "tailwindcss";
@import "@nuxt/ui";
@theme {
--color-cerise-50: #FEF2F4;
--color-cerise-100: #FDE6E9;
--color-cerise-200: #FBD0D9;
--color-cerise-300: #F7AAB9;
--color-cerise-400: #F27A93;
--color-cerise-500: #E63F66;
--color-cerise-600: #D42A5B;
--color-cerise-700: #B21E4B;
--color-cerise-800: #951C45;
--color-cerise-900: #801B40;
--color-cerise-950: #470A1F;
}
```
::
::caution
Make sure to use color ranges from `50` to `950`. You can use tools like [UI Colors](https://uicolors.app/) to generate your palette.
::
This configuration will ensure that only classes for those three colors are generated in your final CSS bundle. When you use the `color` prop, it will be typed and provide autocompletion in your editor with those three colors.
```vue
<template>
@@ -58,30 +62,100 @@ This configuration will ensure that only classes for those three colors are gene
</template>
```
::caution
Make sure to use color ranges from `50` to `950` when you define your colors. You can use tools like [UI Colors](https://uicolors.app/) to generate your palette.
::
## Runtime colors
Nuxt UI generates CSS variables for color management. Among these, you'll find `primary` and `gray` color aliases, which are specifically introduced by Nuxt UI to simplify component styling and provide a consistent color scheme across your application.
### Default aliases
You can configure those aliases in your `app.config.ts` file under the `ui.colors` key:
Nuxt UI introduces three key color aliases used to style components:
- The `gray` alias can be any of the default Tailwind CSS colors: `slate`, `cool` (renamed from `gray`), `zinc`, `neutral` or `stone`. Defaults to `cool`.
- The `primary` alias can be any of the other colors including your custom ones. Defaults to `green`.
1. `primary`{color="primary"}: Main brand color. Default: `green`{color="green"}.
2. `error`{color="error"}: For error states. Default: `red`{color="red"}.
3. `gray`: Neutral color for backgrounds, text, etc. Default: `cool`.
::warning{to="https://tailwindcss.com/docs/customizing-colors#default-color-palette" target="_blank"}
The Tailwind CSS `gray` color is renamed to `cool` in Nuxt UI to avoid conflicts with the `gray` alias.
::
You can configure these aliases in your `app.config.ts` file under the `ui.colors` key:
```ts [app.config.ts]
export default defineAppConfig({
ui: {
colors: {
primary: 'cerise',
primary: 'blue',
error: 'red',
gray: 'zinc'
}
}
})
```
This powerful feature leverages Nuxt [App Config](https://nuxt.com/docs/guide/directory-structure/app-config#app-config-file), enabling dynamic styling of all components at runtime. It allows for real-time theme customization without requiring an application rebuild.
::tip
The aliases colors can be removed from the `colors` option in your `nuxt.config.ts` if you don't use them specifically. For example if `primary`'s target is `cerise` you don't have to select `cerise`, this will reduce the bundle even more.
We recommend using these colors in your application whenever possible with classes like `text-primary-500 dark:text-primary-400`, `border-gray-200 dark:border-gray-800` or `bg-white dark:bg-gray-900` for example.
::
::important
These alias colors don't need to be explicitly listed in the `colors` option of your `nuxt.config.ts`. Also, if you've set `primary` to a custom color (e.g., `cerise`), you don't need to list `cerise` in the `colors` array.
::
::note
You can try this out by clicking on the :prose-icon{name="i-heroicons-swatch-20-solid" class="text-primary-500 dark:text-primary-400"} button in the header of this documentation.
::
### Custom aliases
You can also add your own color aliases to be configurable at runtime in your `app.config.ts` file:
1. Define the alias color by using CSS variables to let Tailwind know about it:
```css [main.css]
@import "tailwindcss";
@import "@nuxt/ui";
@theme {
--color-secondary-50: var(--color-secondary-50);
--color-secondary-100: var(--color-secondary-100);
--color-secondary-200: var(--color-secondary-200);
--color-secondary-300: var(--color-secondary-300);
--color-secondary-400: var(--color-secondary-400);
--color-secondary-500: var(--color-secondary-500);
--color-secondary-600: var(--color-secondary-600);
--color-secondary-700: var(--color-secondary-700);
--color-secondary-800: var(--color-secondary-800);
--color-secondary-900: var(--color-secondary-900);
--color-secondary-950: var(--color-secondary-950);
}
```
2. Set a default value for the color alias in your `app.config.ts` file:
```ts [app.config.ts]
export default defineAppConfig({
ui: {
colors: {
secondary: 'indigo'
}
}
})
```
3. Add this color to the `colors` option of your `nuxt.config.ts` file to generate classes:
```ts [nuxt.config.ts]
export default defineNuxtConfig({
modules: ['@nuxt/ui'],
ui: {
colors: ['secondary']
}
})
```
4. You can use the `secondary` color alias in your application and use classes like `text-secondary-500 dark:text-secondary-400`:
```vue
<template>
<UButton color="secondary">Button</UButton>
</template>
```

102
docs/content/1.getting-started/5.icons.md
View File

@@ -1,38 +1,54 @@
---
description: ''
description: 'Nuxt UI integrates seamlessly with `@nuxt/icon`, providing access to over 200,000+ icons from [Iconify](https://iconify.design/).'
links:
- label: 'nuxt/icon'
to: https://github.com/nuxt/icon
target: _blank
icon: i-simple-icons-github
navigation:
badge:
label: Todo
---
Thanks to [`@nuxt/icon`](https://github.com/nuxt/icon), add 200,000+ ready to use icons to your Nuxt application based on [Iconify](https://iconify.design).
## Usage
You can use any name from the https://icones.js.org collection such as the `i-` prefix (for example, `i-heroicons-cog`) with:
Nuxt UI automatically registers the `@nuxt/icon` module for you, so there's no additional setup required.
- any `icon` prop available across the components:
::note
You can use any name from the https://icones.js.org collection.
::
```vue
<template>
<UButton icon="i-heroicons-magnifying-glass" />
</template>
```
### Icon Component
- the `UIcon` component to use icons anywhere:
You can use the [Icon](/components/icon) component with a `name` prop to display an icon:
```vue
<template>
<UIcon name="i-heroicons-moon" class="w-5 h-5 text-primary-500" />
</template>
```
::component-code{slug="icon"}
---
props:
name: 'i-heroicons-light-bulb'
class: 'size-5'
---
::
### Collections
### Component Props
It's highly recommended to install the icons collections locally with:
Some components also have an `icon` prop to display an icon, like the [Button](/components/button) for example:
::component-code{slug="button"}
---
ignore:
- color
- variant
props:
icon: i-heroicons-sun
variant: subtle
slots:
default: Button
---
::
## Collections
### Iconify Dataset
It's highly recommended to install the icon data locally with:
::code-group
@@ -52,10 +68,52 @@ npm install @iconify-json/{collection_name}
For example, to use the `i-uil-github` icon, install it's collection with `@iconify-json/uil`. This way the icons can be served locally or from your serverless functions, which is faster and more reliable on both SSR and client-side.
::callout{icon="i-heroicons-light-bulb" to="https://github.com/nuxt/icon?tab=readme-ov-file#custom-local-collections" target="_blank"}
Read more about custom collections in the `@nuxt/icon` documentation.
::tip{to="https://github.com/nuxt/icon?tab=readme-ov-file#iconify-dataset" target="_blank"}
Read more about this in the `@nuxt/icon` documentation.
::
### Custom Local Collections
You can use local SVG files to create a custom Iconify collection.
For example, place your icons' SVG files under a folder of your choice, for example, `./assets/icons`:
```bash
assets/icons
├── add.svg
└── remove.svg
```
In your `nuxt.config.ts`, add an item in `icon.customCollections`:
```ts
export default defineNuxtConfig({
modules: [
'@nuxt/ui'
],
icon: {
customCollections: [{
prefix: 'custom',
dir: './assets/icons'
}]
}
})
```
Then you can use the icons like this:
```vue
<template>
<UIcon name="i-custom-add" />
</template>
```
::tip{to="https://github.com/nuxt/icon?tab=readme-ov-file#custom-local-collections" target="_blank"}
Read more about this in the `@nuxt/icon` documentation.
::
## Theme
You can change the default icons used by Nuxt UI components in your `app.config.ts`:
:icons-theme

39
docs/content/1.getting-started/6.fonts.md
View File

@@ -1,13 +1,42 @@
---
description: ''
description: 'Nuxt UI integrates seamlessly with `@nuxt/fonts`, providing plug-and-play font optimization for your Nuxt applications.'
links:
- label: 'nuxt/fonts'
to: https://github.com/nuxt/fonts
target: _blank
icon: i-simple-icons-github
navigation:
badge:
label: Todo
---
Thanks to [`@nuxt/fonts`](https://github.com/nuxt/fonts),
## Usage
Nuxt UI automatically registers the `@nuxt/fonts` module for you, so there's no additional setup required. To use a font in your Nuxt UI application, you can simply declare it in your CSS:
::code-group
```vue [app.vue]
<style>
@import "tailwindcss";
@import "@nuxt/ui";
@theme {
--font-family-sans: Inter, sans-serif;
}
</style>
```
```css [main.css]
@import "tailwindcss";
@import "@nuxt/ui";
@theme {
--font-family-sans: Inter, sans-serif;
}
```
::
That's it! Nuxt Fonts will detect this and you should immediately see the web font loaded in your browser.
::tip{to="https://fonts.nuxt.com/advanced" target="_blank"}
Read more about how `@nuxt/fonts` work behind the scenes to optimize your fonts.
::

12
docs/content/1.getting-started/7.color-mode.md
View File

@@ -1,20 +1,16 @@
---
description: ''
description: 'Nuxt UI integrates seamlessly with `@nuxtjs/color-mode`, offering effortless switching between light and dark themes.'
links:
- label: 'nuxtjs/color-mode'
to: https://github.com/nuxt-modules/color-mode
target: _blank
icon: i-simple-icons-github
navigation:
badge:
label: Todo
navigation: false
---
Thanks to [`@nuxtjs/color-mode`](https://github.com/nuxt-modules/color-mode), you can easily switch between light and dark themes.
## Usage
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.
Nuxt UI automatically registers the `@nuxtjs/color-mode` module for you and takes advantage of [Tailwind CSS dark mode](https://tailwindcss.com/docs/dark-mode#toggling-dark-mode-manually) class strategy, so there's no additional setup required.
You can disable dark mode by setting the `preference` to `light` instead of `system` in your `nuxt.config.ts`.

6
docs/content/3.components/icon.md
View File

@@ -8,16 +8,16 @@ links:
## Usage
You can use any name from the https://icones.js.org collection such as the `i-` prefix:
You can use any name from the https://icones.js.org collection:
::component-code
---
props:
name: 'i-heroicons-light-bulb'
class: 'w-5 h-5'
class: 'size-5'
---
::
::caution
It's highly recommended to install the icons collections you need, read more about this in [Icons](/getting-started/icons).
It's highly recommended to install the icons collections you need, read more about this in [Icons](/getting-started/icons#collections).
::