Tag

01Preview

Change the controls to try every supported combination. The tag is live: click it when it's a toggle, and remove it when it's removable.

import { Tag } from '@nuton/ui'

<Tag
  leading={<RiBookOpenLine />}
  sublabel="(4)"
  onRemove={removeTopic}
>
  Biology
</Tag>

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. Tag draws its dismiss icon with @remixicon/react, and you pass Remix icons to the leading slot (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)

Tags use the Label/X Small and Paragraph/X Small type tokens, which read --nu-font-body (Inter). Map it to your loaded font as described on the Button page.

03Usage

import { Tag } from '@nuton/ui'

export function LessonTopics({ topics, onRemove }: { topics: string[]; onRemove: (topic: string) => void }) {
  return (
    <div role="group" aria-label="Lesson topics">
      {topics.map((topic) => (
        <Tag key={topic} onRemove={() => onRemove(topic)}>{topic}</Tag>
      ))}
    </div>
  )
}

• The default is a stroke, static tag: plain text in a 28px outlined chip. It does nothing until you pass onClick or onRemove.
• onClick makes the tag a toggle button; pair it with active, which sets aria-pressed. Use it for filters.
• onRemove adds the dismiss button. The component doesn't move focus after a removal, so you must.
• Keep labels to one or two words in sentence case. Put counts in sublabel, for example “(4)”.
• For a status people can't act on (“Completed”, “New”), use Badge instead.

04Variants and sizes

Tag has one size and two appearances. What it holds (a leading icon, an avatar or a sublabel) and what it does (nothing, toggle or remove) combine freely.

Appearance × leading content

Figma's six types (Basic, Left Icon, Avatar, Country, Brand and Company) are one leading slot. Use leadingKind="icon" (the default) for a Remix icon, which takes the state's icon colour, and leadingKind="media" for an avatar, flag or logo, which keeps its own colours and fades to 48% when disabled. An <Avatar> in the slot shrinks to 16px and shows one initial (P2). No flags or brand logos ship in @nuton/ui (D12, C15): your app supplies them.

Dismiss icon

const [spaces, setSpaces] = useState(['Biology 101', 'Year 9 chemistry', 'Exam revision'])

<div role="group" aria-label="Shared with spaces">
  {spaces.map((space) => (
    <Tag key={space} onRemove={() => setSpaces((s) => s.filter((x) => x !== space))}>
      {space}
    </Tag>
  ))}
</div>
// After a removal, move focus to the next tag (see Composition examples).

The remove button is named “Remove <label>” when the label is plain text. Pass removeLabel otherwise, or to localise it.

Toggle

const [notStarted, setNotStarted] = useState(true)
const [saved, setSaved] = useState(false)

<div role="group" aria-label="Show lessons">
  <Tag active={notStarted} onClick={() => setNotStarted(!notStarted)}>Not started</Tag>
  <Tag active={saved} onClick={() => setSaved(!saved)}>Saved</Tag>
</div>

Size

<Tag>Biology</Tag>
<Tag leading={<RiPriceTag3Line />} sublabel="(4)">Chemistry</Tag>

Values follow Figma's geometry (Tag [1.1] 57:17219) and are computed from the CSS. They haven't been measured in a browser yet, which the template requires before Stable. Long labels truncate with an ellipsis when the tag is narrower than its content.

05States and interactions

State tokens

Each state sets the tag's component tokens. Override them on a wrapper only for a documented exception.

Two colours are pending a decision: the sublabel uses local Text/Sub-600 instead of the remote 01-Tokens Soft-400 it binds (following D7 and C19), and Figma's Gray hover keeps the dismiss icon at Soft-400 while Stroke hover darkens it. Code implements that hover as bound; it's a candidate for the Figma cleanup batch (D9).

06Composition examples

Filter lessons

Topic tags are toggles. The selected topics also appear as removable gray tags, and a status line announces the result. Remove a filter with the mouse, or focus it and press Delete: focus moves to the next filter, then to the topic's toggle when none are left.

const [selected, setSelected] = useState(['Biology', 'Maths'])

<div role="group" aria-label="Filter lessons by topic">
  {topics.map((topic) => (
    <Tag
      key={topic}
      active={selected.includes(topic)}
      sublabel={`(${countFor(topic)})`}
      onClick={() => toggle(topic)}
    >
      {topic}
    </Tag>
  ))}
</div>

<div role="group" aria-label="Applied filters">
  {selected.map((topic) => (
    <Tag key={topic} appearance="gray" onRemove={() => removeFilter(topic)}>{topic}</Tag>
  ))}
  <Button size="sm" appearance="ghost" onClick={clearFilters}>Clear filters</Button>
</div>

<p role="status">Showing {shown.length} of {lessons.length} lessons</p>

Add and remove topics

A field adds topics to a lesson; each one is a removable tag. When the last tag goes, focus returns to the input.

<form onSubmit={addTopic}>
  <Field label="Lesson topics" hint="Press Enter to add a topic. Students can filter by these." error={error}>
    <Input ref={inputRef} size="sm" value={draft} onChange={(e) => setDraft(e.target.value)} />
  </Field>
  <div role="group" aria-label="Added topics">
    {topics.map((topic) => (
      <Tag key={topic} onRemove={() => removeTopic(topic)}>{topic}</Tag>
    ))}
  </div>
  <Button size="sm" type="submit">Add topic</Button>
</form>

Keywords on a lesson

Static tags describe content. Next to them, the lesson's status is a Status badge, because it's a state, not a keyword.

<StatusBadge status="completed">Completed</StatusBadge>
<Tag appearance="gray">Photosynthesis</Tag>
<Tag appearance="gray">Plant cells</Tag>
<Tag appearance="gray">Year 9</Tag>

Navigation and semantics

Tag renders a <span>, or a <button> with onClick. It has no link mode: don't navigate from onClick, and don't wrap a tag in an <a>. For a keyword that opens a search page, use a link. Wrap related tags in an element with role="group" and an aria-label, or in a list when their number matters.

07API reference

Props

Styling hooks

The component renders .nu-tag with data-appearance, data-active, data-disabled, data-interactive, data-leading (the leading kind) and data-removable. Its parts are .nu-tag__main, .nu-tag__leading, .nu-tag__label, .nu-tag__sublabel and .nu-tag__remove. Use props rather than styling these. The --nu-tag-* tokens (see State tokens) are the supported override points.

Accessibility

You must: move focus to the next tag or the input after a removal; pass removeLabel when the label isn't plain text or the UI isn't in English; give a group of toggle tags an accessible name; use a link, not a tag, for navigation.

Figma mapping

08Guidelines and related components

Do and don't

Common mistakes

• Removing a tag and leaving focus on nothing, so keyboard users are sent back to the top of the page.
• Using active on a static tag with nothing else to show the selection.
• Passing a non-text label (an element) to a removable tag without removeLabel, so the button is just “Remove”.
• Changing the results of a filter without announcing them in a status region.

Related components

• BadgeNon-interactive status, category and count labels.
• Button groupA segmented choice between a few options.
• AvatarPeople in the tag’s leading slot.
• Inputs and fieldsThe input that adds tags.
• CheckboxMultiple selection in a form or long list.