Badge

A small label that highlights a status, count, or category.

Usage

import { Badge } from '@appica/ui-react/badge'

<Badge variant="success">Active</Badge>

Badge is a compact, non-interactive label for a piece of metadata — a status, a count, a tag, a category. It renders a <span> by default and sizes to its content. Pick a variant for the color scheme and a size for the scale; drop an icon next to the text and mark it with data-icon="start" / data-icon="end" so the padding tightens on that side.

To make a badge clickable — a filter chip, a category link — pass a render element (an <a> or <button>). The badge then becomes focusable and gains hover/press affordances automatically. For a user-removable token with a built-in dismiss control, reach for Chip instead.

Examples

Default

A single Badge with text children uses the primary variant at the md size.

import { Badge } from '@appica/ui-react/badge'

export default function BadgeDefault() {
  return <Badge>Badge</Badge>
}

Variants

Each variant carries a semantic color. The solid primary/secondary and tinted error/success/warning/info schemes draw attention to a status, while soft, outline, and primary-outline stay quieter for neutral metadata.

import { Badge } from '@appica/ui-react/badge'

export default function BadgeVariants() {
  return (
    <div className="flex flex-wrap items-center justify-center gap-2">
      <Badge variant="primary">Primary</Badge>
      <Badge variant="primary-outline">Primary outline</Badge>
      <Badge variant="secondary">Secondary</Badge>
      <Badge variant="soft">Soft</Badge>
      <Badge variant="outline">Outline</Badge>
      <Badge variant="error">Error</Badge>
      <Badge variant="success">Success</Badge>
      <Badge variant="warning">Warning</Badge>
      <Badge variant="info">Info</Badge>
    </div>
  )
}

On dark backgrounds

The light variant is built for dark or photographic backgrounds — a translucent white fill that reads against the surface beneath it.

import { Badge } from '@appica/ui-react/badge'
import { Crown } from '@appica/icons-react'

export default function BadgeOnDark() {
  return (
    <div className="relative flex h-44 w-full max-w-66 items-end justify-start overflow-hidden rounded-xl">
      <img src="/thumbnail.jpg" alt="" className="absolute inset-0 size-full object-cover" />
      <div className="absolute inset-0 bg-linear-to-t from-black/25 via-transparent to-transparent" />
      <Badge variant="light" className="relative m-3">
        <Crown data-icon="start" />
        Premium
      </Badge>
    </div>
  )
}

Sizes

Four sizes scale the badge from xs to lg. The text and any icons scale together.

import { Badge } from '@appica/ui-react/badge'

export default function BadgeSizes() {
  return (
    <div className="flex flex-wrap items-center justify-center gap-2">
      <Badge size="xs">Extra small</Badge>
      <Badge size="sm">Small</Badge>
      <Badge size="md">Medium</Badge>
      <Badge size="lg">Large</Badge>
    </div>
  )
}

With an icon

Place an icon before or after the text and tag it with data-icon="start" or data-icon="end" — the badge tightens the padding on that edge so the icon sits snug.

import { Badge } from '@appica/ui-react/badge'
import { Check, Flame, BellRinging } from '@appica/icons-react'

export default function BadgeWithIcon() {
  return (
    <div className="flex flex-wrap items-center justify-center gap-2">
      <Badge variant="success">
        <Check data-icon="start" />
        Verified
      </Badge>
      <Badge variant="warning">
        <Flame data-icon="start" />
        Hot
      </Badge>
      <Badge variant="soft">
        Notification
        <BellRinging data-icon="end" />
      </Badge>
    </div>
  )
}

Icon only

The icon-sm, icon-md, and icon-lg sizes render a square badge for a lone icon. Give it an aria-label so the meaning is announced.

import { Badge } from '@appica/ui-react/badge'
import { Check, Star, Bolt } from '@appica/icons-react'

