HyListItem

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

Used inside <hy-list> — it only means something as part of it.

A flexible list item component designed to work within list containers. Supports text content, checkboxes, links, leading/trailing icons, and comprehensive accessibility features. Can function as a simple display item, interactive button, or navigational link.

When not to use

• A single row on its own, outside a list: hy-card or plain markup.
• Commands in a popup: hy-menu-item inside hy-menu-button.

Accessibility: built in

This component includes comprehensive accessibility support:

• Keyboard Navigation: Full keyboard support with Enter/Space activation
• Screen Readers: Proper ARIA labels, roles, and states
• Focus Management: Visible focus indicators with :focus-visible that only appear during keyboard navigation (not mouse clicks)
• Dark Mode: Inherits the design system's dark theme via semantic color tokens (data-semantic-color)
• High Contrast: Enhanced visibility in high contrast mode
• Reduced Motion: Respects prefers-reduced-motion for animations
• Disabled States: Proper disabled state handling with aria-disabled
• Checkbox States: Full support for checked, unchecked, and indeterminate states

Examples

Simple List Item

<hy-list-item primary-text="Basic List Item"></hy-list-item>

List Item with Checkbox

<hy-list-item
  primary-text="Task Item"
  secondary-text="Click to mark as complete"
  has-checkbox
  value="task1"
>
</hy-list-item>

List Item as Link

<hy-list-item
  href="/profile"
  primary-text="User Profile"
  secondary-text="View and edit your profile"
>
  <hy-icon slot="leading" name="user"></hy-icon>
  <hy-icon slot="trailing" name="chevron-right"></hy-icon>
</hy-list-item>

Size Variants

<hy-list-item primary-text="Small Item" size="small"></hy-list-item>

<hy-list-item primary-text="Medium Item" size="medium"></hy-list-item>

<hy-list-item primary-text="Large Item" size="large"></hy-list-item>

Selected and Disabled States

<hy-list-item primary-text="Selected Item" selected></hy-list-item>

<hy-list-item primary-text="Disabled Item" secondary-text="This item cannot be selected" disabled>
</hy-list-item>

With Leading and Trailing Content

<hy-list-item primary-text="Item with Icons" secondary-text="Leading and trailing content">
  <hy-avatar slot="leading" size="xs" src="avatar.jpg" alt="Jane Doe"></hy-avatar>
  <hy-icon slot="trailing" name="chevron-right"></hy-icon>
</hy-list-item>

CSS Customization

The component can be customized using CSS custom properties:

Theming via CSS custom properties

hy-list-item {
  --hy-list-item-gap-row-list-md-inline: var(--hy-gap-row-list-sm-inline);
  --hy-list-item-interactive-padding-row-list-md-block: var(--hy-padding-row-list-lg-block);
}

ARIA Attributes

<hy-list-item
  primary-text="Accessible Item"
  aria-label="Custom accessible label"
  aria-describedby="description-id"
  role="option"
>
</hy-list-item>

API

Properties

Property	Attribute	Type	Default	Description
primaryText	primary-text	string	''	The main text content displayed prominently in the list item.
secondaryText	secondary-text	string	''	Secondary text displayed below the primary text for additional context.
selected	selected	boolean	false	Whether the list item is currently selected.
disabled	disabled	boolean	false	Disables the list item, preventing interaction.
hasCheckbox	has-checkbox	boolean	false	Whether the list item includes a checkbox for selection.
checked	checked	boolean	false	Whether the checkbox is checked (checkbox items only).
indeterminate	indeterminate	boolean	false	Whether the checkbox is in an indeterminate state (checkbox items only).
value	value	string	—	The value associated with this list item, used for selection tracking.
href	href	string | undefined	—	When set, renders the list item as a link with this URL.
target	target	string | undefined	—	Target for the link (e.g., '_blank', '_self'). Only used when href is set.
ariaLabel	aria-label	string | null	—	Accessible label for the list item, read by screen readers.
ariaDescribedby	aria-describedby	string | undefined	—	ID of element that describes the list item for accessibility.
role	role	string | null	—	The semantic role of the list item (typically set by parent list). Rendered on the inner <li> only: a role attribute on the host is read into this property and taken off the host, so the tree meets one item.
size	size	'small' | 'medium' | 'large'	'medium'	The size variant of the list item. - 'small': Compact size with smaller text (uses hy-body-sm) - 'medium': Default size (uses hy-body-md) - 'large': Larger size with more prominent text (uses hy-body-lg)
active	active	boolean	false	Whether this item currently owns the tab stop in its list's roving tabindex (i.e. the parent list's keyboard focus rests here). Reflected so the modal focus trap can match hy-list-item[active]. Managed by the parent hy-list — do not set manually.

Events

Event	Detail	Description
action	—	Fired when the list item is clicked or activated. Detail contains {item: HyListItem, originalEvent: Event}
change	—	Fired when the checkbox state changes (checkbox items only; not in a selection-mode="single" list, where the checkbox only shows the row's selection). Detail contains {checked: boolean, indeterminate: boolean, state: CheckboxState, value: string, reason: string}

Slots

Slot	Description
leading	Content to display before the main text (e.g., icons, avatars, images). When has-checkbox is true, the checkbox appears here.
trailing	Content to display after the main text (e.g., icons, badges, chevrons)

CSS Parts

Part	Description
base	The list item's base wrapper element (li element)
interactive	The interactive button or link element that receives user interaction

CSS Custom Properties

The documented hooks. Every override hook the component reads — one per token it paints — is listed in @whitespaceux/harmony/theme-api.json, and @whitespaceux/harmony/component-bindings.json (the Harmony MCP get-bindings tool) says which part and state each one paints.

Property	Default	Description
--hy-list-item-background-surface-base	var(--hy-background-surface-base)	Background color at rest
--hy-list-item-gap-row-list-md-inline	var(--hy-gap-row-list-md-inline)	Gap between leading/content/trailing sections
--hy-list-item-padding-row-list-sm-block	var(--hy-padding-row-list-sm-block)	Block padding for small size
--hy-list-item-padding-row-list-sm-inline	var(--hy-padding-row-list-sm-inline)	Inline padding for small size
--hy-list-item-interactive-padding-row-list-md-block	var(--hy-padding-row-list-md-block)	Block padding for medium size
--hy-list-item-padding-row-list-md-inline	var(--hy-padding-row-list-md-inline)	Inline padding for medium size
--hy-list-item-interactive-padding-row-list-lg-block	var(--hy-padding-row-list-lg-block)	Block padding for large size
--hy-list-item-padding-row-list-lg-inline	var(--hy-padding-row-list-lg-inline)	Inline padding for large size
--hy-list-item-background-brand-on-rest	var(--hy-background-brand-on-rest)	Checked / indeterminate fill of the embedded checkbox (has-checkbox) — the on token a checked box reads (C6). Re-points the embedded hy-checkbox's --hy-checkbox-background-brand-on-rest; the React mirror feeds the native checkbox's accent-color.

Methods

setTabIndex()

Sets tabindex on the interactive inner element AND mirrors the tab-stop state to the host's reflected [active] attribute so the focus trap (and CSS) can see which item is the current tab stop. Called by the parent list's roving-tabindex logic.