display

Badge

A compact status label sharing the same variant and tone table as Button.

Variants

SolidSoftOutline

Status dots

The `dot` prop is what makes a badge readable at a glance in a long list.

OperationalDegradedOutageUnknown

Own the source

Noksha ships as a package and as copy-paste source. Take the files and they are yours to change. These are read from the generated registry, so they are exactly what the library ships — never a paraphrase of it.

Take these files, and internal helpers along with them — the imports below point at them. Or let the CLI do it: npx @noksha-ui/cli add badge writes them, follows the same dependency graph, and fixes up the imports.

import { Slot, Slottable } from '@noksha-ui/core';
import * as React from 'react';
import type { BadgeProps } from './badge.types.js';
import { badgeDotVariants, badgeVariants } from './badge.variants.js';

/**
 * A small status label.
 *
 * ```tsx
 * <Badge tone="success" dot>Live</Badge>
 * <Badge variant="outline" tone="neutral">Draft</Badge>
 * ```
 *
 * It is a `<span>`, not a button: a badge that can be clicked or dismissed is a
 * different control with different a11y requirements, and conflating the two is
 * how "chip" components end up unusable from the keyboard.
 */
export const Badge = React.forwardRef<HTMLSpanElement, BadgeProps>(function Badge(
  {
    variant = 'soft',
    tone = 'accent',
    size = 'md',
    dot = false,
    icon,
    asChild = false,
    className,
    children,
    ...rest
  },
  ref,
) {
  const Comp = asChild ? Slot : 'span';

  return (
    <Comp ref={ref} className={badgeVariants({ variant, tone, size, className })} {...rest}>
      {dot ? <span aria-hidden="true" className={badgeDotVariants({ size })} /> : null}
      {icon}
      <Slottable>{children}</Slottable>
    </Comp>
  );
}) as (props: BadgeProps & React.RefAttributes<HTMLSpanElement>) => React.ReactElement | null;

(Badge as unknown as { displayName: string }).displayName = 'Badge';

export { badgeVariants };

API reference

Accepted values

BadgeVariant: solidsoftoutline
BadgeSize: smmdlg

BadgeProps

Also accepts everything from React.HTMLAttributes<HTMLSpanElement>.

Prop	Type	Description
variant	BadgeVariant	Visual weight. Never merged with `tone` — see ADR-007.
tone	BadgeTone	Semantic color.
size	BadgeSize	—
dot	boolean	A small filled circle before the label, for status lists.
icon	React.ReactNode	—
asChild	boolean	Renders the child element instead of a `<span>`.