HyListItem

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

### Styling with CSS Parts

```css
// Style the base wrapper
hy-list-item::part(base) {
border-radius: 8px;
}

// Style the interactive element (button or link)
hy-list-item::part(interactive) {
padding: 16px;
}

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>

## Events

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

- **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)

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