Theming

As Nuxt UI Pro is built on top of Nuxt UI, you should check out the Nuxt UI Theming page first. This is where you'll learn how to choose the 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.

You can achieve the same thing using the app.config.ts in the ui object:

export default defineAppConfig({
  ui: {
    landing: {
      grid: {
        wrapper: 'lg:grid-cols-10'
      }
    }
  }
})

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, ContentToc, 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',
      system: 'i-heroicons-computer-desktop-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',
      menu: 'i-heroicons-bars-3-20-solid',
      close: 'i-heroicons-x-mark-20-solid',
      check: 'i-heroicons-check-circle-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 ContentSearch components for example. Other icons like the ui.header.button shown above need to be overridden specifically.