Skip to content
Tutorials Center
My learning

Topics

Lesson 12 of 32 ยท Components and styling

Styling in Nuxt

Style a Nuxt app: global CSS in nuxt.config, scoped styles and CSS modules, Tailwind with the Vite plugin, fonts, and dark mode with the color mode module.

Nuxt does not invent a styling system. It uses Vue's single-file components and Vite, so everything you know about CSS works: a global stylesheet, <style scoped> in components, CSS modules, preprocessors and utility frameworks such as Tailwind. What Nuxt adds is the server: styles must be present in the HTML the server sends, so the page does not appear unstyled and then jump, and anything that depends on the visitor's preferences, like dark mode, needs a plan that works before JavaScript runs.

This lesson goes through each layer in the order you will probably need it. The real Nuxt code and configuration are read-only, because the sandbox has no Nuxt build. The two runnable stand-ins are plain JavaScript models: one shows how scoped styles and CSS modules rewrite your selectors, and one shows how a color mode module decides between light and dark. Each says what is real and what is the model.

Layers of styling

Global CSS Resets, variables, base typography.
Scoped CSS Styles that belong to one component.
CSS modules Class names that cannot collide.
Utilities Tailwind classes right in the markup.

Start global, scope the rest.

1 / 2

Global CSS

A global stylesheet holds what every page shares: a small reset, CSS variables for your colors and spacing, base typography. Put the file in assets/ and list it in the css option of the config:

TypeScript
// nuxt.config.ts (real Nuxt code, read-only)
export default defineNuxtConfig({
  css: ['~/assets/css/main.css'],
})
CSS
/* app/assets/css/main.css (read-only) */
:root {
  --color-bg: #ffffff;
  --color-text: #1f2328;
  --color-accent: #2563eb;
}

body {
  margin: 0;
  background: var(--color-bg);
  color: var(--color-text);
  font-family: system-ui, sans-serif;
}

Files in the css array are loaded on every page, in the order you list them. You can also import a stylesheet in app.vue or in a layout, which is useful for CSS that belongs to one layout only (see Nested routes and layouts). Use CSS variables for design tokens: they are cheap, they work with dark mode, and components can use them without any import.

Scoped styles

In a single-file component, <style scoped> limits the rules to that component:

VUE
<template>
  <article class="card">
    <h2>{{ title }}</h2>
    <slot />
  </article>
</template>

<style scoped>
.card {
  border: 1px solid #d0d7de;
  border-radius: 8px;
  padding: 1rem;
}
h2 {
  margin-top: 0;
}
</style>

Vue adds a unique attribute such as data-v-7ba5bd90 to every element the component renders and rewrites the selectors to require it. The h2 rule above cannot touch headings in other components. Two consequences are worth knowing:

  • A child component's root element gets the parent's scope attribute too, so a parent can style the root of a child, but not its inner elements.
  • To reach inside a child, use :deep(): .card :deep(.title) { ... }. Use it sparingly, because it ties the parent to the child's markup.

Scoped CSS has a small cost for very generic selectors, so prefer classes over bare element selectors in big components. The plain Vue version of this topic is in Scoped CSS and Styling strategies.

CSS modules

<style module> goes further: class names are turned into unique generated names, and you read them from $style:

VUE
<template>
  <p :class="$style.warning">Disk almost full</p>
</template>

<style module>
.warning {
  color: #b42318;
  font-weight: 600;
}
</style>

In <script setup>, get the same object with useCssModule(). The generated names make collisions impossible, which suits component libraries and teams that prefer explicit class objects.

The stand-in below models both mechanisms. Real parts: the idea that scoped CSS adds an attribute to selectors (before pseudo-classes, and :deep() moves the attribute earlier) and that modules map your class names to unique ones. Model parts: the tiny parser and the hash function, which differ from what Vue and Vite do, and the exact generated names, which will look different in a real build.

JS How scoped CSS and CSS modules rewrite names

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Tailwind CSS

Tailwind is the most common utility framework in the Nuxt world. For Tailwind 4, the documented path is the Vite plugin: install tailwindcss and @tailwindcss/vite, register the plugin, and import Tailwind from your global stylesheet.

TypeScript
// nuxt.config.ts (real Nuxt code, read-only)
import tailwindcss from '@tailwindcss/vite'

