DocumentationGuideAdvancedCustomize the Cascade Layers

Customize the Cascade Layers

In some scenarios, you may need more control over the Nextra predefined CSS to avoid unintended overrides of styles within cascade layers. Below is an example of how nextra-theme-docs uses postcss-import to place predefined CSS into a specified cascade layer:

Install postcss-import

Install postcss-import and add it to postcss.config.js:

postcss.config.js
module.exports = {
  plugins: {
    'postcss-import': {}
    // ...
  }
}

Disable Automatic Import of the Nextra Official Theme CSS

Nextra by default automatically imports the official theme CSS. You can disable this behavior by setting autoImportThemeStyle: false in the Nextra configuration.

next.config.js
const withNextra = nextra({
  autoImportThemeStyle: false,
  theme: 'nextra-theme-docs'
  // ...
})

Set Up the Cascade Layers

In your CSS file (e.g. styles.css), import the nextra-docs-theme CSS and specify the layers:

styles.css
@layer nextra, my-base;
 
@import 'nextra-theme-docs/dist/style.css' layer(nextra);
 
@layer my-base {
  /* my base styles */
}

Import Your CSS File

Create a pages/_app.jsx file and import your CSS files there:

pages/_app.jsx
import '../path/to/your/styles.css'
 
export default function MyApp({ Component, pageProps }) {
  return <Component {...pageProps} />
}
PlaygroundBuilt-ins