# Badge

Displays a badge or a component that looks like a badge.

Source: https://webjs.dev/ui/docs/components/badge

```ts
import { html } from '@webjsdev/core';
import { badgeClass } from '#components/ui/badge.ts';

export default function BadgeDemo() {
  return html`
    <div class="flex w-full flex-wrap justify-center gap-2">
      <span data-slot="badge" data-variant="default" class=${badgeClass()}>Badge</span>
      <span data-slot="badge" data-variant="secondary" class=${badgeClass({ variant: 'secondary' })}>Secondary</span>
      <span data-slot="badge" data-variant="destructive" class=${badgeClass({ variant: 'destructive' })}>Destructive</span>
      <span data-slot="badge" data-variant="outline" class=${badgeClass({ variant: 'outline' })}>Outline</span>
    </div>
  `;
}
```

## Installation

```bash
npx @webjsdev/ui add badge
```

### Copy and paste the following code into your project.

````ts title="components/ui/badge.ts"
/**
 * Badge: small visual label. Tier-1 class helper; compose with any
 * inline element (commonly `<span>` or `<a>` for linked badges).
 *
 * shadcn parity:
 *   Badge (variant: default | secondary | destructive | outline | ghost | link)
 *                                  → badgeClass({ variant })
 *
 * The `[a&]:hover:...` hover styles only apply when the element is an `<a>`,
 * so a static `<span>` doesn't pick up an unwanted hover.
 *
 * A11y (required for accessible output): render a static badge as a plain
 * <span> (not focusable, no tabindex). Only an interactive badge (an <a>
 * or <button>) is focusable, and an icon-only one needs an aria-label.
 *
 * Design tokens used: --primary, --secondary, --destructive, --foreground,
 * --accent, --border, --ring.
 *
 * @example
 * ```html
 * <span class=${badgeClass()}>New</span>
 * <span class=${badgeClass({ variant: 'destructive' })}>Error</span>
 * <a class=${badgeClass({ variant: 'link' })} href="/profile">@vivek</a>
 * ```
 */
import { cn } from '../lib/utils.ts';

const BASE =
  'gap-1 rounded-full border border-transparent px-2 py-0.5 text-xs font-medium transition-[color,box-shadow] [&>svg]:size-3 group/badge inline-flex w-fit shrink-0 items-center justify-center overflow-hidden whitespace-nowrap focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 aria-invalid:border-destructive aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 [&>svg]:pointer-events-none';

const VARIANTS = {
  default: 'bg-primary text-primary-foreground [a&]:hover:bg-primary/90',
  secondary: 'bg-secondary text-secondary-foreground [a&]:hover:bg-secondary/90',
  destructive: 'bg-destructive text-white focus-visible:ring-destructive/20 dark:bg-destructive/60 dark:focus-visible:ring-destructive/40 [a&]:hover:bg-destructive/90',
  outline: 'border-border text-foreground [a&]:hover:bg-accent [a&]:hover:text-accent-foreground',
  ghost: '[a&]:hover:bg-accent [a&]:hover:text-accent-foreground',
  link: 'text-primary underline-offset-4 [a&]:hover:underline',
} as const;

export type BadgeVariant = keyof typeof VARIANTS;

export function badgeClass(opts: { variant?: BadgeVariant } & { className?: string } = {}): string {
  return cn(BASE, VARIANTS[opts.variant ?? 'default'], opts.className);
}

/**
 * shadcn's name for {@link badgeClass}, so shadcn code ports verbatim
 * (`badgeVariants({ ... })` is shadcn's `cva` export for `Badge`). Like cva, it
 * merges a `className` into the result.
 */
export function badgeVariants(opts: { variant?: BadgeVariant } & { className?: string } = {}): string {
  return badgeClass(opts);
}
````

### Update the import paths to match your project setup.

## Usage

```ts
import { badgeClass } from '#components/ui/badge.ts';
```

```ts
<span class=${badgeClass({ variant: 'outline' })}>Badge</span>
```

## Variants

Use the `variant` option to change the variant of the badge.

```ts
import { html } from '@webjsdev/core';
import { badgeClass } from '#components/ui/badge.ts';

export default function BadgeVariants() {
  return html`
    <div class="flex flex-wrap gap-2">
      <span data-slot="badge" data-variant="default" class=${badgeClass()}>Default</span>
      <span data-slot="badge" data-variant="secondary" class=${badgeClass({ variant: 'secondary' })}>Secondary</span>
      <span data-slot="badge" data-variant="destructive" class=${badgeClass({ variant: 'destructive' })}>Destructive</span>
      <span data-slot="badge" data-variant="outline" class=${badgeClass({ variant: 'outline' })}>Outline</span>
      <span data-slot="badge" data-variant="ghost" class=${badgeClass({ variant: 'ghost' })}>Ghost</span>
    </div>
  `;
}
```

## With Icon

You can render an icon inside the badge. Use `data-icon="inline-start"` to render the icon on the left and `data-icon="inline-end"` to render the icon on the right.

```ts
import { html } from '@webjsdev/core';
import { badgeClass } from '#components/ui/badge.ts';
import { BadgeCheck, BookmarkIcon } from '#lib/ui/lucide.ts';

export default function BadgeWithIconLeft() {
  return html`
    <div class="flex flex-wrap gap-2">
      <span data-slot="badge" data-variant="secondary" class=${badgeClass({ variant: 'secondary' })}>
        ${BadgeCheck()}
        Verified
      </span>
      <span data-slot="badge" data-variant="outline" class=${badgeClass({ variant: 'outline' })}>
        Bookmark
        ${BookmarkIcon()}
      </span>
    </div>
  `;
}
```

