A compact inline marker for status labels, category tags, and notification counts.

Badges render as <span> elements that combine a semantic color, a visual variant, and a size to call out a small piece of metadata next to other content. They are pure markup with no client-side behavior, so they can sit inside table cells, navigation rows, card headers, or button labels without any setup. All styles adapt to light and dark modes through the design system's color tokens.

Usage

The simplest badge is a single piece of text:

<.badge>Default</.badge>

The default variant is surface and the default color is primary. Pair color with the meaning of the label:

<.badge color="success">Active</.badge>
<.badge color="warning">Pending</.badge>
<.badge color="danger">Failed</.badge>

Override variant and size to scale visual weight up or down:

<.badge variant="solid" color="primary">Featured</.badge>
<.badge variant="ghost" color="info" size="sm">Beta</.badge>
<.badge variant="dashed" color="warning" size="lg">Draft</.badge>

Visual Variants

The variant attribute selects how the badge renders its background and border. Each variant produces a distinct emphasis level so a row of badges can mix high-priority and background labels without visual noise.

<.badge variant="solid" color="success">Solid</.badge>
<.badge variant="soft" color="info">Soft</.badge>
<.badge variant="surface" color="warning">Surface</.badge>
<.badge variant="outline" color="primary">Outline</.badge>
<.badge variant="dashed" color="warning">Dashed</.badge>
<.badge variant="ghost" color="primary">Ghost</.badge>

Semantic Colors

The color attribute sets a coordinated foreground, background, and border palette for each variant. Pick the color that matches the meaning of the label, not just the visual preference; this keeps badges consistent across the app and reusable across themes.

<.badge color="primary">Featured</.badge>
<.badge color="info">Information</.badge>
<.badge color="success">Completed</.badge>
<.badge color="warning">Pending</.badge>
<.badge color="danger">Failed</.badge>

Each color combines with each variant to produce a tuned background and text token, so the same label color reads correctly whether it is filled (solid), tinted (soft, surface), or transparent (outline, dashed, ghost).

Sizes

The size attribute scales the badge height, padding, font size, border radius, and inline icon size together. Choose a size that matches the surrounding text scale:

<.badge size="xs">XS</.badge>
<.badge size="sm">SM</.badge>
<.badge size="md">MD</.badge>
<.badge size="lg">LG</.badge>
<.badge size="xl">XL</.badge>

Icons

The badge slot accepts arbitrary inline content, so you can place a Fluxon icon next to the label. Add the icon class to <.icon> so the badge can size and align it from the outside; the size token then follows the badge's size attribute automatically.

<.badge color="success">
  <.icon name="hero-check-circle" class="icon" /> Verified
</.badge>

<.badge color="warning" size="sm">
  <.icon name="hero-clock" class="icon" /> Pending
</.badge>

<.badge color="danger" variant="ghost">
  <.icon name="hero-x-circle" class="icon" /> Failed
</.badge>

<!-- Correct: the badge sizes and aligns the icon -->
<.badge color="success">
  <.icon name="hero-check" class="icon" /> Done
</.badge>

<!-- Wrong: missing "icon" class, the glyph renders at its native size -->
<.badge color="success">
  <.icon name="hero-check" /> Done
</.badge>

Custom Classes and Attributes

The class attribute is merged with the variant, color, and size styles, so utilities you pass through override defaults where they conflict. Any other HTML attribute is forwarded to the underlying <span> through the :rest global, which makes badges easy to wire up to LiveView events:

<.badge color="primary" class="cursor-pointer" phx-click="open_filter">
  Filter
</.badge>

<.badge color="info" data-testid="status-badge" aria-label="Build status: passing">
  Passing
</.badge>

Examples

Status indicator next to a label

<div class="flex items-center gap-2">
  <span class="text-sm font-medium">Database</span>
  <.badge variant="solid" color="success">
    <.icon name="hero-check-circle" class="icon" /> Online
  </.badge>
</div>

Notification count in a navigation row

<.link navigate={~p"/inbox"} class="flex items-center justify-between">
  <span>Messages</span>
  <.badge color="info">{@unread_count}</.badge>
</.link>

Removable filter chips driven by LiveView

<div class="flex flex-wrap gap-2">
  <.badge
    :for={tag <- @active_filters}
    variant="dashed"
    color="primary"
    phx-click="remove_filter"
    phx-value-tag={tag}
    class="cursor-pointer"
    aria-label={"Remove filter #{tag}"}
  >
    <.icon name="hero-x-mark" class="icon" /> {tag}
  </.badge>
</div>

def handle_event("remove_filter", %{"tag" => tag}, socket) do
  {:noreply, update(socket, :active_filters, &List.delete(&1, tag))}
end

Toggleable category in a tag picker

Switch the variant and the icon based on selection state. Toggle styling through data- attributes rather than computing classes when possible; in this example the attribute-based approach lives at the call site since the badge has no built-in selection state:

<.badge
  color={if @selected, do: "primary", else: "info"}
  variant={if @selected, do: "solid", else: "dashed"}
  phx-click="toggle_category"
  phx-value-id={@category.id}
  class="cursor-pointer"
>
  <.icon :if={@selected} name="hero-check" class="icon" />
  {@category.name}
</.badge>

Inline label inside a button

Badges compose cleanly inside other components. Use ghost or soft to stay subtle next to the button label:

<.button variant="outline" navigate={~p"/changelog"}>
  Changelog
  <.badge variant="soft" color="info" size="xs">3 new</.badge>
</.button>

Table cell status

<.table rows={@invoices}>
  <:col :let={invoice} label="Number">{invoice.number}</:col>
  <:col :let={invoice} label="Status">
    <.badge color={invoice_color(invoice.status)} size="sm">
      {String.capitalize(invoice.status)}
    </.badge>
  </:col>
</.table>

defp invoice_color("paid"), do: "success"
defp invoice_color("pending"), do: "warning"
defp invoice_color("overdue"), do: "danger"
defp invoice_color(_), do: "info"