Compact labels for status, counts, and metadata.
Also known as: status badge, count badge, notification badge, meta badge
Install with the CLI, or copy the component source into your project.
Add badge (npm)
1npx --yes -p @default-file/ui df-ui add badge
Default badge label.
All visual variants.
T-shirt sizes from XS to XL. Default is MD.
Corner radius from square to full pill. Default is 4XL.
Instance override for the theme corner curve. Prefer setting round or smooth once at Create / df-ui init --corner-shape; use this prop only when a single badge should differ.
Status chip with StatusDot in the leading slot. The mark follows the badge size and currentColor.
Control space between leading, label, trailing, and count with design-scale units. Omit gap to keep the size default.
Dismissible chip using the trailing slot for the close control.
Bind any numeric count (1 to 4+ digits) via the count prop. Shown on MD, LG, and XL hosts.
Badge as an OptionList trigger with a chevron in the trailing slot. Panel align is configurable: start, end, or auto (content-aware).
Compact label for status and metadata. Label ink is optically centered to cap height with text-box when available, and a 1cap line box otherwise. Inline badges also use vertical-align middle so they sit on the text line next to copy. Use leading and trailing slots for any node before or after the label. Use gap to control space between slots and the label. Compose a nested counter or OptionList dropdown via count, children, and render.
| Prop | Type | Default | Notes |
|---|---|---|---|
| variant | "default" | "secondary" | "destructive" | "outline" | "ghost" | "link" | "default" | Visual style of the badge. |
| size | "xs" | "sm" | "md" | "lg" | "xl" | "md" | T-shirt height and type size. Nested counter chips are supported on md, lg, and xl only. |
| radius | "none" | "xxs" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | "4xl" | "full" | "4xl" | Corner radius of the badge. |
| cornerShape | "round" | "smooth" | - | Instance corner curve. Omit to inherit --df-corner-shape from the theme (set at create/init). |
| gap | number | "none" | - | Space between leading, label, trailing, and count. Design-scale units from the shared spacing scale (none/0, even integers through 200, half-steps such as 0.5 and 1.5). One unit = 0.25rem via --spacing-unit. Omit to use the size default: 0.5 on xs and sm, 1 on md and lg, 1.5 on xl. |
| leading | ReactNode | - | Slot before the label. Pass any node. Prefer StatusDot for online and live presence marks. SVG glyphs inherit the badge size step. |
| trailing | ReactNode | - | Slot after the label. Pass any node (close button, chevron, or custom control). Prefer this over placing trailing nodes in children. |
| count | number | string | - | Trailing count chip bound to any numeric value (1 to 4+ digits). Shown on md, lg, and xl hosts. Renders after the trailing slot. |
| render | ReactElement | - | Host element to clone badge styles onto. For dropdowns, prefer OptionListTrigger render={<Badge />}. |
| children | ReactNode | - | Label content between the leading and trailing slots. Prefer leading and trailing for icons and controls. |
| className | string | - | Additional styles on the badge. |
Patterns built with leading, trailing, count, children, or render. Leading icon (leading): Pass any node to leading for a mark before the label. Prefer StatusDot for a filled presence mark that follows the badge size. SVG children inherit the badge glyph size for the size step. Close button (trailing): Pass a button with an X icon to trailing. The button inherits badge color and is keyboard focusable. Counter (count | children): Prefer the count prop for numeric data. Or nest a second Badge. Host size must be md, lg, or xl so the chip stays readable. Width grows with 1 to 4+ digits.
Pass these on OptionListContent when the badge opens an option list. Placement is relative to the badge trigger. alignOffset (number): Extra shift along the alignment axis in pixels. sideOffset (number): Gap between the badge and the menu. alignItemWithTrigger (boolean): When true, menu width matches the badge. When false, the menu sizes to its option content.
Theme defaults live on :root. Override these globally or on a local host.
| Token | Type | Default | Notes |
|---|---|---|---|
| --df-badge-gap | number | var(--df-badge-gap-md) | Resolved unitless spacing-scale multiplier for space between leading, label, trailing, and count. Set by the gap prop, or from the size default tokens when gap is omitted. |
| --df-badge-gap-xs | number | 0.5 | Default gap step for size xs. |
| --df-badge-gap-sm | number | 0.5 | Default gap step for size sm. |
| --df-badge-gap-md | number | 1 | Default gap step for size md. |
| --df-badge-gap-lg | number | 1 | Default gap step for size lg. |
| --df-badge-gap-xl | number | 1.5 | Default gap step for size xl. |
| --spacing-unit | CSS length | 0.25rem | Base unit multiplied by --df-badge-gap to resolve the flex gap. |
| --primary | CSS color | var(--df-neutral-850, var(--df-neutral-900)) | Default variant fill. |
| --df-badge-secondary-bg | CSS color | var(--df-neutral-100) | Secondary variant fill. One step stronger than accent and muted surfaces. |
| --df-badge-secondary-fg | CSS color | var(--secondary-foreground) | Secondary variant label. |
| --destructive | CSS color | oklch(0.577 0.245 27.325) | Destructive variant fill. |
| --df-badge-outline-border | CSS color | var(--df-neutral-200) | Outline variant border. |
| --muted | CSS color | var(--df-neutral-50) | Ghost variant hover fill. |
| --muted-foreground | CSS color | var(--df-neutral-500) | Ghost variant label. |
| --radius-4xl | CSS length | calc(var(--radius) * 2.6) | Default radius step. The radius prop can select any --radius-* step, from none to full. |
| --df-corner-shape | CSS corner-shape | var(--df-corner-shape-round) | Theme corner curve for all kit chrome. round = circular arcs; smooth = continuous squircle. Set with df-ui init --corner-shape, or override on :root. Default round. |
| --df-label-line-height | CSS line-height | var(--df-leading-none) | Line box for label flex centering. Defaults to --df-leading-none. When text-box is unavailable and the cap unit is supported, the kit sets this to 1cap so flex centering matches cap-height ink. |