Skip to content

Import#

import { Chip } from '@dnb/eufemia'

Description#

Chip is a compact, selectable option for filters, categories, and short choices. The component name is singular because each instance represents one chip.

Chips for filters and choices#

Use Chip.Group to manage related choices, their label, and shared name. The group selects one option by default using value. Set selectionMode="multiple" and use values when several options can be selected. Set a shared variant on the group to choose the appearance independently of the selection mode. The addable variant changes its icon between add and remove as the selection changes. It keeps the chip visible so the user can select it again.

Use Tag for compact labels or removable values, Badge for counts and statuses, and Button for actions.

Toggle buttons#

Use Chip like a toggle button to select or deselect an option. Use Chip.Group for mutually exclusive choices, or set selectionMode="multiple" to allow several selections. Use Chip for new implementations instead of ToggleButton, which is deprecated.

When moving from ToggleButton, keep checked, value, values, variant, size, and layoutDirection. Check these differences:

FeatureChip
LabelsUse text or children for the option name. Move an external ToggleButton label to Chip.Group. labelSrOnly on Chip hides the option name; on Chip.Group it hides the group label.
Selection modeReplace multiselect with selectionMode="multiple". Single selection is the default (selectionMode="single").
Initial selectionSet value on a single selection group, or values with selectionMode="multiple". A nested Chip's checked does not initialize its group. Use checked for standalone chips.
Change eventsChip returns { checked, value, event }. Chip.Group also returns values containing all selected options, including in single selection mode. value identifies the changed option. The ref and event.currentTarget refer to the native input or addable toggle button.
ValuesStrings and numbers preserve their type in change events. Use matching types for group and option values, and keep values unique after conversion to strings. Map objects and arrays to stable identifiers. Native form submission uses strings.
AppearanceChip.Group controls single or multiple selection independently of variant. Use icon for decorative content before the name and suffix for per-option help outside the pill.

Accessibility#

Give every chip a short name using text or children. text takes precedence over children. Prefer visible names. Use labelSrOnly with a recognizable icon when space is limited, and provide the hidden name in tooltip so it is available on hover and keyboard focus. Keep the content to text and decorative icons. Links, buttons, and other interactive elements must be outside the chip.

Chip uses native checkboxes and radio inputs. Addable chips use native toggle buttons with aria-pressed, except in single selection groups, which retain radio inputs. The name stays the same when selected; the add and remove icons are decorative. Assistive technology announces the selected or pressed state. Only selected, enabled chips participate in native form submission using their name and value.

Give Chip.Group a visible label. A single selection group uses native radio inputs. A multiple selection group uses native checkboxes, or toggle buttons for addable chips. Tab moves between checkboxes or toggle buttons and enters or leaves a radio group. Space or Enter selects an option; arrow keys move between radio options. Disabled options are skipped. Standalone chips use checkboxes, except for the radio and addable variants.

Use status for an error message that explains how to resolve the problem. readOnly preserves the selection while keeping the chip focusable. Read-only addable buttons expose aria-disabled to communicate that they cannot be changed. disabled removes the chip from keyboard navigation and form submission.

Relevant links#

Related components#

Chip is part of the Inputs category. More components in this category:

  • Autocomplete — to help people find and choose from matching suggestions as they type.
  • Checkbox — when people can turn one or more options on or off.
  • Date picker — when people need to choose one date or a date range.
  • Dropdown — when people need to choose one option from a list.
  • Filter — to help people narrow down a list or data set.
  • Input — when people need to enter a short line of text.

See all in Inputs →

Demos#

Multiple selection#

Keep selected values in state when they are used to filter content. Every option remains available after selection.

Account filters

Selected: savings

const Example = () => {
  const [values, setValues] = useState<ChipValue[]>(['savings'])
  return (
    <Flex.Stack>
      <Chip.Group
        selectionMode="multiple"
        label="Account filters"
        name="filters"
        values={values}
        onChange={({ values }) => setValues(values)}
      >
        {['savings', 'funds', 'loans'].map((value) => (
          <Chip key={value} value={value}>
            {value === 'savings'
              ? 'Savings'
              : value === 'funds'
              ? 'Funds'
              : 'Loans'}
          </Chip>
        ))}
      </Chip.Group>
      <P>Selected: {values.join(', ') || 'None'}</P>
    </Flex.Stack>
  )
}
render(<Example />)

