ProGuide
Usage
Learn how to build your Nuxt app from scratch with Nuxt UI Pro.
Introduction
Nuxt UI Pro is thought to be flexible so you can build anything you want with it. It provides a set of components, composables and utils to build your app, but it will not inject any pages or layouts.
Therefore, we recommend to start with one of the templates (coming soon) or follow this guide to build your app from scratch.
primary and gray colors or the icons collections to use for example.Components
Like in Nuxt UI, every component is prefixed with a U to avoid conflicts with other components. For example, the Header component is named UHeader.
You can customize components the same way as @nuxt/ui, through the App Config or ui prop, both of which are smartly merged thanks to tailwind-merge. In the same way, when using the class prop on any component, it will also automatically be merged with the wrapper.
For example, if you use the LandingGrid component which has this config:
const config = {
wrapper: 'flex flex-col lg:grid gap-8 lg:grid-cols-12 relative'
}
If you use a class as such: <ULandingGrid class="lg:grid-cols-10" />
, it will be merged with the wrapper class and the grid will have 10 columns instead of 12.
On top of that, Nuxt UI Pro provides some additional customization options that you can use in your app.config.ts.
Variables
A new variables key is available in the ui object to override some variables used in Nuxt UI Pro. By default, the following variables are used:
export default defineAppConfig({
ui: {
variables: {
light: {
background: '255 255 255',
foreground: 'var(--color-gray-700)'
},
dark: {
background: 'var(--color-gray-900)',
foreground: 'var(--color-gray-200)'
},
header: {
height: '4rem'
}
}
}
})
The background and foreground variables are transformed into colors and used in some components. They are also automatically applied to the body element so you don't have to:
body {
@apply antialiased font-sans text-foreground bg-background;
}
The header.height variable is used to set the height of the Header component. Some other components like Aside, Main, DocsToc, etc. also use it to position themselves accordingly.
Icons
A new icons key is available in the ui object to override some icons used in Nuxt UI Pro. By default, the following icons are used:
export default defineAppConfig({
ui: {
icons: {
dark: 'i-heroicons-moon-20-solid',
light: 'i-heroicons-sun-20-solid',
search: 'i-heroicons-magnifying-glass-20-solid',
external: 'i-heroicons-arrow-up-right-20-solid',
chevron: 'i-heroicons-chevron-down-20-solid',
hash: 'i-heroicons-hashtag-20-solid'
}
}
})
Those are only shortcuts, you can still override them specifically:
export default defineAppConfig({
ui: {
header: {
links: {
trailingIcon: {
name: 'i-ph-caret-down' // Defaults to `ui.icons.chevron`
}
},
button: {
icon: {
open: 'i-ph-list',
close: 'i-ph-x'
}
}
}
}
})
Note that those shortcuts are used for icons that are repeated across components, like the dark and light icons used in ColorModeButton, ColorModeToggle and DocsSearch components for example. Other icons like the ui.header.button shown above need to be overridden specifically.
Structure
We'll only provide examples for the most common use cases, but keep in mind that you can do whatever you want. Let's start by configuring our app, then we'll see how to build a Nuxt app with a simple landing page and then how to integrate with the @nuxt/content module.
nuxt.config.ts
If you've followed the installation guide, you should already have a nuxt.config.ts file with the @nuxt/ui-pro layer and the @nuxt/ui module registered. We'll also configure @nuxt/ui module with some icons collections and take advantage of @nuxtjs/google-fonts and @nuxtjs/fontaine to choose our font.
export default defineNuxtConfig({
extends: ['@nuxt/ui-pro'],
modules: [
'@nuxtjs/fontaine',
'@nuxtjs/google-fonts',
'@nuxt/ui'
],
ui: {
icons: ['ph', 'simple-icons']
},
colorMode: {
preference: 'dark'
},
googleFonts: {
display: 'swap',
download: true,
families: {
'DM+Sans': [400, 500, 600, 700]
}
},
fontMetrics: {
fonts: ['DM Sans']
}
})
app.config.ts
We'll now create an app.config.ts file to configure the primary and gray colors. We'll also change the header height, default background and override some icons.
export default defineAppConfig({
ui: {
primary: 'green',
gray: 'slate',
tooltip: {
background: '!bg-background'
},
variables: {
dark: {
background: 'var(--color-gray-950)'
},
header: {
height: '5rem'
}
},
icons: {
dark: 'i-ph-moon-duotone',
light: 'i-ph-sun-duotone',
search: 'i-ph-magnifying-glass-duotone',
external: 'i-ph-arrow-up-right',
chevron: 'i-ph-caret-down',
hash: 'i-ph-hash-duotone'
},
header: {
wrapper: 'lg:mb-0 lg:border-0',
popover: {
links: {
active: 'dark:bg-gray-950/50',
inactive: 'dark:hover:bg-gray-950/50'
}
}
}
}
})
Like in Nuxt UI, you'll configure components through the ui prop. The key to override a component will be its path, for example ui.landing.hero will override the LandingHero component. The only difference with Nuxt UI is that the config lives inside each component instead of a global ui.config.ts file.
tailwind.config.ts
Let's say we want to override the green color to use the one from Nuxt, we can create a tailwind.config.ts file to do so. Like any other app using Tailwind CSS, you can override any Tailwind config here. We'll also override the fontFamily to use DM Sans as our default font.
import type { Config } from 'tailwindcss'
import defaultTheme from 'tailwindcss/defaultTheme'
export default <Partial<Config>>{
theme: {
extend: {
fontFamily: {
sans: ['DM Sans', 'DM Sans fallback', ...defaultTheme.fontFamily.sans]
},
colors: {
green: {
50: '#EFFDF5',
100: '#D9FBE8',
200: '#B3F5D1',
300: '#75EDAE',
400: '#00DC82',
500: '#00C16A',
600: '#00A155',
700: '#007F45',
800: '#016538',
900: '#0A5331',
950: '#052e16'
}
}
}
}
}
app.vue
Let's add an app.vue file which will be the root component of our app. We can use the Header, Main and Footer components to build the layout of our app.
<script setup lang="ts">
const links = [{
label: 'Documentation',
icon: 'i-heroicons-book-open',
to: '/getting-started'
}, {
label: 'Playground',
icon: 'i-simple-icons-stackblitz',
to: '/playground'
}, {
label: 'Roadmap',
icon: 'i-heroicons-academic-cap',
to: '/roadmap'
}, {
label: 'Pro',
icon: 'i-heroicons-square-3-stack-3d',
to: '/pro'
}, {
label: 'Releases',
icon: 'i-heroicons-rocket-launch',
to: 'https://github.com/nuxt/ui/releases',
target: '_blank'
}]
</script>
<template>
<UHeader :links="links">
<template #logo>
<Logo class="w-auto h-6" />
</template>
<template #right>
<UColorModeButton />
<UButton icon="i-simple-icons-github" to="https://github.com/nuxt/nuxt" target="_blank" color="gray" variant="ghost" />
</template>
</UHeader>
<UMain>
<NuxtLayout>
<NuxtPage />
</NuxtLayout>
</UMain>
<UFooter>
<template #left>
<p class="text-gray-500 dark:text-gray-400 text-sm">
Copyright © 2016-{{ new Date().getFullYear() }} Nuxt - <NuxtLink class="hover:underline" to="https://github.com/nuxt/nuxt/blob/main/LICENSE" target="_blank">
MIT License
</NuxtLink>
</p>
</template>
<template #right>
<UButton to="https://x.com/nuxt_js" target="_blank" icon="i-simple-icons-x" color="gray" variant="ghost" />
<UButton to="https://discord.com/invite/ps2h6QT" target="_blank" icon="i-simple-icons-discord" color="gray" variant="ghost" />
<UButton to="https://github.com/nuxt/nuxt" target="_blank" icon="i-simple-icons-github" color="gray" variant="ghost" />
</template>
</UFooter>
<UNotifications />
</template>
This example is quite long but demonstrates some props and slots available to customize your app. You can find the documentation of each component in the Components section.
pages/index.vue
Now, we can create our first page. We'll use the LandingHero and LandingSection components to build a simple landing page.
<template>
<div>
<ULandingHero description="Nuxt UI Pro is a collection of premium components built on top of Nuxt UI to create beautiful & responsive Nuxt applications in minutes.">
<template #title>
The <span class="text-primary block lg:inline-block">Building Blocks</span> for Modern Web apps
</template>
</ULandingHero>
<ULandingSection title="The freedom to build anything" align="left" />
<ULandingSection title="The flexibility to control your data" align="right" />
</div>
</template>
This is a very simple example as it's way easier to demonstrate with @nuxt/content rather than hard-coding the content.
Nuxt UI Pro components can be used in various ways, we'll release some templates soon to help you get started. With each template, a new page in the guide will be added to explain how to build a documentation, a blog, a landing page, etc.