Badge

A small label for a status, a count or a category.

BadgeSecondaryDestructiveOutline
import { Badge } from "@/components/ui/badge"
import { HStack } from "@/components/ui/stack"

export default function BadgeDemo() {
  return (
    <HStack align="center" gap={2} wrap="wrap">
      <Badge>Badge</Badge>
      <Badge variant="secondary">Secondary</Badge>
      <Badge variant="destructive">Destructive</Badge>
      <Badge variant="outline">Outline</Badge>
    </HStack>
  )
}

Installation

pnpm dlx shadcn@latest add @arene/badge

Needs the arene setup first.

Usage

import { Badge } from "@/components/ui/badge"
<Badge variant="secondary">Badge</Badge>

Variants

Pick a style with variant.

DefaultSecondaryDestructiveOutlineGhostLink
import { Badge } from "@/components/ui/badge"
import { HStack } from "@/components/ui/stack"

export default function BadgeVariants() {
  return (
    <HStack align="center" gap={2} wrap="wrap">
      <Badge variant="default">Default</Badge>
      <Badge variant="secondary">Secondary</Badge>
      <Badge variant="destructive">Destructive</Badge>
      <Badge variant="outline">Outline</Badge>
      <Badge variant="ghost">Ghost</Badge>
      <Badge variant="link">Link</Badge>
    </HStack>
  )
}

With icon

Set iconPosition to the side the icon is on, so the badge tightens its padding there.

Peer reviewedSaved
import { Badge } from "@/components/ui/badge"
import { HStack } from "@/components/ui/stack"
import { SealCheckIcon } from "@phosphor-icons/react/dist/csr/SealCheck"
import { BookmarkSimpleIcon } from "@phosphor-icons/react/dist/csr/BookmarkSimple"

export default function BadgeWithIcon() {
  return (
    <HStack align="center" gap={2} wrap="wrap">
      <Badge variant="secondary" iconPosition="start">
        <SealCheckIcon aria-hidden="true" />
        Peer reviewed
      </Badge>
      <Badge variant="outline" iconPosition="end">
        Saved
        <BookmarkSimpleIcon aria-hidden="true" />
      </Badge>
    </HStack>
  )
}

Without iconPosition the padding stays symmetric and the glyph looks inset against the round end. StyleX has no :has(), so the badge has to be told which side the icon is on.

Loading

Render a Spinner and set iconPosition to its side.

DeletingGenerating
import { Badge } from "@/components/ui/badge"
import { Spinner } from "@/components/ui/spinner"
import { HStack } from "@/components/ui/stack"

export default function BadgeLoading() {
  return (
    <HStack align="center" gap={2} wrap="wrap">
      <Badge variant="destructive" iconPosition="start">
        <Spinner aria-hidden="true" />
        Deleting
      </Badge>
      <Badge variant="secondary" iconPosition="end">
        Generating
        <Spinner aria-hidden="true" />
      </Badge>
    </HStack>
  )
}

Pass render to change the element the badge renders.

import * as stylex from "@stylexjs/stylex"
import { color } from "@/theme/tokens.stylex"
import { Badge } from "@/components/ui/badge"
import { HStack } from "@/components/ui/stack"
import { ArrowUpRightIcon } from "@phosphor-icons/react/dist/csr/ArrowUpRight"

const styles = stylex.create({
  primary: {
    backgroundColor: {
      default: color.primary,
      ":hover": `color-mix(in oklab, ${color.primary} 80%, transparent)`,
    },
  },
  outline: { backgroundColor: { default: null, ":hover": color.muted } },
})

export default function BadgeAsLink() {
  return (
    <HStack align="center" gap={2} wrap="wrap">
      <Badge
        xstyle={styles.primary}
        render={<a href="https://base-ui.com" target="_blank" rel="noopener noreferrer" />}
      >
        Base UI
      </Badge>
      <Badge
        variant="outline"
        xstyle={styles.outline}
        iconPosition="end"
        render={<a href="https://base-ui.com/react/utils/use-render" />}
      >
        useRender
        <ArrowUpRightIcon aria-hidden="true" />
      </Badge>
    </HStack>
  )
}

Badges have no built-in hover styles. Add a hover through xstyle when using render for a link or another interactive element.

Custom colors

Pass xstyle to change the background, border and text colors.

InfoSuccessWarningTip
import * as stylex from "@stylexjs/stylex"
import { Badge } from "@/components/ui/badge"
import { HStack } from "@/components/ui/stack"
import { color } from "@/theme/tokens.stylex"

const styles = stylex.create({
  info: {
    backgroundColor: color.infoBg,
    borderColor: color.infoBorder,
    color: color.info,
  },
  success: {
    backgroundColor: color.successBg,
    borderColor: color.successBorder,
    color: color.success,
  },
  warn: {
    backgroundColor: color.warningBg,
    borderColor: color.warningBorder,
    color: color.warning,
  },
  tip: {
    backgroundColor: color.tipBg,
    borderColor: color.tipBorder,
    color: color.tip,
  },
})

export default function BadgeColors() {
  return (
    <HStack align="center" gap={2} wrap="wrap">
      <Badge xstyle={styles.info}>Info</Badge>
      <Badge xstyle={styles.success}>Success</Badge>
      <Badge xstyle={styles.warn}>Warning</Badge>
      <Badge xstyle={styles.tip}>Tip</Badge>
    </HStack>
  )
}

API reference

Pass render to replace a part's element or compose it with another component.

Badge

Renders a span through Base UI's useRender, so it accepts render alongside every span attribute.

PropTypeDefault
variant"default" | "secondary" | "destructive" | "outline" | "ghost" | "link""default"
iconPosition"start" | "end" | "both"—
renderReactElement | ((props, state) => ReactElement)<span />
xstyleStyleXStyles—
classNamestring—

xstyle is merged last, so it beats the variant. className is concatenated with no conflict resolution. Use it for plain-CSS hooks.

Setting aria-invalid switches the border and ring to the destructive pair.

badgeStyles

The style maps behind Badge. Spread them onto any element:

import * as stylex from "@stylexjs/stylex"
import { badgeStyles } from "@/components/ui/badge"
import { clsx } from "clsx"

const sx = stylex.props(badgeStyles.base, badgeStyles.variants.outline)

;<span data-variant="outline" {...sx} className={clsx("arene-icons", sx.className)} />

Merge className from the stylex.props() result by hand. A second className attribute beside the spread replaces it.

KeyWhat it is
baseShape and type, with the shared focus ring
variantsOne namespace per variant
iconStartLeading-icon padding
iconEndTrailing-icon padding

base is two styles, the badge's own and the shared states.focusRing. Set a border of your own through --arene-border-color rather than borderColor. A flat borderColor replaces the property with all of its conditions, so the ring loses its focus colour.

Keep the arene-icons class. interop.css sizes icons off it, and without it a Phosphor icon keeps its default 1em size.

Data attributes

AttributeOnEffect
data-slot="badge"the badgeTargets the badge from a parent
data-variantthe badgeReflects the variant prop, for styling from a parent

CSS variables

VariableOnEffect
--arene-icon-sizethe badgeThe icon's size, read by interop.css. Defaults to 12px
--arene-border-colorthe badgeThe resting border colour the focus ring reads. outline sets it