# Banner
Use banners for page-level notices that need to sit above the reader's current task.
Source: /docs/components/banner
Last modified: 2026-06-20
Banners are broader than badges and more persistent than inline prose. Use them for availability, migration, or page-wide context.

## Global banner config

Mintlify banners are usually configured in `docs.json` so the notice appears across the documentation site. Plandalf supports the same authoring shape for docs examples, and the MDX Banner component mirrors the same props for page-level demonstrations.

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

## Basic example


> **SDK examples use published offers**
>

  Create or publish the offer before testing `plandalf.present()` from a live page.


```mdx title="banner-example.mdx"

> **SDK examples use published offers**
>

  Create or publish the offer before testing `plandalf.present()` from a live page.


```

## Notice types

Use the semantic type first. Reach for a custom color only when the page has a specific brand or release-state need.


> **Information**
>

  Use information banners for setup context that applies to the whole page.


> **Warning**
>

  Use warnings when a step can fail or behave differently if the reader skips context.


> **Critical**
>

  Use critical banners rarely, usually for breaking changes, deprecations, or security-sensitive constraints.


```mdx title="banner-types.mdx"

> **Information**
>

  Use information banners for setup context that applies to the whole page.


> **Warning**
>

  Use warnings when a step can fail if the reader skips context.


> **Critical**
>

  Use critical banners rarely.


```

## Dismissible notice

Dismissible banners are useful for local docs environments, release notices, or temporary migration notes. Always provide an `id` so the stored dismissal remains stable if the title changes.


> **Temporary migration note**
>

  This banner stores dismissal in local storage and reappears if the content changes.


```mdx title="dismissible-banner.mdx"

> **Temporary migration note**
>

  This banner stores dismissal in local storage and reappears if the content changes.


```

## Custom color

Use `color` for a deliberate brand or release state. A single value applies everywhere; a `light` and `dark` object lets the banner adapt to color mode.


> **Custom color**
>

  This banner uses separate light and dark custom colors while keeping white text.


```mdx title="custom-color-banner.mdx"

> **Custom color**
>

  This banner uses separate light and dark custom colors while keeping white text.


```

## Language-specific banners

When a docs site has localized navigation, the language-level banner should take priority over the global banner. Use the global banner as the fallback.

```json title="language-banners.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": "Version 2.0 is now live! See our [changelog](/es/changelog) for details.",
          "dismissible": true
        },
        "groups": [
          {
            "group": "Getting started",
            "pages": ["es/overview", "es/quickstart"]
          }
        ]
      }
    ]
  },
  "banner": {
    "content": "Version 2.0 is now live!",
    "dismissible": true
  }
}
```

## Content rules


### Banner usage


- `Placement` (top of page or before affected section):
    Put a banner before the content it changes. Do not repeat the same banner between every section.


- `Length` (one short paragraph):
    Keep the copy direct. If the banner needs steps, link to a proper section or another docs page.


- `Dismissal` (temporary context only):
    Do not make permanent warnings dismissible. Dismissal is for release notes, migration windows, and local-only reminders.


## Properties


- `content` (string; required):
  The text content displayed in the banner. Supports basic MDX formatting including links, bold, italic text, and inline code. Custom components are not supported in global `docs.json` banner content.


- `dismissible` (boolean; default: false):
  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.


- `type` (string; default: info):
  The visual style of the banner. Controls the background color so visitors can quickly recognize the urgency of the message.

  * `info`: Best for product announcements and general updates.
  * `warning`: Best for cautionary notices like scheduled maintenance or upcoming deprecations.
  * `critical`: Best for urgent notices that require immediate attention.


- `color` (object):
  Override the banner background color with a custom hex value. When set, this takes precedence over the color implied by `type`.


> **color properties**
>


- `light` (string):
      Hex color used in light mode. If only `dark` is provided, it is used in light mode as well.


- `dark` (string):
      Hex color used in dark mode. If only `light` is provided, it is used in dark mode as well.


## MDX Banner extensions


- `title` (string):
  Short page-level headline when using the MDX `Banner` component directly.


- `tone` (primary | neutral | green | amber):
  Plandalf visual tone when the semantic type is not enough for a page-local banner.


- `id` (string):
  Stable storage key for dismissible MDX banners.


## Related


  - [Badge](/docs/components/badge): Use compact status labels.
  - [Callouts](/docs/components/callouts): Use task-local warnings.
  - [Frame](/docs/components/frames): Use for screenshots and media.