rc-chip-group

Adaptive wrapping and horizontal-scrolling layout for chip collections and arbitrary direct children.

Package

@rcarls/rc-chip-group

Element

<rc-chip-group>

Native dependency

Author-owned fieldset and radio/checkbox controls

State model

Auto overflow disclosure and optional assist roving focus

Main events

rc-chip-group-toggle

Related

Usage rulesrc-chiprc-toolbarTheme previews

Installation

npm

npm install @rcarls/rc-webcomponents@next

Yarn

yarn add @rcarls/rc-webcomponents@next

pnpm

pnpm add @rcarls/rc-webcomponents@next

import '@rcarls/rc-webcomponents/rc-chip-group/define';

The define entry also registers rc-chip, which the group uses for its internal Show all/Show less action.

Usage

Keep fieldset, legend, form value, and selection semantics native:

<fieldset>
  <legend>Recipe scope</legend>
  <rc-chip-group kind="filter" selection="single">
    <rc-chip>
      <label><input type="radio" name="scope" value="all" checked />All</label>
    </rc-chip>
    <rc-chip>
      <label><input type="radio" name="scope" value="favorites" />Favorites</label>
    </rc-chip>
  </rc-chip-group>
</fieldset>

Use selection="multiple" with checkboxes. Use selection="none" for menu-backed filter buttons with aria-haspopup; their menu owns the eventual selection.

Live demo

Accessibility

• kind="filter" keeps the native radios or checkboxes as the selection controls, so the author's fieldset and legend name the group and each input keeps its role, label, and checked state.
• kind="assist" gives the group role="toolbar" and an aria-label from label. It is a single tab stop: arrow keys along the row move between chips, wrapping, and Home and End move to the first and last chip. The arrow keys follow the inline direction, so Left and Right swap in right-to-left text.
• kind="generic" adds no role or keyboard behavior.

The Show all and Show less action is a native button whose name changes with the state, and its icon and separator are decorative.

Adaptive layout

layout="auto" is the default. The group first measures its natural wrapped layout. When the content needs more than max-rows="2", it becomes one horizontally scrolling row and inserts a leading Show all action. Expanded content returns to natural wrapping and the same action becomes Show less. The action uses the MDI tune icon and a vertical separator to distinguish the disclosure control from the authored chip collection.

Use layout="wrap" to always wrap or layout="scroll" to always keep one horizontal row. The component uses actual rendered rows, so container size, text scaling, localization, and consumer content all participate in the decision without device-pixel-ratio special cases.

Coordination modes

• kind="generic" is layout-only and accepts any direct HTMLElement.
• kind="assist" exposes a labeled toolbar with one tab stop and horizontal arrow/Home/End navigation.
• kind="filter" synchronizes native radio/checkbox state to direct rc-chip children. Put the group inside an author-owned fieldset.

Localization

Built-in text follows the element's own lang, else <html lang>. Override it with messages, or register it for every instance under rc-chip-group: label, showAll, showLess. See Localization.

API

Properties

Property	Markup	Type	Default	Description
messages	JS property only	Partial<RCChipGroupMessages> | undefined	Not specified	Built-in text overrides; unset keys fall back to registered text, then English.
layout	layout	RCChipGroupLayout	'auto'	Layout strategy.
maxRows	max-rows	number	2	Maximum natural rows before auto layout collapses to horizontal scrolling.
kind	kind	RCChipGroupKind	'generic'	Child coordination mode.
selection	selection	RCChipGroupSelection	'none'	Native filter selection hint.
label	label	string | undefined	Not specified	Accessible label used when `kind="assist"` exposes toolbar semantics. Defaults to the `label` message.
expanded	expanded	boolean	Not specified	Current auto-layout disclosure state. Host writes are silent.
defaultExpanded	default-expanded	boolean	Not specified	Initial uncontrolled disclosure state.

Events

Event	Detail type	Description
rc-chip-group-toggle	No detail type documented	Fired after the user activates Show all or Show less.

Slots

Name	Description
(default)	Direct chip or arbitrary-element children.

CSS Custom Properties

Property	Default	Description
--rc-chip-group-column-gap	0.5rem	Inline gap between items.
--rc-chip-group-row-gap	0	Block gap between wrapped rows. Slotted readonly chips keep `--rc-chip-touch-target-block-size` so every row shares the disclosure toggle's pitch.
--rc-chip-touch-target-block-size	3rem	Shared row pitch for readonly chips and the disclosure toggle.
--rc-chip-group-padding-block	0	Group block-axis padding.
--rc-chip-group-scroll-padding-inline	0	Horizontal scroll padding.
--rc-chip-group-scrollbar-width	none	Standards-based scrollbar width.
--rc-chip-group-scrollbar-display	none	WebKit scrollbar display.
--rc-chip-group-toggle-gap	0.5rem	Gap between the disclosure icon and label.
--rc-chip-group-toggle-separator-gap	0.5rem	Gap before the disclosure separator.
--rc-chip-group-toggle-icon-size	1.125rem	Disclosure icon size.
--rc-chip-group-toggle-separator-block-size	1.5rem	Separator block size.
--rc-chip-group-toggle-separator-inline-size	1px	Separator thickness.
--rc-chip-group-toggle-separator-color	currentColor	Separator color.

CSS Parts

Part	Description
root	Flex layout and horizontal scroll container.
toggle	Internal leading disclosure chip.
toggle-icon	MDI tune icon inside the disclosure chip.
toggle-separator	Vertical separator after the disclosure chip.