Banner

Add a dismissible banner at the top of your documentation site to display important announcements, release notes, or notifications.

Use banners to display important announcements, updates, or notifications across your entire documentation site. Banners appear at the top of every page, support Markdown formatting, and you can make them dismissible. By default, banners use the color defined by the colors.dark property in your docs.json. You can change the appearance with the type property or override the background entirely with color.

To add a banner, use the banner property in your docs.json:

"banner": {
  "content": "🚀 Version 2.0 is now live! See our [changelog](/changelog) for details.",
  "dismissible": true
}

You can also configure banners per language by setting banner in navigation.languages. See Language-specific banners.

Properties

contentstringrequired

The text content displayed in the banner. Supports basic MDX formatting including links, bold, and italic text. Custom components are not supported.

dismissibleboolean

Whether users can dismiss the banner. When true, a close button appears. If a user closes the banner, it stays hidden for them until you update the banner content. Defaults to false.

typestring

The visual style of the banner. Controls the background color so visitors can quickly recognize the urgency of the message. Defaults to info.

info: Uses the primary brand color. Best for product announcements and general updates.
warning: Uses an amber background. Best for cautionary notices like scheduled maintenance or upcoming deprecations.
critical: Uses a red background. Best for urgent notices that require immediate attention, such as outages or required actions.

colorobject

Override the banner background color with a custom hex value. When set, this takes precedence over the color implied by type. Banner text is white, so choose a background dark enough to remain legible.

Show color properties

lightstring

Hex color used in light mode. If only dark is provided, it’s used in light mode as well.

darkstring

Hex color used in dark mode. If only light is provided, it’s used in dark mode as well.

Language-specific banners

Configure different banner content for each language in your documentation. Define language-specific banners in the navigation.languages array in your docs.json.

{
  "navigation": {
    "languages": [
      {
        "language": "en",
        "banner": {
          "content": "🚀 Version 2.0 is now live! See our [changelog](/en/changelog) for details.",
          "dismissible": true
        },
        "groups": [
          {
            "group": "Getting started",
            "pages": ["en/overview", "en/quickstart"]
          }
        ]
      },
      {
        "language": "es",
        "banner": {
          "content": "🚀 ¡La versión 2.0 ya está disponible! Consulta nuestro [registro de cambios](/es/changelog) para más detalles.",
          "dismissible": true
        },
        "groups": [
          {
            "group": "Getting started",
            "pages": ["es/overview", "es/quickstart"]
          }
        ]
      }
    ]
  },
  "banner": {
    "content": "🚀 Version 2.0 is now live!",
    "dismissible": true
  }
}

Fallback behavior

Banners follow a priority order when determining which content to display:

Language-specific banner: If the current language has a banner configuration, it takes priority.
Global banner: If no language-specific banner exists, display the global banner.

Properties

Language-specific banners

Fallback behavior

On this page