# Banner (/components/banner)

<!-- agent-signals: reading_time_min: 3 · est_tokens: 1396 · updated: 2026-07-30 -->
Related: [Accordions](/components/accordions.md), [Badge](/components/badge.md), [Callouts](/components/callouts.md), [Cards](/components/cards.md), [Code groups](/components/code-groups.md), [Color](/components/color.md)

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`:

<CodeGroup>
  <CodeBlockTabs defaultValue="Product announcements" groupId="critical-notices+custom-color+maintenance-notices+product-announcements">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="Product announcements">
        Product announcements
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="Maintenance notices">
        Maintenance notices
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="Critical notices">
        Critical notices
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="Custom color">
        Custom color
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="Product announcements">
      ```json wrap  
      "banner": {
        "content": "🚀 Version 2.0 is now live! See our [changelog](/changelog) for details.",
        "dismissible": true
      }
      ```
    </CodeBlockTab>

    <CodeBlockTab value="Maintenance notices">
      ```json wrap  
      "banner": {
        "content": "⚠️ Scheduled maintenance: API will be unavailable December 15, 2-4 AM UTC",
        "type": "warning",
        "dismissible": false
      }
      ```
    </CodeBlockTab>

    <CodeBlockTab value="Critical notices">
      ```json wrap  
      "banner": {
        "content": "**Action required:** Rotate your API keys before January 1. [Migration guide](/migration)",
        "type": "critical",
        "dismissible": true
      }
      ```
    </CodeBlockTab>

    <CodeBlockTab value="Custom color">
      ```json wrap  
      "banner": {
        "content": "🎉 Join us at our annual conference!",
        "color": {
          "light": "#7C3AED",
          "dark": "#5B21B6"
        },
        "dismissible": true
      }
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

<Note>
  You can also configure banners per language by setting `banner` in `navigation.languages`. See [Language-specific banners](#language-specific-banners).
</Note>

## Properties [#properties]

<ResponseField name="content" type="string">
  The text content displayed in the banner. Supports basic MDX formatting including links, bold, and italic text. Custom components are not supported.
</ResponseField>

<ResponseField name="dismissible" type="boolean">
  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`.
</ResponseField>

<ResponseField name="type" type="string">
  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.
</ResponseField>

<ResponseField name="color" type="object">
  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.

  <Expandable title="color properties">
    <ResponseField name="light" type="string">
      Hex color used in light mode. If only `dark` is provided, it's used in light mode as well.
    </ResponseField>

    <ResponseField name="dark" type="string">
      Hex color used in dark mode. If only `light` is provided, it's used in dark mode as well.
    </ResponseField>
  </Expandable>
</ResponseField>

## Language-specific banners [#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`.

```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 [#fallback-behavior]

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

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