Badges are inline labels that signal the status of a feature or page. They're small enough to drop next to a heading or in a sentence without disrupting the flow.
Examples#
Default Beta New Pro plan Deprecated
Source#
MDX
<Badge color="yellow">Pro plan</Badge>Props#
| Prop | Values | Default | Description |
|---|---|---|---|
color | gray, blue, green, yellow, orange, red, purple | gray | Background and text color |
size | xs, sm, md, lg | md | Visual size |
shape | rounded, pill | rounded | Corner radius |
icon | Lucide icon name | none | Optional inline icon (e.g., rocket, check) |
stroke | boolean | false | Outline-only variant |
children | string | required | The label text. Keep it short — one or two words. |
Common patterns#
Plan-gating a heading#
MDX
## Custom CSS <Badge color="yellow">Pro</Badge>Renders the heading with the badge inline. Readers immediately see the feature requires Pro.
Marking new or beta features#
MDX
### Webhooks <Badge color="green">New</Badge>
### MCP integration <Badge color="blue">Beta</Badge>Marking deprecated APIs#
MDX
### `client.users.fetch()` <Badge color="red">Deprecated</Badge>Always pair Deprecated badges with a callout explaining the replacement:
Deprecated
Use client.users.get() instead. fetch() will be removed in v2.0.
When not to use a Badge#
- Don't put more than one Badge on the same heading. It looks busy.
- Don't use Badges for marketing language ("Awesome!", "Hot!"). They're informational, not promotional.
- Don't use a Badge where a Callout would carry the message better. Badges are flags, not warnings.