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 or follow this guide to build your app from scratch.

Configuration

You can customize components the same way as Nuxt UI, through the App Config and ui prop. As Nuxt UI Pro is built on top of Nuxt UI, you should check out the Theming documentation first. This is where you'll learn how to choose the primary and gray colors or the icons collections to use for example.

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:

app.config.ts
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:

app.config.ts
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:

app.config.ts
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 needs to be overridden specifically.

Take a look at nuxt.com app.config.ts to see how to override all the icons.

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 creating the structure of our app, then we'll see how to build a Nuxt app with a simple landing page. We'll also see how to build a documentation with @nuxt/content module in the Content section.

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.

nuxt.config.ts
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']
  }
})
You can use any icon (100,000+) from Iconify, learn more in the Theming documentation.

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.

app.config.ts
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 object. 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.

You can use any color from Tailwind CSS, learn more in the Theming documentation.

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.

tailwind.config.ts
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 UHeader, UMain and UFooter components to build the layout of our app.

app.vue
<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',
  children: [{
    label: 'Features',
    to: '/pro#features',
    exactHash: true,
    icon: 'i-heroicons-beaker',
    description: 'Discover all the features of Nuxt UI Pro.'
  }, {
    label: 'Pricing',
    to: '/pro#pricing',
    exactHash: true,
    icon: 'i-heroicons-credit-card',
    description: 'A simple pricing, for solo developers or teams.'
  }, {
    label: 'Guide',
    to: '/pro/guide',
    icon: 'i-heroicons-book-open',
    description: 'Learn how to use Nuxt UI Pro in your app.'
  }, {
    label: 'Components',
    to: '/pro/components',
    icon: 'i-heroicons-cube-transparent',
    description: 'Discover all the components available in Nuxt UI 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>
    <NuxtPage />
  </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 all the props and slots available to customize your app. You can find the documentation of each component in the Components section.

pages/index.vue

pages/index.vue
<template>
  <ULandingHero>
    <template #title>
      The Intuitive<br><span class="text-primary block lg:inline-block">Vue Framework</span>
    </template>

    <template #description>
      Nuxt is an <NuxtLink to="https://github.com/nuxt/nuxt" target="_blank">
        open source framework
      </NuxtLink> that makes web development intuitive and powerful.<br>Create performant and production-grade full-stack web apps and websites with confidence.
    </template>

    <template #links>
      <UButton to="/docs/getting-started/installation" icon="i-ph-rocket-launch-duotone" size="xl">
        Get Started
      </UButton>
      <UButton size="xl" color="white" icon="i-ph-video-duotone">
        What is Nuxt?
      </UButton>
    </template>
  </ULandingHero>
</template>
You'll find a complete example in the Landing template.

Let's continue in the Content section as it's easier to demonstrate with @nuxt/content rather than hard-coding the content in our app.

Setup

Learn how to install Nuxt UI Pro in your Nuxt application.

Content

Learn how to build your app with @nuxt/content module.