Primitives

Badge

Beta

Compact status, label, or count chip.

DefaultSmallBeta15DeniedOutlineAllowedneutralredorangeyellowgreenbluepurplepinkLink badge

Composition

The preferred shape for composing the installed primitive from its exported parts.

Root

Single-slot surface with no nested parts.

Badge

First install and activate one skin. Core deliberately contains no visual token defaults.

The Control UI source installs this primitive from src/registry/sources/control-ui/ui/badge.tsx. Install it on its own with the command above, or inspect the source below.

Registry command

npx shadcn@latest add https://control-ui.dev/r/badge.json

See registry manifest

Knobs

Typed custom properties the recipe paints with. Set one on the root — style, a utility class, or a skin — and every slot inherits it.

--cui-badge-* · 4 knobsHow the cascade resolves

--cui-badge-radius<length-percentage>var(--radius-control)

--cui-badge-background*var(--_badge-color-background)

--cui-badge-foreground<color>var(--_badge-color-foreground)

--cui-badge-border-color<color>transparent

Installed dependencies

Support files installed with this primitive — shared ones arrive once with your first Control UI component. Public dependencies stay linked to their own pages.

Theme tokenssrc/registry/sources/control-ui/theme.cssSupport

Raw code

This primitive's source and the support files it installs with

src/registry/sources/control-ui/ui/badge.tsx

"use client";

import { useRender } from "@base-ui/react/use-render";

import type { ComponentProps, CSSProperties } from "react";

import type { RenderProp } from "@/components/control-ui/control-props";

import type { BadgeKnobStyle } from "@/components/control-ui/knob-contracts/badge-knobs";

import { cn } from "@/components/control-ui/lib/cn";

export const badgeVariants = ["default", "outline"] as const;

export type BadgeVariant = (typeof badgeVariants)[number];

export const badgeSizes = ["sm", "md"] as const;

export type BadgeSize = (typeof badgeSizes)[number];

export const BADGE_COLORS = ["neutral", "red", "orange", "yellow", "green", "blue", "purple", "pink"] as const;

export type BadgeColor = (typeof BADGE_COLORS)[number];

export type BadgeProps = Omit<ComponentProps<"span">, "style"> & {

variant?: BadgeVariant;

size?: BadgeSize;

color?: BadgeColor;

render?: RenderProp<ComponentProps<"span">>;

style?: CSSProperties & BadgeKnobStyle;

};

export function Badge({ variant = "default", size = "md", color, render, className, children, ...props }: BadgeProps) {

const resolvedColor = color ?? "neutral";

return useRender({

defaultTagName: "span",

render,

props: {

...props,

"data-control-ui": "badge",

"data-control-family": "badge",

"data-slot": "root",

"data-variant": variant,

"data-size": size,

"data-color": resolvedColor,

className: cn(

        "inline-flex w-fit shrink-0 items-center justify-center gap-1 overflow-hidden whitespace-nowrap [&>svg]:pointer-events-none [&>svg]:size-3",

size === "sm" ? "h-4 px-1.5 py-0" : "px-2 py-0.5",

className,

),

children,

},

});

}