Badge

A small, pill-shaped label that tags an item with a status, count, or category. Render Badge inline next to the thing it describes — a row’s status cell, a user’s role, a removable filter chip.

Reach for Badge when the label sits on content (a table cell, a list item, a heading) and the meaning lives in the text. Use Status instead when you want a bare colored dot — with or without a label — to read state at a glance in a dense list. The two share the same colorPalette scale, so a subtle badge and a Status dot stay visually consistent when used side by side.

Variants

variant sets the fill and weight. default (solid primary) and secondary carry the most emphasis; outline, ghost, and subtle recede so a badge can sit quietly inside a busy row; destructive flags errors; link styles the badge as inline link text. The default is default.

DeliveredIn transitExceptionDraftArchivedView labelPre-purchase

import { Badge } from "@vesyl/ui-next";

export default function BadgeVariants() {
  return (
    <div className="flex flex-wrap items-center justify-center gap-3">
      <Badge variant="default">Delivered</Badge>
      <Badge variant="secondary">In transit</Badge>
      <Badge variant="destructive">Exception</Badge>
      <Badge variant="outline">Draft</Badge>
      <Badge variant="ghost">Archived</Badge>
      <Badge variant="link">View label</Badge>
      <Badge variant="subtle">Pre-purchase</Badge>
    </div>
  );
}

Status palettes

Pair variant="subtle" with colorPalette to get a tinted status pill — the standard pattern for shipment and order status cells in the WMS. The palette maps to a domain status (delivered → green, in_transit → blue, exception → red, and so on); colorPalette only changes the look for the subtle variant.

Pre-purchaseIn transitDeliveredPendingDelayedExceptionPicked upOut for deliveryReturnedRefunded

import { Badge } from "@vesyl/ui-next";

export default function BadgePalettes() {
  return (
    <div className="flex flex-wrap items-center justify-center gap-3">
      <Badge variant="subtle" colorPalette="gray">
        Pre-purchase
      </Badge>
      <Badge variant="subtle" colorPalette="blue">
        In transit
      </Badge>
      <Badge variant="subtle" colorPalette="green">
        Delivered
      </Badge>
      <Badge variant="subtle" colorPalette="yellow">
        Pending
      </Badge>
      <Badge variant="subtle" colorPalette="orange">
        Delayed
      </Badge>
      <Badge variant="subtle" colorPalette="red">
        Exception
      </Badge>
      <Badge variant="subtle" colorPalette="teal">
        Picked up
      </Badge>
      <Badge variant="subtle" colorPalette="cyan">
        Out for delivery
      </Badge>
      <Badge variant="subtle" colorPalette="purple">
        Returned
      </Badge>
      <Badge variant="subtle" colorPalette="pink">
        Refunded
      </Badge>
    </div>
  );
}

With a leading icon

Drop a lucide icon before the label. Any leading svg is auto-sized to size-3 and the gap is handled for you, so the icon and text stay aligned without extra classes.

DeliveredIn transitException

import { Badge } from "@vesyl/ui-next";
import { CircleCheck, TriangleAlert, Truck } from "lucide-react";

export default function BadgeIcon() {
  return (
    <div className="flex flex-wrap items-center justify-center gap-3">
      <Badge variant="subtle" colorPalette="green">
        <CircleCheck />
        Delivered
      </Badge>
      <Badge variant="subtle" colorPalette="blue">
        <Truck />
        In transit
      </Badge>
      <Badge variant="subtle" colorPalette="red">
        <TriangleAlert />
        Exception
      </Badge>
    </div>
  );
}

Polymorphic with `render`

Badge renders a <span> by default. Pass render to swap the element — e.g. an <a> to make a clickable tracking or label chip — while keeping the badge styling. The outline, ghost, and link variants pick up hover states automatically when rendered as an anchor.

Track shipment View label

import { Badge } from "@vesyl/ui-next";

export default function BadgeRender() {
  return (
    <div className="flex flex-wrap items-center justify-center gap-3">
      <Badge variant="outline" render={<a href="#tracking" />}>
        Track shipment
      </Badge>
      <Badge variant="subtle" colorPalette="blue" render={<a href="#label" />}>
        View label
      </Badge>
    </div>
  );
}

Reference

Badge

Renders a <span>. Extends the props of the rendered element, plus the badgeVariants options below.

Prop	Type	Default	Description
`variant`	`"default" \| "secondary" \| "destructive" \| "outline" \| "ghost" \| "link" \| "subtle"`	`"default"`	Fill and emphasis of the badge
`colorPalette`	`"gray" \| "red" \| "orange" \| "yellow" \| "green" \| "teal" \| "blue" \| "cyan" \| "purple" \| "pink"`	—	Status tint; only takes effect with `variant="subtle"`
`render`	`ReactElement`	`<span>`	Swap the rendered element (e.g. `<a>`) while keeping badge styling
`className`	`string`	—	Merged onto the badge

badgeVariants is also exported as a standalone cva helper for composing badge styling onto another element.

Badge

Variants

Status palettes

With a leading icon

Polymorphic with render

Reference

Badge

Polymorphic with `render`