HyChip

Usage examples on this page are written for Lit / plain HTML (<hy-chip>). The same component ships as HyChip in @whitespaceux/harmony-react (native React 19), with typed wrappers for Angular, Solid, Svelte, and Vue. The API reference below applies to all frameworks.

A compact, interactive element for displaying tags, filters, selections, or actions.

Chips are versatile UI elements that can represent inputs, attributes, or actions. Unlike badges (which are non-interactive status indicators), chips support user interaction including clicking, selecting, and removing.

Key Features

• Multiple semantic variants (neutral, brand, success, warning, danger, info)
• Optional remove button for dismissible chips
• Selectable state for filter/toggle scenarios
• Link mode when href is provided
• Icon and avatar support via prefix/suffix slots
• Full keyboard navigation (Enter, Space, Backspace, Delete)
• SSR compatible

Accessibility Features

• Proper ARIA roles and states
• Keyboard navigation with focus indicators
• Screen reader announcements
• High contrast mode support
• Reduced motion support

Examples

Basic Chip

<hy-chip>Label</hy-chip>

With Icon

<hy-chip icon="favorite-border">Favorites</hy-chip>

Removable Chip

<hy-chip removable>Removable</hy-chip>

Selectable Chip

<hy-chip selected>Selected</hy-chip>

Link Chip

<hy-chip href="/category/design">Design</hy-chip>

Variants

<hy-chip variant="neutral">Neutral</hy-chip>
<hy-chip variant="brand">Brand</hy-chip>
<hy-chip variant="success">Success</hy-chip>
<hy-chip variant="warning">Warning</hy-chip>
<hy-chip variant="danger">Danger</hy-chip>

Categorical / Identity tag

<!-- Hash an identity string to a stable slot in a named group. -->
<hy-chip category-group="team" identity="user-alice">Alice</hy-chip>
<!-- Explicit slot beats identity. -->
<hy-chip category-group="team" slot-index="3">Frontend</hy-chip>
<!-- A non-neutral variant wins — categorical is ignored. -->
<hy-chip variant="brand" category-group="team" slot-index="3">Brand (categorical skipped)</hy-chip>

Event Handling

const chip = document.querySelector('hy-chip[removable]');

chip.addEventListener('remove', (event) => {
console.log('Chip removed:', event.detail.chip);
event.detail.chip.remove(); // Remove from DOM
});

chip.addEventListener('select', (event) => {
console.log('Selection changed:', event.detail.selected);
});

API

Properties

Property	Attribute	Type	Default	Description
variant	variant	'neutral' | 'brand' | 'success' | 'warning' | 'danger' | 'info'	'neutral'	Visual style variant determining the chip's color scheme and semantic meaning.
emphasis	emphasis	'solid' | 'soft' | 'outlined' | 'tinted'	'soft'	Visual chrome weight on top of the role.
size	size	'small' | 'medium' | 'large'	'medium'	Physical size of the chip affecting dimensions, padding, and typography.
interactive	interactive	boolean	true	Whether the chip is interactive (clickable, focusable, and responds to keyboard). When false, the chip renders as a static display element without button semantics, making it suitable for tags or labels that don't require user interaction.
removable	removable	boolean	false	Shows a remove button that allows the user to dismiss the chip. When clicked, fires the remove event. The chip can also be removed by pressing Backspace or Delete when focused.
disabled	disabled	boolean	false	Disables the chip, preventing interaction and applying disabled styling. Disabled chips cannot be clicked, selected, or removed.
selected	selected	boolean	false	Indicates whether the chip is in a selected state. Useful for filter chips, toggle chips, or multi-select scenarios. Clicking a selectable chip toggles this state and fires select.
href	href	string | undefined	—	When set, renders the chip as an <a> tag with this href. The chip will navigate to the specified URL when clicked.
target	target	'_blank' | '_parent' | '_self' | '_top'	—	Specifies where to open the linked document. Only used when href is set. When set to _blank, automatically adds rel="noreferrer noopener" for security.
removeLabel	remove-label	string | undefined	—	Custom label for the remove button used by assistive technologies. If not provided, defaults to "Remove {chip text content}" for better context.
icon	icon	string | undefined	—	Name of the icon to display before the label. When set, renders an hy-icon in the shadow DOM instead of using the prefix slot.
categoryGroup	category-group	string | undefined	—	Categorical group name to hash into. Only applied when variant is neutral; a non-neutral variant wins. Selects which palette in the active DS's roles.categorical map this chip pulls from.
identity	identity	string | undefined	—	Identity string hashed to a stable slot within categoryGroup — same identity always produces the same color. Ignored when slotIndex is set.
slotIndex	slot-index	number | undefined	—	Explicit 1-indexed slot within categoryGroup. Takes precedence over identity. Out-of-range values fall back to default styling.

Events

Event	Detail	Description
activate	—	Fired when chip is clicked. Detail: { originalEvent: MouseEvent | KeyboardEvent }
remove	—	Fired when remove button is clicked or Backspace/Delete pressed. Detail: { chip: HyChip, originalEvent: MouseEvent | KeyboardEvent }
select	—	Fired when chip selection state changes. Detail: { selected: boolean, originalEvent: MouseEvent | KeyboardEvent }

Slots

Slot	Description
default	The chip's label text
prefix	Content before the label (icon, avatar)
suffix	Content after the label, before remove button (icon, count)
remove-icon	Custom remove icon (overrides the default close icon; only rendered when removable)

CSS Parts

Part	Description
base	The chip's base wrapper element
label	The default slot containing chip text
remove-button	The remove button element (when removable)

CSS Custom Properties

Property	Description
--hy-chip-gap	Gap between elements
--hy-chip-height-sm	Height at small size
--hy-chip-height-md	Height at medium size
--hy-chip-height-lg	Height at large size
--hy-chip-padding-inline-sm	Horizontal padding at small size
--hy-chip-padding-inline-md	Horizontal padding at medium size
--hy-chip-padding-inline-lg	Horizontal padding at large size
--hy-chip-radius	Border radius
--hy-chip-stroke	Border width
--hy-chip-opacity-disabled	Opacity when disabled
--hy-chip-remove-opacity	Opacity of the remove button
--hy-chip-text-transform	Text transform for chip label
--hy-chip-font-family	Font family override for chip label
--hy-chip-foreground-on-inverse-surface	Text color for neutral selected chips Default: var(--hy-background-surface-base)
--hy-chip-hover-duration	Transition duration for hover and focus state feedback
--hy-chip-hover-easing	Transition easing for hover and focus state feedback

Methods

focus()

Sets focus on the chip.

blur()

Removes focus from the chip.