Single selection#

Use Chip.Group to label and manage mutually exclusive choices. Set variant="radio" on the group to show radio indicators, or use the default appearance. Give each chip a unique value.

Account type
<Chip.Group
  label="Account type"
  name="account"
  variant="radio"
  value="savings"
  onChange={({ value }) => console.log(value)}
>
  <Chip value="savings">Savings</Chip>
  <Chip value="funds">Funds</Chip>
  <Chip value="loans" disabled>
    Loans
  </Chip>
  <Chip value="all">All accounts</Chip>
</Chip.Group>

Variants and icons#

Choose the visual cue that fits the task. In Chip.Group, the selection mode is controlled by selectionMode, independently of the appearance.

<Flex.Container gap="x-small" role="group" aria-label="Chip variants">
  <Chip>Default</Chip>
  <Chip variant="addable">Add or remove</Chip>
  <Chip variant="checkbox">Checkbox</Chip>
  <Chip icon={savings_account}>Savings</Chip>
</Flex.Container>

Flags and logos#

Use icon for a CountryFlag or an Avatar with a logo. Keep the image decorative and give the chip a visible text label. The DNB logo in the Figma design is a circular avatar, shown here at 16 × 16 pixels.

<Flex.Stack>
  {[false, true].map((checked) => (
    <Flex.Container key={String(checked)} gap="x-small">
      <Chip checked={checked} icon={<CountryFlag iso="US" size="small" />}>
        United States
      </Chip>
      <Chip
        variant="addable"
        checked={checked}
        icon={
          <Avatar
            src="/images/avatars/dnb.svg"
            alt=""
            hasLabel
            style={{
              width: '1rem',
              height: '1rem',
            }}
          />
        }
      >
        DNB
      </Chip>
      <Chip
        variant="checkbox"
        checked={checked}
        icon={<CountryFlag iso="NO" size="small" />}
      >
        Norway
      </Chip>
      <Chip
        variant="radio"
        checked={checked}
        icon={
          <Avatar
            src="/images/avatars/dnb.svg"
            alt=""
            hasLabel
            style={{
              width: '1rem',
              height: '1rem',
            }}
          />
        }
      >
        DNB
      </Chip>
    </Flex.Container>
  ))}
</Flex.Stack>

Group labels, layout, and status#

Share selection state and a label with Chip.Group. Use layoutDirection="column" to stack the options, suffix for guidance, and status for a group message.

View
Notifications
Choose all that apply
Choose at least two channels
Account (read only)
<Flex.Stack>
  <Chip.Group label="View" value="overview">
    <Chip value="overview">Overview</Chip>
    <Chip value="details">Details</Chip>
  </Chip.Group>
  <Chip.Group
    selectionMode="multiple"
    variant="checkbox"
    label="Notifications"
    values={['email']}
    layoutDirection="column"
    suffix="Choose all that apply"
    status="Choose at least two channels"
  >
    <Chip value="email">Email</Chip>
    <Chip value="sms">SMS</Chip>
  </Chip.Group>
  <Chip.Group
    label="Account (read only)"
    variant="radio"
    value="savings"
    readOnly
  >
    <Chip value="savings">Savings</Chip>
    <Chip value="funds">Funds</Chip>
  </Chip.Group>
</Flex.Stack>

Sizes#

Available sizes: small, medium, default, and large. Set size on Chip.Group for all options, or on an individual Chip to override it.

small
medium
default
large
Individual size override
<Flex.Stack>
  {(['small', 'medium', 'default', 'large'] as const).map((size) => (
    <Chip.Group
      key={size}
      label={size}
      size={size}
      selectionMode="multiple"
      values={['checkbox', 'radio']}
    >
      <Chip value="default">Default</Chip>
      <Chip value="addable" variant="addable">
        Addable
      </Chip>
      <Chip value="checkbox" variant="checkbox">
        Checkbox
      </Chip>
      <Chip value="radio" variant="radio">
        Radio
      </Chip>
    </Chip.Group>
  ))}
  <Chip.Group label="Individual size override" size="large">
    <Chip value="inherited">Inherited</Chip>
    <Chip value="override" size="small">
      Small
    </Chip>
  </Chip.Group>