export default defineNuxtConfig({
  css: ['~/assets/css/main.css'],
  vite: {
    plugins: [tailwindcss()],
  },
})
CSS
/* app/assets/css/main.css (read-only) */
@import "tailwindcss";
VUE
<template>
  <button class="rounded-lg bg-blue-600 px-4 py-2 font-semibold text-white hover:bg-blue-700">
    Buy now
  </button>
</template>

There is also a community Nuxt module, @nuxtjs/tailwindcss, that wraps the setup and adds config-file support. Versions and options change, so follow the current setup guide of whichever you pick. A practical tip: when a long class list repeats, extract a component (BaseButton.vue), not a CSS abstraction, so the style lives in one place (see Components and composables in Nuxt).

Fonts

Fonts are a frequent cause of slow, jumpy pages. The @nuxt/fonts module looks at the font-family names in your CSS, finds them in providers such as Google Fonts, downloads and serves them from your own domain, and generates fallback metrics so the swap from the fallback font to the real one shifts the layout less.

TypeScript
// nuxt.config.ts (real Nuxt code, read-only)
export default defineNuxtConfig({
  modules: ['@nuxt/fonts'],
})
CSS
body {
  font-family: 'Inter', system-ui, sans-serif;
}

Keep the number of font families and weights small; every extra file is a request. Self-hosting also avoids sending your visitors' addresses to a third-party font server, which matters for privacy rules in some countries. More loading advice is in Performance and Core Web Vitals.

Dark mode with the color mode module

Dark mode has a trap on a server-rendered site. The server cannot know the visitor's system preference, so it renders one version, and JavaScript fixes it later. The visitor sees a white flash before the dark theme appears. The @nuxtjs/color-mode module avoids this by injecting a tiny script into the head that sets a class on <html> before the first paint.

TypeScript
// nuxt.config.ts (real Nuxt code, read-only)
export default defineNuxtConfig({
  modules: ['@nuxtjs/color-mode'],
  colorMode: { classSuffix: '' }, // class names "dark" and "light", the Tailwind convention
})
VUE
<script setup lang="ts">
const colorMode = useColorMode()
</script>

<template>
  <select v-model="colorMode.preference">
    <option value="system">System</option>
    <option value="light">Light</option>
    <option value="dark">Dark</option>
  </select>
  <p>Resolved: {{ colorMode.value }}</p>
</template>

The module distinguishes two values. colorMode.preference is what the visitor chose: system, light or dark. colorMode.value is what is actually applied, after resolving system against the operating system's setting. Your CSS then reacts to the class, for example with variables:

CSS
:root { --color-bg: #ffffff; --color-text: #1f2328; }
:root.dark { --color-bg: #0d1117; --color-text: #e6edf3; }

By default the module's class has a suffix (dark-mode); set classSuffix: '' if your CSS or Tailwind expects plain dark. The module stores the preference in localStorage, so it persists across visits. The stand-in models the resolve step and the head script's job:

JS Resolving system, light and dark

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Where do you register a global stylesheet in Nuxt?

    Files listed in the css option are included on every page, in the order given.
  2. 2. What does <style scoped> do to a selector like .card h2?

    Vue adds a data-v attribute to the component's elements and appends the attribute to the selector.
  3. 3. How does a CSS module differ from scoped CSS?

    Scoped CSS adds an attribute to selectors. A CSS module renames the classes and gives you a map of the new names.
  4. 4. A site flashes white before it turns dark for dark-mode visitors. What does @nuxtjs/color-mode do about it?

    The script runs before painting, so the right class is present when the page first appears.
  5. 5. What is the difference between colorMode.preference and colorMode.value?

    When the preference is 'system', the value follows the operating system setting.

Summary

  • Register shared CSS in the css option of nuxt.config.ts; use CSS variables for design tokens.
  • <style scoped> adds a data attribute to selectors so rules stay inside the component; use :deep() sparingly; <style module> generates unique class names.
  • Tailwind 4 plugs in through the @tailwindcss/vite plugin and an @import "tailwindcss" line; extract components rather than long repeated class lists.
  • @nuxt/fonts self-hosts fonts and reduces layout shift; @nuxtjs/color-mode prevents the dark-mode flash with a head script and separates preference from value.

Next: Server routes and the Nitro engine