Badge
A short label for a status, a plan, or a category.
Colors
Use white (the default) for neutral metadata, gray for a strong neutral label such as Deprecated, and a brand color when the label must stand out. The colors have no fixed meaning. Badge and Chip share these colors.
Solid and soft
Use solid (the default) for one label that must stand out. Use soft when there are many labels, such as tags in a list. White looks the same in both.
Sizes
Use sm (the default) for most badges. Use md when the badge sits beside larger text, such as a card title.
Icon and long text
Use an icon when it makes the label faster to recognize. Long labels truncate.
Links
Pass href to make the badge a link. Internal links open in the app window, like the site Link.
With a preview
Pass the card content in preview. With href, the badge uses PreviewCard, which opens on hover or keyboard focus. Without href, the badge is a button and uses Popover, which also opens on click and tap. The content mounts only when the card opens.
Inline
Set size to inline to put a badge in a heading or a sentence. The badge scales with the text around it and does not break across lines.
Session replay Beta
Mobile replay is New and works with React Native, iOS, and Android. Web replay is GA.
Small text with a Paid badge.
Usage
These are defaults, not laws. Break one when you have a good reason, or when it makes the design more cohesive or more interesting.
- Choose the component from where the message sits and what the user does with it.
Component Use it for Badge A status or category that the user reads, such as Beta. Chip A thing the user can open or act on, such as a person, a filter, or a selected value. Note Context inside content, such as a tip in a docs page. Banner A notice about the whole page, at the top. One at a time. Toast Brief feedback after an action. - A badge with href is a link. For an action, use a Button.
- Put the meaning in the text. Colors are decoration and do not mean a status.
- On a link badge, a preview repeats or extends what the link target shows. Do not put actions or required information in it, because touch users do not see it. A badge without href can hold them, because its card opens on tap.
API
Badge is a site component, not a Base UI component. Without href, it accepts span element props. With href, it takes the props of the site Link.
Badge
| Prop | Type | Default | Description |
|---|---|---|---|
| color | 'white' | 'gray' | 'brand' | 'blue' | 'cobalt' | 'coral' | 'corn-blue' | 'green' | 'lemon' | 'lime' | 'purple' | 'tangerine' | 'teal' | 'violet' | 'yellow' | 'white' | Sets the color: white, gray, or a PostHog brand color. |
| appearance | 'solid' | 'soft' | 'solid' | Sets the fill and border of a color other than white. |
| size | 'sm' | 'md' | 'inline' | 'sm' | Sets the height and text size. inline scales the badge with the text around it. |
| href | string | – | Makes the badge a link. It renders the site Link, so internal links open in the app. For an external URL, pass externalNoIcon to open it in a new tab. |
| preview | ReactNode | – | The content of a card that opens on hover. With href, it is a PreviewCard. Without href, the badge becomes a button with a Popover. Load the data for the card inside this content, so the request starts when the card opens. |
| icon | ReactNode | – | Adds a decorative icon before the label. |
| children | ReactNode | – | The badge label. |