Plandalf

Banner

Use banners for page-level notices that need to sit above the reader's current task.

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.

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

Basic example

<Banner title="SDK examples use published offers" type="info" icon="info">
  Create or publish the offer before testing `plandalf.present()` from a live page.
</Banner>

Notice types

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

<Banner title="Information" type="info" icon="info">
  Use information banners for setup context that applies to the whole page.
</Banner>

<Banner title="Warning" type="warning" icon="warning">
  Use warnings when a step can fail if the reader skips context.
</Banner>

<Banner title="Critical" type="critical" icon="warning">
  Use critical banners rarely.
</Banner>

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.

<Banner id="checkout-sdk-migration" title="Temporary migration note" tone="green" icon="check" dismissible>
  This banner stores dismissal in local storage and reappears if the content changes.
</Banner>

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.

<Banner
  title="Custom color"
  color={{ light: "#0f766e", dark: "#115e59" }}
  icon="sparkles"
  dismissible
  id="component-banner-color-example"
>
  This banner uses separate light and dark custom colors while keeping white text.
</Banner>

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.

{
  "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

Placementtop of page or before affected section

Put a banner before the content it changes. Do not repeat the same banner between every section.

Lengthone short paragraph

Keep the copy direct. If the banner needs steps, link to a proper section or another docs page.

Dismissaltemporary context only

Do not make permanent warnings dismissible. Dismissal is for release notes, migration windows, and local-only reminders.

Properties

contentstringrequired

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.

dismissiblebooleandefault: 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.

typestringdefault: 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.
colorobject

Override the banner background color with a custom hex value. When set, this takes precedence over the color implied by type.

lightstring

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

darkstring

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

MDX Banner extensions

titlestring

Short page-level headline when using the MDX Banner component directly.

toneprimary | neutral | green | amber

Plandalf visual tone when the semantic type is not enough for a page-local banner.

idstring

Stable storage key for dismissible MDX banners.

Badge Use compact status labels.
Callouts Use task-local warnings.
Frame Use for screenshots and media.

Feature detail