Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/shuding/nextra/llms.txt

Use this file to discover all available pages before exploring further.

Nextra is 100% compatible with the built-in CSS support of Next.js, including plain .css, CSS Modules (.module.css), and Sass files (.scss, .sass, .module.scss, .module.sass). You can add a global stylesheet, override theme variables, and integrate Sass with no extra configuration beyond the Nextra setup.

​
Adding a Global CSS File

To apply custom styles across your entire Nextra site, create a CSS file and import it in your root layout.
1
Create your stylesheet
2
Create a CSS file anywhere in your project — a common convention is app/globals.css:
3
body {
  font-family:
    'SF Pro Text', 'SF Pro Icons', 'Helvetica Neue', 'Helvetica', 'Arial',
    sans-serif;
  padding: 20px 20px 60px;
  max-width: 680px;
  margin: 0 auto;
}
4
Import in your root layout
5
Import the CSS file at the top of your app/layout.tsx (or app/layout.jsx). Next.js will bundle and inject it on every page:
6
import './globals.css'

export default async function RootLayout({
  children
}: {
  children: React.ReactNode
}) {
  // ... Your layout logic here
  return (
    <html>
      <body>{children}</body>
    </html>
  )
}
Global CSS files must be imported from a layout or page file inside the app/ directory. Importing global CSS from a component that is not a layout or page is not supported by Next.js.

​
Overriding nextra-theme-docs CSS Variables

nextra-theme-docs is built with Tailwind CSS v4 and exposes its design tokens as CSS custom properties (variables). You can override these in your global CSS to customize colors, fonts, spacing, and more without modifying any theme source code.
app/globals.css
@import 'nextra-theme-docs/style.css';

:root {
  /* Primary accent color (used for links, active nav items, etc.) */
  --nextra-primary-hue: 212deg;
  --nextra-primary-saturation: 80%;

  /* Content width */
  --nextra-content-width: 900px;
}

.dark {
  /* Dark mode overrides */
  --nextra-primary-hue: 200deg;
}
Open your browser’s DevTools and inspect elements to discover all available CSS variables exported by nextra-theme-docs. They follow the --nextra-* naming convention.

​
Cascade Layers

nextra-theme-docs uses CSS @layer declarations internally, which means its styles participate in the CSS cascade layer order. Understanding this helps you write overrides that always win without needing high specificity or !important.

​
How layers work

Styles inside a @layer always have lower precedence than styles outside any layer, regardless of specificity. This means a simple un-layered rule in your CSS will override a theme rule — even a highly specific one — as long as yours is not also inside a lower-priority layer.
app/globals.css
@import 'nextra-theme-docs/style.css';

/* This wins over any nextra-theme-docs @layer rule */
.nextra-nav-container {
  border-bottom: 2px solid var(--nextra-primary-hue);
}

​
Explicit layer ordering with postcss-import

When you need full control over the layer stack — for example, to integrate multiple third-party style libraries — use postcss-import to wrap imports in named layers:
1
Install postcss-import
2
npm
npm install postcss-import
pnpm
pnpm add postcss-import
yarn
yarn add postcss-import
3
Add postcss-import to your PostCSS config
4
export default {
  plugins: {
    'postcss-import': {}
    // add other PostCSS plugins here (e.g., autoprefixer, cssnano)
  }
}
5
Set up your cascade layers in CSS
6
Declare the layer order explicitly, then import each stylesheet into its named layer. Layers listed later in @layer have higher priority:
7
/* Layers listed here establish priority: my-overrides wins over nextra */
@layer nextra, base, my-overrides;

@import 'nextra-theme-docs/dist/style.css' layer(nextra);

@layer base {
  /* base styles here */
}

@layer my-overrides {
  /* These always win over nextra-theme-docs */
  :root {
    --nextra-primary-hue: 270deg;
  }
}
8
Import your CSS file in the root layout
9
import '../styles.css'

export default async function RootLayout({ children }) {
  // ...
}

​
Using Sass

Nextra supports Sass out of the box through Next.js. The only prerequisite is installing the sass package.
1
Install the sass package
2
npm
npm install sass
pnpm
pnpm add sass
yarn
yarn add sass
3
Rename your CSS file to .scss
4
Rename globals.css to globals.scss (or create a new .scss file). Sass is a superset of CSS, so existing CSS is valid SCSS:
5
$primary-font: 'SF Pro Text', 'Helvetica Neue', sans-serif;
$max-content-width: 680px;

body {
  font-family: $primary-font;
  max-width: $max-content-width;
  margin: 0 auto;

  &:has(.nextra-sidebar) {
    max-width: 100%;
  }
}
6
Update the import in your root layout
7
Update the import in app/layout.tsx to reference the .scss file:
8
import './globals.scss'

export default async function RootLayout({ children }) {
  // ...
}
Sass variables and mixins are scoped to their own compilation step and are separate from Tailwind’s CSS variable system. You can use both simultaneously.

​
CSS Isolation with style-prefixed.css

By default, nextra-theme-docs/style.css uses the standard Tailwind v4 layer names (@layer base, @layer utilities). If you need stronger CSS layer isolation — for example, to embed a Nextra-powered section inside a larger app that also uses Tailwind — use the style-prefixed.css variant, which renames those layers to v4-base and v4-utilities:
app/globals.css
/* Use prefixed layer names to avoid collisions with your own base/utilities layers */
@import 'nextra-theme-docs/style-prefixed.css';
With this import, the theme’s base and utilities layers carry unique names, preventing them from merging with layers of the same name defined elsewhere in your CSS.
Switching between style.css and style-prefixed.css changes the layer names used by the theme. If you have explicit @layer ordering that references base or utilities, update those references when switching to the prefixed variant.

​
Quick Reference

Next.js (and therefore Nextra) supports all of the following out of the box:
File typeUsage
.cssGlobal styles, imported from layouts/pages
.module.cssComponent-scoped CSS Modules
.scss / .sassSass/SCSS (requires sass package)
.module.scss / .module.sassSass CSS Modules
:root {
  --nextra-primary-hue: 212deg;
  --nextra-primary-saturation: 100%;
  --nextra-content-width: 90rem;
  --nextra-navbar-height: 4rem;
  --nextra-menu-height: 3.75rem;
  --nextra-banner-height: 2.5rem;
}

Build docs developers (and LLMs) love

Get started for freeTalk to us