Token

ColoursCopy Anchor Link

color picks one of eleven colours. default is a neutral grey. Pick a colour for its meaning in the product and keep it consistent across a list.

<Token>Design</Token>
<Token color="red">Overdue</Token>
<Token color="orange">Homework</Token>
<Token color="yellow">Quiz</Token>
<Token color="green">Approved</Token>
<Token color="teal">Science</Token>
<Token color="cyan">Mathematics</Token>
<Token color="blue">History</Token>
<Token color="purple">Art</Token>
<Token color="pink">Music</Token>
<Token color="gray">Elective</Token>

SizesCopy Anchor Link

Three heights, 20, 24 and 28px. small is the default. Padding, gap, font and slots stay the same at every size.

<Token color="blue" size="small">
  Small
</Token>
<Token color="blue" size="medium">
  Medium
</Token>
<Token color="blue" size="large">
  Large
</Token>

IconsCopy Anchor Link

leadingIcon and trailingIcon render in 16px boxes and take the text colour. Slot content is decorative, so mark icons aria-hidden.

<Token color="blue" leadingIcon={<IconUserSingleUser aria-hidden />}>
  Assigned to me
</Token>
<Token
  color="purple"
  trailingIcon={<IconFoldersFolderLink aria-hidden />}
>
  Shared folder
</Token>

RemovableCopy Anchor Link

onRemove adds a 20px remove button. It runs on a click, or on Enter or Space. The Token does not hide itself. The caller removes it from its list.

After a removal, move focus to a neighbouring Token or to another control, because the removed Token unmounts. This demo moves focus to the next remove button, then the previous one, then the reset button.

<div className="flex flex-col items-center gap-spacing-12">
  <ul
    ref={list}
    aria-label="Subjects"
    className="flex flex-wrap gap-spacing-8"
  >
    {subjects.map((subject) => (
      <Token
        key={subject}
        render={<li />}
        color="cyan"
        size="medium"
        onRemove={remove(subject)}
      >
        {subject}
      </Token>
    ))}
  </ul>
  <button
    ref={reset}
    type="button"
    className={`${typography('h5-medium')} text-color-text-primary underline`}
    onClick={() => setSubjects(SUBJECTS)}
  >
    Reset subjects
  </button>
</div>

Custom remove buttonCopy Anchor Link

removeLabel is the verb read before the label, so "Delete tag" gives "Delete tag Field trip". removeIcon replaces the X glyph. removeButtonClassName merges last into the button, so the app wins.

<Token
  color="blue"
  size="medium"
  removeLabel="Delete tag"
  removeIcon={<IconInterfaceEssentialTrashDeleteBin2 aria-hidden />}
  onRemove={() => {}}
>
  Field trip
</Token>
<Token
  color="pink"
  size="medium"
  removeButtonClassName="bg-color-background-pink"
  onRemove={() => {}}
>
  Music
</Token>

DisabledCopy Anchor Link

disabled drops the Token to 50% opacity. The remove button becomes a disabled native button and leaves the tab order.

<Token disabled>Archived</Token>
<Token disabled size="medium" color="red" onRemove={() => {}}>
  Locked filter
</Token>

Width and truncationCopy Anchor Link

The Token hugs its content up to the width of its container. The label truncates with an ellipsis when space runs out, and the slots and the remove button keep their size. className="w-full" fills the container.

<div className="flex w-spacing-160 flex-col items-start gap-spacing-8">
  <Token color="orange" onRemove={() => {}}>
    Grade 6 science fair project
  </Token>
  <Token color="gray" className="w-full">
    Fill width
  </Token>
</div>

AccessibilityCopy Anchor Link

• The Token is a plain span with no role. The remove button is the only control.
• The remove button's name is removeLabel (default "Remove") followed by the label, such as "Remove Design".
• When two Tokens can share a label, give each a removeLabel that tells them apart.
• Never put a link or a button in a slot or as the render target, because the Token already holds the remove button.
• The focus ring draws on the whole Token while the remove button has keyboard focus.
• The remove target is 20px, under the 24px WCAG 2.2 target size. Keep 4px or more between removable Tokens so the spacing exception applies.

APICopy Anchor Link

TokenCopy Anchor Link