</Flex.Stack>

Per-option help#

Use suffix for guidance or a HelpButton beside an option. It stays outside the clickable pill, so opening help does not change the selection. Values can be strings or numbers; the numeric values in this example stay numeric in change events.

Account
Filters
<Flex.Stack>
  <Chip.Group label="Account" value={0} variant="radio">
    <Chip
      value={0}
      suffix={
        <HelpButton size="small" title="About savings">
          Savings accounts earn interest on your balance.
        </HelpButton>
      }
    >
      Savings
    </Chip>
    <Chip
      value={1}
      suffix={
        <HelpButton size="small" title="About funds">
          Funds let you invest for the long term.
        </HelpButton>
      }
    >
      Funds
    </Chip>
  </Chip.Group>
  <Chip.Group label="Filters" selectionMode="multiple" variant="checkbox">
    <Chip
      value="active"
      suffix={
        <HelpButton size="small" title="About active accounts">
          Show accounts that are currently in use.
        </HelpButton>
      }
    >
      Active accounts
    </Chip>
  </Chip.Group>
</Flex.Stack>

Tooltips and hidden labels#

Use tooltip for extra context. With labelSrOnly, the name is available to screen readers while the icon and selection indicator stay visible. Use a recognizable icon and repeat the hidden name in the tooltip so it is available on hover and keyboard focus.

<Flex.Container gap="x-small" role="group" aria-label="Chip tooltips">
  <Chip tooltip="Show accounts that earn interest">Savings</Chip>
  <Chip icon={savings_account} labelSrOnly tooltip="Savings accounts">
    Savings accounts
  </Chip>
  <Chip variant="radio" icon={bell} labelSrOnly tooltip="Notifications">
    Notifications
  </Chip>
</Flex.Container>

Error messages#

Accounts
Select at least two accounts
Period
Choose another period
<Flex.Stack>
  <Chip.Group
    label="Accounts"
    variant="checkbox"
    selectionMode="multiple"
    values={['savings']}
    status="Select at least two accounts"
  >
    <Chip value="savings">Savings</Chip>
    <Chip value="funds">Funds</Chip>
  </Chip.Group>
  <Chip.Group
    label="Period"
    variant="radio"
    value="month"
    status="Choose another period"
  >
    <Chip value="month">Month</Chip>
    <Chip value="year">Year</Chip>
  </Chip.Group>
</Flex.Stack>

Dark surface#

<Section surface="dark" innerSpace>
  <Flex.Container gap="x-small">
    <Chip>Default</Chip>
    <Chip variant="addable" checked>
      Selected
    </Chip>
    <Chip variant="checkbox" checked>
      Checkbox
    </Chip>
    <Chip variant="radio" checked>
      Radio
    </Chip>
    <Chip disabled>Disabled</Chip>
    <Chip variant="checkbox" disabled checked>
      Disabled selected
    </Chip>
  </Flex.Container>
</Section>

Skeleton#

<Flex.Container gap="x-small">
  <Chip skeleton>Loading option</Chip>
  <Chip variant="checkbox" skeleton>
    Loading option
  </Chip>
  <Chip variant="radio" skeleton>
    Loading option
  </Chip>
</Flex.Container>

Selected, disabled, and read-only states#

Group appearances#

Each appearance supports both single and multiple selection. Shared disabled, readOnly, and skeleton properties can also be set on the group.

default: single
default: multiple
addable: single
addable: multiple
checkbox: single
checkbox: multiple
radio: single
radio: multiple

Long labels#

Keep labels short where possible. Longer text wraps within the available width.

<Flex.Container gap="x-small">
  <Chip variant="checkbox">
    A longer option that wraps when space is limited
  </Chip>
  <Chip variant="radio">
    AnExtremelyLongUnbrokenLabelThatStillNeedsToFitOnASmallScreen
  </Chip>
</Flex.Container>
Suggest an edit
Eufemia · /web/components/chip/ · Version 11.18.0