## With Spinner

You can render a `spinner()` inside the badge. Remember to add the `data-icon="inline-start"` or `data-icon="inline-end"` attribute to the spinner.

```ts
import { html } from '@webjsdev/core';
import { badgeClass } from '#components/ui/badge.ts';
import { spinner } from '#components/ui/spinner.ts';

export default function BadgeWithSpinner() {
  return html`
    <div class="flex flex-wrap gap-2">
      <span data-slot="badge" data-variant="destructive" class=${badgeClass({ variant: 'destructive' })}>
        ${spinner({ decorative: true })}
        Deleting
      </span>
      <span data-slot="badge" data-variant="secondary" class=${badgeClass({ variant: 'secondary' })}>
        Generating
        ${spinner({ decorative: true })}
      </span>
    </div>
  `;
}
```

## Link

A class helper styles any element, so a link that looks like a badge is an `<a>` with the badge's classes. The hover styles apply only when the element is a link.

```ts
import { html } from '@webjsdev/core';
import { badgeClass } from '#components/ui/badge.ts';
import { ArrowUpRightIcon } from '#lib/ui/lucide.ts';

export default function BadgeAsLink() {
  return html`
    <a href="#link" data-slot="badge" data-variant="default" class=${badgeClass()}>
      Open Link ${ArrowUpRightIcon()}
    </a>
  `;
}
```

## Custom Colors

You can customize the colors of a badge by adding custom classes such as `bg-green-50 dark:bg-green-800`, merged with the helper's through `cn()`.

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { badgeClass } from '#components/ui/badge.ts';

export default function BadgeCustomColors() {
  return html`
    <div class="flex flex-wrap gap-2">
      <span data-slot="badge" data-variant="default" class=${cn(badgeClass(), 'bg-blue-50 text-blue-700 dark:bg-blue-950 dark:text-blue-300')}>
        Blue
      </span>
      <span data-slot="badge" data-variant="default" class=${cn(badgeClass(), 'bg-green-50 text-green-700 dark:bg-green-950 dark:text-green-300')}>
        Green
      </span>
      <span data-slot="badge" data-variant="default" class=${cn(badgeClass(), 'bg-sky-50 text-sky-700 dark:bg-sky-950 dark:text-sky-300')}>
        Sky
      </span>
      <span data-slot="badge" data-variant="default" class=${cn(badgeClass(), 'bg-purple-50 text-purple-700 dark:bg-purple-950 dark:text-purple-300')}>
        Purple
      </span>
      <span data-slot="badge" data-variant="default" class=${cn(badgeClass(), 'bg-red-50 text-red-700 dark:bg-red-950 dark:text-red-300')}>
        Red
      </span>
    </div>
  `;
}
```

## RTL

To enable RTL support, see the [RTL configuration guide](https://webjs.dev/ui/docs/rtl).

```ts
import { html } from '@webjsdev/core';
import { badgeClass } from '#components/ui/badge.ts';
import { BadgeCheck, BookmarkIcon } from '#lib/ui/lucide.ts';

const translations = {
  en: {
    dir: 'ltr',
    values: {
      badge: 'Badge',
      secondary: 'Secondary',
      destructive: 'Destructive',
      outline: 'Outline',
      verified: 'Verified',
      bookmark: 'Bookmark',
    },
  },
  ar: {
    dir: 'rtl',
    values: {
      badge: 'شارة',
      secondary: 'ثانوي',
      destructive: 'مدمر',
      outline: 'مخطط',
      verified: 'متحقق',
      bookmark: 'إشارة مرجعية',
    },
  },
  he: {
    dir: 'rtl',
    values: {
      badge: 'תג',
      secondary: 'משני',
      destructive: 'הרסני',
      outline: 'קווי מתאר',
      verified: 'מאומת',
      bookmark: 'סימנייה',
    },
  },
};

export default function BadgeRtl() {
  const lang = 'ar';
  const { dir, values: t } = translations[lang];

  return html`
    <div class="flex w-full flex-wrap justify-center gap-2" dir=${dir} lang=${lang}>
      <span data-slot="badge" data-variant="default" class=${badgeClass()}>${t.badge}</span>
      <span data-slot="badge" data-variant="secondary" class=${badgeClass({ variant: 'secondary' })}>${t.secondary}</span>
      <span data-slot="badge" data-variant="destructive" class=${badgeClass({ variant: 'destructive' })}>${t.destructive}</span>
      <span data-slot="badge" data-variant="outline" class=${badgeClass({ variant: 'outline' })}>${t.outline}</span>
      <span data-slot="badge" data-variant="secondary" class=${badgeClass({ variant: 'secondary' })}>
        ${BadgeCheck()}
        ${t.verified}
      </span>
      <span data-slot="badge" data-variant="outline" class=${badgeClass({ variant: 'outline' })}>
        ${t.bookmark}
        ${BookmarkIcon()}
      </span>
    </div>
  `;
}
```

## API Reference

### badgeClass

`badgeClass()` returns the classes for a badge or an element that looks like a badge. Put them on a `<span>` for a static badge, or on an `<a>` or `<button>` for an interactive one. `badgeVariants()` is an alias of `badgeClass()` that also merges a `className`.

| Option | Type | Default |
| --- | --- | --- |
| `variant` | `"default" \| "secondary" \| "destructive" \| "outline" \| "ghost" \| "link"` | `"default"` |
