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.

The Banner component renders a fixed, dismissible announcement strip at the top of the page. It is ideal for announcing new releases, upcoming maintenance, or any time-sensitive notice you want every visitor to see. Once a user dismisses the banner, the decision is stored in localStorage under a configurable key — changing that key causes the banner to reappear for all visitors, making it easy to manage multiple sequential announcements.

​
Import

import { Banner } from 'nextra/components'

​
Props

PropTypeDefaultDescription
storageKeystring'nextra-banner'The localStorage key used to remember whether the banner has been dismissed. Change this value whenever you update the banner content so that it reappears for returning visitors.
dismissiblebooleantrueWhen true, a close (×) button is rendered. Set to false to make the banner permanent.
childrenReactNode—The content rendered inside the banner. Supports links and inline markup.
classNamestring—Additional CSS class names applied to the inner content wrapper.

​
Usage

​
Basic Banner

import { Banner } from 'nextra/components'

<Banner storageKey="v4-release">
  🎉 Nextra 4.0 is released! Read the{' '}
  <a href="/blog/v4">release notes</a>.
</Banner>

​
Non-Dismissible Banner

Set dismissible={false} to hide the close button and keep the banner visible at all times — useful for mandatory notices such as a site-wide outage or a required migration warning. 
import { Banner } from 'nextra/components'

<Banner storageKey="maintenance" dismissible={false}>
  ⚠️ Scheduled maintenance on Saturday 14:00–16:00 UTC.
</Banner>

​
Using Banner in a Layout

The most common usage is to pass the Banner as a prop to the docs theme Layout component inside your root app/layout.tsx. This ensures it appears on every page of the site without having to add it to individual MDX files. 
import { Layout } from 'nextra-theme-docs'
import { Banner } from 'nextra/components'

const banner = (
  <Banner storageKey="v4-release">
    Nextra 4.0 is released 🎉
  </Banner>
)

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <Layout banner={banner} ...>
          {children}
        </Layout>
      </body>
    </html>
  )
}

​
Updating Banner Content

Every time you change the text of your banner, update storageKey to a new descriptive value. Visitors who dismissed the previous banner will see the new one because the old dismissed state is stored under a different key. 
// Before — old announcement
<Banner storageKey="v3-release">
  Nextra 3.0 is out 🚀
</Banner>

// After — new announcement (changing storageKey causes banner to reappear)
<Banner storageKey="v4-release">
  Nextra 4.0 is out — bigger and faster 🚀
</Banner>

​
How Dismissal Works

When the user clicks the close button, the component writes the storageKey value to localStorage. On subsequent page loads, an inline <script> (injected before hydration) reads localStorage and immediately toggles the x:hidden class on the banner element, preventing any flash of the banner before React hydrates.
Because the dismiss state lives in localStorage, it is browser-specific and not shared across devices. Clearing browser data or using a different browser will cause the banner to reappear.

​
CSS Custom Property

The Banner component automatically sets the --nextra-banner-height CSS custom property on the <html> element via a ResizeObserver. The docs theme uses this value to offset the sticky header so it doesn’t overlap the banner. If you are building a custom theme or layout, you can read this property to position fixed elements correctly: 
.my-header {
  top: var(--nextra-banner-height, 0px);
}

Build docs developers (and LLMs) love

Get started for freeTalk to us