Badge

01Preview

Badge and Status badge share one palette. Change the controls to try every supported combination; the preview renders the real component and the code updates with it.

Badge

import { Badge } from '@nuton/ui'

<Badge appearance="light" color="blue">New</Badge>

Status badge

import { StatusBadge } from '@nuton/ui'

<StatusBadge status="completed">Completed</StatusBadge>

02Installation

1. Add the packages

pnpm add @nuton/ui @nuton/tokens @remixicon/react

npm install @nuton/ui @nuton/tokens @remixicon/react

yarn add @nuton/ui @nuton/tokens @remixicon/react

Peer dependencies: react and react-dom 18 or later. Status badge draws its default icons with @remixicon/react, and you pass Remix icons to leadingIcon, trailingIcon and icon (D1).

2. Load tokens and component styles once

// app/layout.tsx (or your app's entry file)
import '@nuton/tokens/tokens.css' // --nu-* design tokens
import '@nuton/ui/styles.css'     // component styles (uses the tokens)

Badges use the Label and Subheading type tokens, which read --nu-font-body (Inter). Map it to your loaded font as described on the Button page.

03Usage

import { Badge, StatusBadge } from '@nuton/ui'

export function LessonRow({ title, isNew, done }: { title: string; isNew: boolean; done: boolean }) {
  return (
    <li>
      {title}
      {isNew && <Badge appearance="light" color="blue">New</Badge>}
      {done
        ? <StatusBadge status="completed">Completed</StatusBadge>
        : <StatusBadge status="information">In progress</StatusBadge>}
    </li>
  )
}

• The default is gray, filled, md. Choose appearance and color for meaning; appearance="light" passes AA in every colour today.
• Use StatusBadge for the status of an item (a submission, a lesson). Its icon shape is a second cue besides colour.
• Write the meaning in words. Colour is never the only cue, so “Failed”, not a red dot.
• Give a numeric badge a label, such as “3 to review”. A bare number means nothing to a screen reader.
• Badges aren't interactive. For something people click or remove, use Tag or Button.

04Variants and sizes

Appearance sets the emphasis and colour sets the meaning. Every colour works with every appearance and size. Status badge is a separate component with a fixed colour per status.

Colour × appearance

Sizes

<Badge appearance="light" color="blue" size="sm">New</Badge>
<Badge appearance="light" color="blue" size="md">New</Badge>
<Badge appearance="light" color="blue" size="lg">New</Badge>

Heights follow Figma's geometry and are computed from the CSS; they haven't been measured in a browser yet. Figma's labels are wrong: “Medium (20)” measures 24 and “Large (32)” measures 28. Code uses the measured geometry, the C4 and C17 principle; correcting the labels is pending a decision. All sizes are pills with a 2px gap; the dot is a 4px circle in a 16px frame.

Types

<Badge appearance="light" color="purple">Basic</Badge>
<Badge appearance="light" color="green" dot>Live</Badge>
<Badge appearance="light" color="blue" leadingIcon={<RiSparkling2Line />}>AI summary</Badge>
<Badge appearance="light" color="gray" trailingIcon={<RiArrowRightSLine />}>3 spaces</Badge>
<Badge appearance="light" color="red" numeric label="5 unread messages">5</Badge>

numeric ignores dot and both icons. The dot and icons take the text colour and are hidden from screen readers.

Status badge

28px tall, radius 6, padding 4 / 8 / 4 / 4, Label/X Small. The icon is 16px with a 4px gap; with dot, a 6px dot in a 16px frame replaces it with a 2px gap. Stroke has a white fill, a Soft-200 border and Sub-600 text; only the icon or dot keeps the status colour. Pass icon to replace the default icon, for example <RiTimeLine /> for a scheduled lesson.

<StatusBadge status="information" icon={<RiTimeLine />}>Scheduled</StatusBadge>

05States and interactions

Badges don't respond to the pointer or keyboard. Their only state is disabled; a status badge's status is content, not a state.

The disabled Large badge in Figma uses the remote “Label/Small” text style, which renders 2px narrower. Code uses the local style (pending a decision).

Palette and component tokens

Both components set data-color and read one shared palette. Override the component tokens on a wrapper only for a documented exception.

06Composition examples

Lesson progress

A status badge on each row tells students where they are. The text names the status; the icon shape repeats it without colour.

<ul aria-label="Biology 101 lessons">
  <li>
    <span>Cell structure and function <span>Reading · 12 min</span></span>
    <StatusBadge status="completed">Completed</StatusBadge>
  </li>
  <li>
    <span>Photosynthesis <span>Video · 18 min</span></span>
    <StatusBadge status="information">In progress</StatusBadge>
  </li>
  <li>
    <span>Plant cells check-in <span>Assignment</span></span>
    <StatusBadge status="pending">Pending review</StatusBadge>
  </li>
  <li>
    <span>Respiration quiz <span>Quiz · 10 questions</span></span>
    <StatusBadge status="failed">Retake needed</StatusBadge>
  </li>
</ul>

Space header

Category and plan badges sit next to a title. Keep it to one or two; more becomes noise.

<p>
  <strong>Year 9 chemistry</strong>
  <Badge appearance="light" color="purple">Pro</Badge>
  <Badge appearance="light" color="blue" leadingIcon={<RiSparkling2Line />}>AI tutor on</Badge>
</p>

Counts

A numeric badge shows how many items need attention. Its label gives screen readers the full meaning, and a status region announces changes.

const [count, setCount] = useState(3)

<p>
  Biology 101 submissions
  {count > 0 && (
    <Badge numeric color="red" appearance="light" label={`${count} to review`}>{count}</Badge>
  )}
</p>
<Button size="sm" appearance="stroke" onClick={markReviewed}>Mark one reviewed</Button>
<p role="status">{message}</p>

Semantics

Badge and Status badge render a <span> with no role. They're read as part of the surrounding text, so place them where that reading makes sense (after the title they describe). Don't put a badge inside a button as its only label, and don't add onClick to it: a clickable badge isn't keyboard-accessible. For a count on a button, give the button an aria-label that includes the number.

07API reference

Badge props

StatusBadge props

Styling hooks

Badge renders .nu-badge with data-appearance, data-color, data-size, data-numeric, data-dot, data-leading, data-trailing and data-disabled. Status badge renders .nu-status-badge with data-status, data-color, data-appearance and data-dot. Use props rather than styling these. The --nu-badge-* and --nu-status-badge-* tokens are the supported override points.

Accessibility

You must: write the meaning in words, never colour alone; give numeric badges a label; announce changing counts in a status region; keep actions out of badges.

Figma mapping

08Guidelines and related components

Do and don't

Common mistakes

• Showing a number with no label, so screen readers announce just “3”.
• Adding onClick to a badge to make it a filter. Use a toggle Tag.
• Using disabled to mean “archived”. It's visual only and low contrast; use Status badge status="disabled" with text.
• Picking a colour for decoration. Colours should map to meaning consistently across a product.

Related components

• TagLabels people can select or remove.
• ProgressHow far through a lesson or upload someone is.
• AvatarStatus indicators on people.
• ColourThe State roles behind the badge palette.