Skip to main content
Callouts sit in the main content and interrupt the reading flow. Some signals work better elsewhere: across the whole site, in the sidebar before a reader opens a page, or as a small label next to the thing it describes. Banners, tags, and badges handle those three cases. A banner appears at the top of every page. It isn’t a component you add to a page. You configure it once with the banner property in docs.json and choose whether readers can dismiss it. Use a banner when:
  • You’re announcing a deprecation that affects a significant portion of your users.
  • A feature is in maintenance mode or temporarily unavailable.
  • There’s a breaking change in an upcoming release that everyone needs to know about before they continue reading.
Set type to match the urgency: info for general announcements, warning for maintenance or upcoming changes, and critical when readers need to act.
Example of a banner in docs.json
If a reader dismisses a banner, it stays hidden for them until you change its content.

​
When not to use a banner

If an announcement is only applicable to a small portion of your users, don’t use a banner. Don’t use a banner for:
  • A new feature announcement that isn’t urgent or widely relevant (write a changelog entry instead).
  • Page-specific notes or warnings (use a callout instead).
  • Content that applies to only some users (the banner appears to everyone).
The cost of a banner is high: it takes up space on every page and if it’s not relevant to people, it trains them to dismiss banners without reading them. Use banners thoughtfully, and retire them promptly.

​
Tag: sidebar labels for pages

The tag frontmatter property adds a short label next to your page title in the sidebar. Use it to signal the status of a page to readers before they open it.
Example of a tag
Tags are useful for:
  • Marking new pages or recently updated content so returning users notice them.
  • Labeling preview or beta features that aren’t yet stable.
For deprecated pages, Mintlify has a specific frontmatter property: deprecated: true.
Example of a deprecated page
This displays a “Deprecated” label next to the page title.

​
Badge: inline labels and status indicators

Use <Badge> components to communicate status, version, or category inline with your content.
Example of a badge
Common uses for badges include:
  • Versions and availability: Available in v2.3+
  • Status indicators: Beta, Deprecated, Enterprise
  • Requirements and defaults: Required, Optional, Default

​
Tags versus badges

Both tags and badges are labels, but they appear in different places and serve different readers. A tag is a sidebar signal. It’s visible before the reader opens a page and useful for readers scanning navigation. A badge appears inside the content and labels something at the point where the reader encounters it. The right choice depends on when the reader needs the information: in the sidebar while navigating or in the content while reading. Next up: Steps or numbered lists—choose the right structure for instructions readers must follow.