Skip to content

Badge

Compact label for status, categories, or counts. Supports theme option colors, an optional icon, and a dot-only mode for minimal status indicators.

import { Badge } from "phoundry-ui";

Variants

Loading interactive example…

View source
variants.svelte
<script lang="ts">
import { Badge } from "phoundry-ui";
</script>
<div class="flex flex-wrap items-center gap-2">
<Badge>Gray</Badge>
<Badge color="blue">Blue</Badge>
<Badge color="green">Green</Badge>
<Badge color="yellow">Yellow</Badge>
<Badge color="red">Red</Badge>
<Badge color="cyan">Cyan</Badge>
</div>

Sizes

Loading interactive example…

View source
sizes.svelte
<script lang="ts">
import { Badge } from "phoundry-ui";
</script>
<p class="mb-2 text-xs text-txt-secondary">
<code>lg</code> increases label typography; combine with <code>icon</code> for dense
toolbar badges.
</p>
<div class="flex flex-wrap items-center gap-2">
<Badge size="xs" color="blue">Extra small</Badge>
<Badge size="sm" color="blue">Small</Badge>
<Badge size="md" color="blue">Medium</Badge>
</div>

With Icon

Loading interactive example…

View source
with-icon.svelte
<script lang="ts">
import { Badge } from "phoundry-ui";
import { PhiIcons } from "phoundry-ui";
</script>
<div class="flex items-center gap-2">
<Badge icon={PhiIcons.edit} color="blue">Featured</Badge>
<Badge icon={PhiIcons.check} color="green">Verified</Badge>
<Badge icon={PhiIcons.warning} color="yellow">Caution</Badge>
</div>

Icon Only

Loading interactive example…

View source
icon-only.svelte
<script lang="ts">
import { Badge } from "phoundry-ui";
import { PhiIcons } from "phoundry-ui";
</script>
<p class="mb-2 text-xs text-txt-secondary">
When there are no <code>children</code>, the badge shrinks to a square chip
sized by <code>size</code>.
</p>
<div class="flex items-center gap-2">
<Badge icon={PhiIcons.info} color="blue" />
<Badge icon={PhiIcons.check} color="green" />
<Badge icon={PhiIcons.warning} color="yellow" />
<Badge icon={PhiIcons.cancel} color="red" />
</div>

Dot Mode

Loading interactive example…

View source
dot-mode.svelte
<script lang="ts">
import { Badge } from "phoundry-ui";
</script>
<div class="flex items-center gap-3">
<div class="flex items-center gap-1.5">
<Badge color="green" dot />
<span class="text-xs text-txt-secondary">Online</span>
</div>
<div class="flex items-center gap-1.5">
<Badge color="yellow" dot />
<span class="text-xs text-txt-secondary">Away</span>
</div>
<div class="flex items-center gap-1.5">
<Badge color="red" dot />
<span class="text-xs text-txt-secondary">Busy</span>
</div>
<div class="flex items-center gap-1.5">
<Badge dot />
<span class="text-xs text-txt-secondary">Offline</span>
</div>
</div>

API

From phoundry-ui@0.4.21

NameTypeDefaultDescription
colorBadgeColor'gray'Theme option color.
sizeBadgeSize'xs'Shared control size: xs 1.25rem, sm 1.5rem, md 1.75rem; defaults to xs.
iconstring—Iconify icon string shown before the label.
dotbooleanfalseRender as a small colored dot instead of a label.
classClassValue—Additional CSS classes.
stylestring—Inline styles on the stable component root.
childrenSnippet<[]>—Badge label content.

Usage tips

  • Use dot mode for compact status indicators next to labels or avatars.
  • In dot mode, only color and size apply - children and icon are ignored.
  • The icon prop accepts any Iconify string (or PhiIcons entries) and scales with size.
  • Combine badges with other components - e.g. inside table cells, card headers, or list items.

Styling

.ph-badge is the stable root hook. Consumer class values are additive, and style applies to that root. Styling uses vanilla CSS with semantic state attributes. Sizes are now xs | sm | md, defaulting to xs. The normal badge uses shared --ph-comp-h-xs/sm/md heights (1.25rem / 1.5rem / 1.75rem), corresponding --ph-comp-icon-* sizes, and Button-aligned typography. Icon-only badges are square. Dots retain their distinct 0.5rem (xs) and 0.625rem (sm / md) dimensions. The root emits data-size, data-color, data-dot, and data-icon-only; colors use the active Theme’s option tokens. Internal part selectors and --_ph-* properties remain implementation details.

When upgrading, rename old sm → xs, md → sm, and lg → md at call sites and in typed size maps. The default changes from sm to xs. The new dimensions follow the shared control tokens rather than preserving the old badge geometry. Replace .phi-badge and .phi-badge-dot hooks with .ph-badge and their corresponding state attributes.

Documentation is licensed under CC BY 4.0. Phoundry names and marks remain reserved.