HyList

Usage examples on this page are written for Lit / plain HTML (<hy-list>). The same component ships as HyList 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 vertical list of items for display, navigation, or selection.

When to Use This Component

Use hy-list for:

• Displaying lists of items, options, or content
• Navigation menus and listboxes with selectable options
• Settings panels with multiple choices

Don't use this for:

• Action menus, value pickers, or any overlay-triggered selection → Use <hy-menu-button> with <hy-menu-item> / <hy-menu-item-radio> / <hy-menu-item-checkbox> instead.
• Simple form inputs → Use <hy-select> instead.

Size Variants

• small: Compact design with body-sm typography
• medium: Default size with body-md typography (default)
• large: Prominent design with body-lg typography

Role Behavior

The list automatically sets the appropriate role on child list-items based on its own role:

• role="listbox" → child items get role="option"
• role="menu" → child items get role="menuitem"
• role="list" → child items get role="listitem"

Examples

Basic List

<hy-list>
  <hy-list-item value="1" primary-text="Item 1"></hy-list-item>
  <hy-list-item value="2" primary-text="Item 2"></hy-list-item>
</hy-list>

API

Properties

Property	Attribute	Type	Default	Description
ariaLabel	aria-label	string	—	Accessible label for the list
ariaLabelledBy	aria-labelledby	string | undefined	—	ID of element that labels the list
ariaDescribedby	aria-describedby	string | undefined	—	ID of element that describes the list
role	role	'list' | 'listbox' | 'menu' | 'group'	'list'	ARIA role for the list (list, listbox, menu, or group)
selectionMode	selection-mode	'none' | 'single' | 'multiple'	'none'	Selection mode: none, single, or multiple
size	size	'small' | 'medium' | 'large'	'medium'	Size variant for list items
disabled	disabled	boolean	false	Disables the entire list
required	required	boolean	false	Marks the list as required for form validation
dense	dense	boolean	false	Enables dense/compact spacing
bordered	bordered	boolean	false	Shows border around the list
selectedValues	selected-values	string[]	[]	Array of currently selected item values
listId	list-id	string	''	ID for the list element. Defaults to auto-generated ID.

Events

Event	Detail	Description
selection-change	—	Fired when selection changes

Slots

Slot	Description
default	The list's items (hy-list-item elements)

CSS Parts

Part	Description
base	The list's base <ul> element