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.

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.

Basic Usage

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

```html
* <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>

Custom Content

<hy-list-item value="custom-content">
  <div>
    <h4>Custom Content</h4>
    <p>You can use custom HTML when not setting primary/secondary text.</p>
  </div>
</hy-list-item>

With Leading and Trailing Content

<hy-list-item primary-text="Item with Icons" secondary-text="Leading and trailing content">
  <img
    slot="leading"
    src="avatar.jpg"
    alt="User"
    style="width: 20px; height: 20px; border-radius: 50%;"
  />
  <hy-icon slot="trailing" name="chevron-right"></hy-icon>
</hy-list-item>

CSS Customization

### Theming via CSS custom properties

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

Accessibility Features

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

### ARIA Attributes

```html
<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). |
| `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). Detail contains `{checked: boolean, indeterminate: boolean, state: CheckboxState, value: string, reason: string}` |

### Slots

| Slot | Description |
| --- | --- |
| `default` | Custom content to display when not using primary-text/secondary-text |
| `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

| Property | Description |
| --- | --- |
| `--hy-list-item-background-rest` | Background color at rest |
| `--hy-list-item-gap` | Gap between leading/content/trailing sections |
| `--hy-list-item-padding-size-sm-block` | Block padding for small size |
| `--hy-list-item-padding-size-sm-inline` | Inline padding for small size |
| `--hy-list-item-padding-size-md` | Padding for medium size |
| `--hy-list-item-padding-size-lg-block` | Block padding for large size |
| `--hy-list-item-padding-size-lg-inline` | Inline padding for large size |
| `--hy-list-item-checkbox-accent` | Fill for an embedded checkbox. Names the CSS `accent-color` property it feeds, NOT the Harmony `accent` role — it defaults to `--hy-background-brand-rest`. Read only by the React mirror, whose native `input type=checkbox` is styled via `accent-color`; the Lit list-item slots an `hy-checkbox` that themes itself, so the hook is carried here for parity only. |

## 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.