export default function BadgeIconOnly() {
  return (
    <div className="flex flex-wrap items-center justify-center gap-2">
      <Badge variant="success" size="icon-sm" aria-label="Verified">
        <Check />
      </Badge>
      <Badge variant="primary-outline" size="icon-md" aria-label="Featured">
        <Star />
      </Badge>
      <Badge variant="warning" size="icon-lg" aria-label="Boosted">
        <Bolt />
      </Badge>
    </div>
  )
}

Notification count

Absolutely position a small badge against an icon button to surface an unread count. Keep the number in the badge and the count in its aria-label.

import { Badge } from '@appica/ui-react/badge'
import { Button } from '@appica/ui-react/button'
import { Bell } from '@appica/icons-react'

export default function BadgeNotification() {
  return (
    <div className="relative inline-flex">
      <Button variant="outline" size="icon-md" aria-label="Notifications">
        <Bell />
      </Button>
      <Badge
        variant="secondary"
        size="xs"
        className="absolute -inset-e-1.5 -top-1.5 min-w-4 px-1 font-medium"
        aria-label="3 unread notifications"
      >
        3
      </Badge>
    </div>
  )
}

Interactive (link or button)

Pass a render element to turn the badge into a link — a plain <a> or a framework one like a Next.js <Link> — or a <button>. It becomes focusable and animates on hover and press.

'use client'

import { useState } from 'react'
import Link from 'next/link'
import { Badge } from '@appica/ui-react/badge'

export default function BadgeInteractive() {
  const [following, setFollowing] = useState(false)

  return (
    <div className="flex flex-wrap items-center justify-center gap-2">
      <Badge variant="soft" render={<a href="#design" />}>
        Design
      </Badge>
      <Badge variant="outline" render={<Link href="#trending" />}>
        Trending
      </Badge>
      <Badge
        variant={following ? 'primary' : 'primary-outline'}
        render={<button type="button" onClick={() => setFollowing((value) => !value)} />}
      >
        {following ? 'Following' : 'Follow'}
      </Badge>
    </div>
  )
}

RTL

Every Appica UI component supports right-to-left layouts out of the box. Set the dir attribute on a container (commonly your <html> element) so CSS logical properties resolve correctly, and wrap your tree in DirectionProvider so direction-aware behavior follows the same direction.

import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}

The icon flips to the start (right) edge and the tightened padding follows, because both are expressed with logical properties. For setup details and caveats, see the RTL guide.

API reference

Badge is built on Base UI's useRender and renders a <span> by default. Pass a render element to swap the underlying tag (e.g. an <a> or <button>), which also makes it focusable and interactive; render and its state ({ variant, size }) follow Base UI's render conventions. Every other <span> (or the rendered element's) attribute is forwarded.

Prop	Type	Default	Description
`variant`	`'primary' \| 'primary-outline' \| 'secondary' \| 'soft' \| 'outline' \| 'error' \| 'success' \| 'warning' \| 'info' \| 'light'`	`'primary'`	Color scheme.
`size`	`'xs' \| 'sm' \| 'md' \| 'lg' \| 'icon-sm' \| 'icon-md' \| 'icon-lg'`	`'md'`	Scale. The `icon-*` sizes render a square badge for a lone icon.
`children`	`ReactNode`	—	The label content. Tag an icon with `data-icon="start"`/`"end"` to tighten that edge.
`render`	`ReactElement \| ((props, state) => ReactElement)`	—	Replace the `<span>` with another element. Doing so makes the badge focusable/interactive.
`className`	`string`	—	Extra classes, merged via `tailwind-merge`.

Accessibility

A plain Badge is a <span> — purely visual. Don't rely on color alone to convey meaning; back it with text (e.g. "Active", not just a green badge).
For an icon-only badge, supply an aria-label so the icon's meaning is announced.
For a count badge, keep the visible number short and put the full meaning in aria-label (e.g. "3 unread notifications").
When you make a badge interactive via render, render a real <a> or <button> so it's keyboard-focusable and announced with the correct role; the badge applies focusable styling automatically.
Hover/press transitions are skipped when the user prefers reduced motion.

Actions & Inputs

Data Display

Decoration & Effects

Layout

Menus

Navigation

Overlays

Status & Feedback