ChipGroup

Tier: client

ImportCopy Anchor Link

import { Chip, ChipGroup } from '@nizivo/react/chip-group';

// Once per app (Getting started), after
// @nizivo/tokens/tokens.css and @nizivo/react/css/base.css
import '@nizivo/react/css/chip-group.css';

Static or interactiveCopy Anchor Link

Client. It always ships its client leaf, which wires it to a Field. The server HTML is native radios or checkboxes, so arrows, Space and submission work before hydration. How to choose.

In a client app (a Vite or React Router single-page app, or a 'use client' file) it is an ordinary React component: event handlers, refs and state work as usual. In a client app.

One value or severalCopy Anchor Link

By default the chips are radios under role="radiogroup": value and defaultValue are strings and onValueChange receives the checked value. With multiple they are checkboxes under role="group": value and defaultValue are arrays, onValueChange receives every checked value in document order, and the form submits one entry per checked chip (formData.getAll(name)). required applies to one value only: on checkboxes the browser would require every one.

SwatchesCopy Anchor Link

A product colour is data, not a token. Pass an element with that background in leading, such as <span style={{ background: '#2e5a3c' }} />, or an image; it fills a 24 px circle with a thin inner ring, so white and cream stay visible. A chip with a swatch and no text needs an aria-label.

Unavailable or disabledCopy Anchor Link

unavailable (out of stock) keeps the swatch's colour, draws a diagonal strike and describes the chip as labels.unavailable ("Unavailable"; pass labels={{ unavailable: 'Sold out' }} on the group). It can still be chosen, so a shopper can pick a sold-out size and be offered "Notify me"; add disabled to stop that. disabled greys the chip out and takes it out of the keyboard order, as a native disabled input.

No size jumpCopy Anchor Link

