# Badge
Use badges for compact status labels, version markers, and small inline metadata in Plandalf docs.
Source: /docs/components/badge
Last modified: 2026-06-20
Badges are small labels. Use them when a reader needs a quick status cue, not a full warning or callout.

## Basic example

<div class="not-prose my-6 flex flex-wrap items-center gap-2">
  Stable
  API
  Preview
  Deprecated
</div>

```mdx title="badge-example.mdx"
Stable
API
Preview
Deprecated
```

## Colors

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

<div class="not-prose my-6 flex flex-wrap items-center gap-2">
  Gray
  Blue
  Green
  Yellow
  Orange
  Red
  Purple
  White
  Surface
  White destructive
  Surface destructive
</div>

```mdx title="badge-colors.mdx"
Gray
Blue
Green
Yellow
Orange
Red
Purple
White
Surface
White destructive
Surface destructive
```

## Sizes and shapes

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

<div class="not-prose my-6 flex flex-wrap items-center gap-2">
  XS
  SM
  MD
  LG
  Rounded
  Pill
</div>

```mdx title="badge-sizes-shapes.mdx"
XS
SM
MD
LG
Rounded
Pill
```

## 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.

<div class="not-prose my-6 flex flex-wrap items-center gap-2">
  Verified
  Pending
  Blocked
  Outlined
  Locked
</div>

```mdx title="badge-icons-stroke-disabled.mdx"
Verified
Pending
Blocked
Outlined
Locked
```

## Inline usage

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

```mdx title="inline-badge.mdx"
This endpoint returns JSON.
This feature requires Premium.
```

## Combined properties

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

<div class="not-prose my-6 flex flex-wrap items-center gap-2">
  Premium
  Verified
  Beta
  Self closing label
</div>

```mdx title="badge-combined-props.mdx"
Premium
Verified
Beta
Self closing label
```

## 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.


    <h3 class="m-0 text-base font-semibold text-neutral-950">Status metadata</h3>
    Use color and icon together when a status matters during implementation.
    <div class="not-prose mt-4 flex flex-wrap gap-2">
      Required
      Optional
      Beta
    </div>


    <h3 class="m-0 text-base font-semibold text-neutral-950">Version labels</h3>
    Use stroke badges for quieter compatibility labels inside reference pages.
    <div class="not-prose mt-4 flex flex-wrap gap-2">
      v1
      SDK
      Agent safe
    </div>


```mdx title="badge-patterns.mdx"
Required
Beta
SDK
```

## With tooltip

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

<div class="not-prose my-6 flex flex-wrap items-center gap-2">
  Agent safe
  Planned
</div>

```mdx title="badge-tooltip.mdx"
Agent safe
```

## When to use


### Badge usage


- `Use a badge for` (status, metadata, compact labels):
    Version markers, API availability, required or optional labels, release states, and small inline qualifiers.


- `Use a callout for` (important prose):
    Anything that needs a sentence, a warning, a consequence, or a link to another page.


- `Use a banner for` (page-wide context):
    Notices that apply to the whole page, such as migration status or an SDK-wide constraint.


## Properties


- `color` (string; default: gray):
  Badge color variant.

  Options: `gray`, `blue`, `green`, `yellow`, `orange`, `red`, `purple`, `white`, `surface`, `white-destructive`, `surface-destructive`.


- `size` (string; default: md):
  Badge size.

  Options: `xs`, `sm`, `md`, `lg`.


- `shape` (string; default: rounded):
  Badge shape.

  Options: `rounded`, `pill`.


- `icon` (string):
  The icon to display. Use a shared docs icon name, a supported icon-library name, a URL, or an imported SVG value.


- `iconType` (string):
  Icon style for icon libraries that support style variants.

  Options: `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, `brands`.


- `stroke` (boolean; default: false):
  Display the badge with an outline instead of a filled background.


- `disabled` (boolean; default: false):
  Display the badge in a disabled state with reduced opacity.


- `className` (string):
  Additional CSS classes to apply to the badge.


## Plandalf extensions


- `text | label` (string):
  Visible badge label for self-closing badge usage. Children are still the most portable Mintlify-style label.


- `tooltip` (string):
  Adds a hover and focus tooltip for short definitions.


## Related


  - [Banner](/docs/components/banner): Use for page-level notices.
  - [Callouts](/docs/components/callouts): Use for important prose warnings.
  - [Update](/docs/components/update): Use for changelog-style notes.