diff --git a/docs/content/1.getting-started/2.installation.md b/docs/content/1.getting-started/2.installation.md index db8c0394..5d2c192e 100644 --- a/docs/content/1.getting-started/2.installation.md +++ b/docs/content/1.getting-started/2.installation.md @@ -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. :: diff --git a/docs/content/1.getting-started/3.theme.md b/docs/content/1.getting-started/3.theme.md index 559e8b99..2d86eecd 100644 --- a/docs/content/1.getting-started/3.theme.md +++ b/docs/content/1.getting-started/3.theme.md @@ -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"} --- diff --git a/docs/content/1.getting-started/4.colors.md b/docs/content/1.getting-started/4.colors.md index 83bc5288..709a477f 100644 --- a/docs/content/1.getting-started/4.colors.md +++ b/docs/content/1.getting-started/4.colors.md @@ -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 ``` -::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 + +``` diff --git a/docs/content/1.getting-started/5.icons.md b/docs/content/1.getting-started/5.icons.md index f4d22a02..e8b0e95b 100644 --- a/docs/content/1.getting-started/5.icons.md +++ b/docs/content/1.getting-started/5.icons.md @@ -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 - -``` +### 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 - -``` +::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 + +``` + +::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 diff --git a/docs/content/1.getting-started/6.fonts.md b/docs/content/1.getting-started/6.fonts.md index d9db5af5..4f9ccc63 100644 --- a/docs/content/1.getting-started/6.fonts.md +++ b/docs/content/1.getting-started/6.fonts.md @@ -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] + +``` + +```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. +:: diff --git a/docs/content/1.getting-started/7.color-mode.md b/docs/content/1.getting-started/7.color-mode.md index 654d9aed..dcd91029 100644 --- a/docs/content/1.getting-started/7.color-mode.md +++ b/docs/content/1.getting-started/7.color-mode.md @@ -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`. diff --git a/docs/content/3.components/icon.md b/docs/content/3.components/icon.md index 8b27c61d..b0494500 100644 --- a/docs/content/3.components/icon.md +++ b/docs/content/3.components/icon.md @@ -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). ::