The edge is an inset ring, not a border: selecting turns it into a 2 px brand ring in the same box, so a chip never grows on select (Figma's grew from 90 × 40 to 92 × 42).

ExamplesCopy Anchor Link

import type { JSX } from 'react';
import { Field } from '@nizivo/react/field';
import { Chip, ChipGroup } from '@nizivo/react/chip-group';

/** A product colour is data: the swatch is any element with that background. */
function Swatch({ color }: { color: string }): JSX.Element {
  return <span style={{ background: color }} />;
}

export function ChipGroupExample(): JSX.Element {
  return (
    <Field label="Colour" name="color" group>
      <ChipGroup defaultValue="moss" labels={{ unavailable: 'Sold out' }}>
        <Chip value="moss" leading={<Swatch color="#2e5a3c" />}>
          Moss
        </Chip>
        <Chip value="clay" leading={<Swatch color="#b5643c" />}>
          Clay
        </Chip>
        <Chip value="sand" leading={<Swatch color="#e9dcc3" />} unavailable>
          Sand
        </Chip>
        <Chip value="slate" leading={<Swatch color="#4a5560" />}>
          Slate
        </Chip>
      </ChipGroup>
    </Field>
  );
}

import type { JSX } from 'react';
import { Field } from '@nizivo/react/field';
import { Chip, ChipGroup } from '@nizivo/react/chip-group';

export function ChipGroupSizesExample(): JSX.Element {
  return (
    <Field label="Size" name="size" group required>
      <ChipGroup defaultValue="m" labels={{ unavailable: 'Sold out' }}>
        <Chip value="xs" unavailable>
          XS
        </Chip>
        <Chip value="s">S</Chip>
        <Chip value="m">M</Chip>
        <Chip value="l">L</Chip>
        <Chip value="xl" disabled>
          XL
        </Chip>
      </ChipGroup>
    </Field>
  );
}

import type { JSX } from 'react';
import { Stack } from '@nizivo/react/stack';
import { Chip, ChipGroup } from '@nizivo/react/chip-group';

/** A product colour is data: the swatch is any element with that background. */
function Swatch({ color }: { color: string }): JSX.Element {
  return <span style={{ background: color }} />;
}

export function ChipGroupMultipleExample(): JSX.Element {
  return (
    <Stack gap="4">
      <ChipGroup aria-label="Order status" name="status" multiple defaultValue={['paid', 'open']}>
        <Chip value="open">Open</Chip>
        <Chip value="paid">Paid</Chip>
        <Chip value="refunded">Refunded</Chip>
        <Chip value="archived">Archived</Chip>
      </ChipGroup>
      <ChipGroup aria-label="Glaze" name="glaze" defaultValue="white">
        <Chip value="white" leading={<Swatch color="#ffffff" />} aria-label="White" />
        <Chip value="black" leading={<Swatch color="#1d1d1b" />} aria-label="Black" />
        <Chip value="celadon" leading={<Swatch color="#a7c4a0" />} aria-label="Celadon" />
      </ChipGroup>
    </Stack>
  );
}

import type { JSX } from 'react';
import { Field } from '@nizivo/react/field';
import { Chip, ChipGroup } from '@nizivo/react/chip-group';

export function ChipGroupErrorExample(): JSX.Element {
  return (
    <Field label="Fit" name="fit" group required error="Choose a fit.">
      <ChipGroup>
        <Chip value="regular">Regular</Chip>
        <Chip value="relaxed">Relaxed</Chip>
        <Chip value="slim">Slim</Chip>
      </ChipGroup>
    </Field>
  );
}

PropsCopy Anchor Link

Other exportsCopy Anchor Link

ChipGroupChangeReason type

import type { ChipGroupChangeReason } from '@nizivo/react/chip-group'

Why the value changed: the user checked or cleared an input (a pointer or a key).

type ChipGroupChangeReason = "input"

ChipGroupLabels type

import type { ChipGroupLabels } from '@nizivo/react/chip-group'

ChipGroup's own strings (§16.4): serialisable, English defaults.

Name	Type	Default	Description
unavailablerequired	string	'Unavailable'	Describes an unavailable chip (out of stock), read after its name; the strike-through is only visual.

ChipGroupProps type

import type { ChipGroupProps } from '@nizivo/react/chip-group'

M is true when multiple is: TypeScript infers it from the prop, so value, defaultValue and onValueChange take arrays exactly when the chips are checkboxes.

The props of ChipGroup, listed above.

ChipGroupState type

import type { ChipGroupState } from '@nizivo/react/chip-group'

The render state of ChipGroup, listed above.

ChipGroupValue type

import type { ChipGroupValue } from '@nizivo/react/chip-group'

What onValueChange receives: the checked value, or with multiple every checked value.

type ChipGroupValue<M extends boolean> = M extends true ? string[] : string

ChipProps type

import type { ChipProps } from '@nizivo/react/chip-group'

The props of Chip, listed above.

ChipState type

import type { ChipState } from '@nizivo/react/chip-group'

The render state of Chip, listed above.

Data attributes and slotsCopy Anchor Link

Style parts by class (.nz-<slot>) and state by data attribute. Attribute meanings come from contracts/vocabulary.json.

CSS hooksCopy Anchor Link

Set a hook on the component's class or any ancestor to restyle it without specificity games; leave it unset for the default shown.

Layers: nz.components. Classes: .nz-chip, .nz-chip-group, .nz-chip-input, .nz-chip-label, .nz-chip-leading, .nz-chip-strike.

AccessibilityCopy Anchor Link

These parts are interactive. Each gets the focus outline and touch-action rule from @nizivo/react/css/base.css (the nz.base layer), so the floor survives a restyle:

• chip: draws the outline when the hidden input inside it has keyboard focus.

In forced-colours mode these states keep a visible system colour: chip (border), chip:has(> input:checked) (outline).

Pattern: WAI-ARIA Authoring Practices.

KeyboardCopy Anchor Link

Source: native <input type="radio"> or <input type="checkbox"> elements inside <label>s (chip-group.client.tsx); its only key handler marks the chip data-focus-visible, because WebKit matches no :focus-visible on a radio reached by an arrow key. The browser lane (test/browser/chip-group.spec.tsx) checks Tab entry, arrows, Space, skipping a disabled chip and reaching an unavailable one.

FigmaCopy Anchor Link

Node ids from design/component-map.json, which nz gen writes from component.json. The links open the Nizivo Figma library, which may ask you to sign in.

• Canonical: Figma node 7275:14018
• Ghost masters: Figma node 753:405