# List A container that displays a collection of related items in a structured format. Lists help organize content clearly and improve readability by grouping similar elements together. Part of the Harmonia Alpine.js component library. Every directive uses the `x-h-` prefix. ## Usage Use lists to present multiple related items, such as options, tasks, or entries. Avoid using lists for grouping unrelated content. ## Behavior An item is a container rather than a control, so a list is made interactive by putting a real button or link inside the item with `x-h-list-item-button`. Everything about the interaction (`@click`, `href`, `aria-current` and `disabled`) belongs on that control. The control fills the row and takes the row's padding, so the area that responds to a click is the area that lights up. The item is what paints, which is why the highlight still spans the full width. A button placed beside the control, for an action on the row rather than the row itself, is an ordinary `x-h-button` and stays outside `x-h-list-item-button`. It gets its own hover and leaves the row alone, so the two never light up at once. Which row is the current one stays yours to manage. Bind `aria-current` on the control to mark it, since the list never changes it. Use `page` for a list of destinations and a bound boolean for a list you select from. ## Directives `x-h-list` is the root. The directives compose one component and must be nested as shown in the Examples below (the library throws at runtime when a required ancestor is missing): - `x-h-list` - `x-h-list-item` - `x-h-list-item-button` - `x-h-list-secondary` - `x-h-list-header` ## API ### Attributes #### x-h-list-item-button | Attribute | Type | Required | Description | | ------------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- | | aria-current | string | false | Marks the row as the current one, which highlights it. Use `page` in a list of destinations, or bind a boolean elsewhere. | | aria-disabled | boolean | false | Marks the control unavailable while keeping it focusable and announced. On a button, `disabled` removes it from the tab order instead. | ## Keyboard Handling The row control is a native button or link, so it behaves like one and the list adds nothing of its own. Each control is a separate tab stop and the arrow keys are not used. For a group that `Tab` enters once and the arrow keys move through, use the Listbox component instead. - `Tab` / `Shift+Tab` - Moves focus to the next or previous control, including any action button beside a row control. - `Enter` / `Space` - Activates the focused button. A link activates on `Enter`. ## Accessibility An item is always a list item, whether the list is interactive or not, so the list is announced as a list and with its item count. This is why the control goes inside the item rather than on it. An item that holds only an icon needs an `aria-label` on its control, naming the row rather than the icon. ## Examples ```html ``` ### Interactive with disabled items ```html ``` ### With secondary text ```html ``` ### Interactive with a row action ```html ``` ### As links ```html ``` ### With header ```html ``` ### With icons and buttons ```html ``` Full docs: https://www.codbex.com/harmonia/components/list.html ## Notes - Directive values are Alpine expressions, so quote string literals: `x-h-...="'Label'"`. - Components render only after Alpine has registered Harmonia. See SKILL.md for setup.