Badge

Badges are small labels. Use them when a reader needs a quick status cue, not a full warning or callout.

Basic example

<Badge text="Stable" color="green" icon="check" />
<Badge text="API" color="blue" icon="braces" />
<Badge text="Preview" color="yellow" icon="timer" />
<Badge text="Deprecated" color="red" icon="warning" />

Colors

Badges support the same color set used by Mintlify-style MDX. Use color as meaning, not decoration.

<Badge color="gray">Gray</Badge>
<Badge color="blue">Blue</Badge>
<Badge color="green">Green</Badge>
<Badge color="yellow">Yellow</Badge>
<Badge color="orange">Orange</Badge>
<Badge color="red">Red</Badge>
<Badge color="purple">Purple</Badge>
<Badge color="white">White</Badge>
<Badge color="surface">Surface</Badge>
<Badge color="white-destructive">White destructive</Badge>
<Badge color="surface-destructive">Surface destructive</Badge>

Sizes and shapes

Use small badges in prose and reference rows. Use larger badges only when the badge is a standalone metadata item.

<Badge size="xs">XS</Badge>
<Badge size="sm">SM</Badge>
<Badge size="md">MD</Badge>
<Badge size="lg">LG</Badge>
<Badge shape="rounded" color="blue">Rounded</Badge>
<Badge shape="pill" color="blue">Pill</Badge>

Icons, stroke, and disabled

Icons add context when the badge labels status. Stroke badges are quieter. Disabled badges mark unavailable or inactive states without removing the label.

<Badge icon="circle-check" color="green">Verified</Badge>
<Badge icon="clock" color="orange">Pending</Badge>
<Badge icon="ban" color="red">Blocked</Badge>
<Badge stroke color="blue">Outlined</Badge>
<Badge disabled icon="lock" color="gray">Locked</Badge>

Inline usage

Badges can appear inside prose when the status is part of the sentence: this endpoint returns JSON , while this feature requires Premium .

This endpoint returns <Badge color="blue" size="sm">JSON</Badge>.
This feature requires <Badge color="orange" size="sm">Premium</Badge>.

Combined properties

Combine props when a label needs more visual precision, but keep the badge short.

<Badge icon="star" color="blue" size="lg" shape="pill">Premium</Badge>
<Badge icon="check" iconType="solid" stroke color="green" size="sm">Verified</Badge>
<Badge icon="badge-alert" color="orange" shape="rounded">Beta</Badge>
<Badge label="Self closing label" color="blue" size="sm" />

Common patterns

Use badges beside headings, field names, or short metadata. Keep the label to one or two words so the badge reads as a cue, not a sentence.

<Badge text="Required" color="red" icon="warning" size="sm" />
<Badge text="Beta" color="purple" icon="sparkles" size="sm" />
<Badge text="SDK" color="green" stroke size="sm" />

With tooltip

Use tooltip when the badge names a short concept that needs a definition, such as an availability state or a release channel.

<Badge
  text="Agent safe"
  color="green"
  icon="shield"
  tooltip="This example can be copied by an agent without private dashboard context."
/>

When to use

Badge usage

Use a badge forstatus, metadata, compact labels

Version markers, API availability, required or optional labels, release states, and small inline qualifiers.

Use a callout forimportant prose

Anything that needs a sentence, a warning, a consequence, or a link to another page.

Use a banner forpage-wide context

Notices that apply to the whole page, such as migration status or an SDK-wide constraint.

Properties

Plandalf extensions

Related