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.

Child components: <hy-list-item> — used only inside this one.

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

Size Variants

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

Every item takes the list's size, and follows it when it changes — except an item given a size of its own, which keeps it.

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"

Checkbox rows (has-checkbox)

• selection-mode="multiple": the checkbox toggles its row in and out of the selection (each item fires change, the list selection-change).
• selection-mode="single": the checkbox is the row's selection indicator. Clicking the row or its checkbox, or Enter / Space on it, selects that row and unchecks the rest — the same action and one selection-change a row without a checkbox fires; the item fires no change, and a second click on the checked row keeps it checked. Same contract as the React HyList.

When to use

• A column of similar items people scan, open or pick: messages, files, people.
• Selecting one or several items in place, with selection-mode.

Do

• Give every row the same structure: the same parts in the same places.
• Lead each row with the text people scan for.

When not to use

• Items nested under parents that open and close: hy-tree.
• Uneven entries with images and long text: a grid of hy-card.
• Multiple selection: set has-checkbox on each hy-list-item so the selection shows.
• Action menus, value pickers, or any selection that opens from a trigger: hy-menu-button with hy-menu-item, hy-menu-item-radio or hy-menu-item-checkbox.
• A simple form input: hy-select.
• Records compared column by column: hy-table, or hy-datagrid to filter, select or page through them.

Accessibility: your part

• With a selection-mode other than none, set role="listbox".
• Name the list with aria-label or aria-labelledby, always when it is a listbox.
• Give each row one interaction: a link or a selection, never both.

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). Rendered on the inner list element only: a role attribute on the host is read into this property and taken off the host, so the accessibility tree meets one list.
selectionMode	selection-mode	'none' | 'single' | 'multiple'	'none'	Selection mode: none, single, or multiple
size	size	'small' | 'medium' | 'large'	'medium'	Size variant for list items (an item's own size wins)
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

Methods

selectAll()

Selects every enabled item. Disabled items keep their selection, and a disabled selected item stays in the value (the shared select-all rule, internal/select-all.ts).

deselectAll()

Clears every enabled item. Disabled items keep their selection.