List
Accessible list component with support for navigation, selection, groups, subheaders, icons, avatars, single/multi-line items and keyboard traversal.
Structure
Anatomy
Visual breakdown of the component's internal structure with BEM class call-outs.
<origam-list> — 5 structural zones: root (①), ListItem (②), active item (③), ListGroup activator (④) and nested child item (⑤).- 1.origam-list
- Root element.
role="listbox". Manages keyboard navigation (arrow keys, Home, End) and focus tracking. - 2.origam-list-item
- Individual row. 3-column grid: prepend | content (title + subtitle) | append. Clickable when link or value is set.
- 3.origam-list-item--active
- Active state modifier. Applied when the item value matches the list selection or when active=true.
- 4.origam-list-group
- Collapsible group wrapper. The activator header toggles the open state; nested children indent via CSS var.
- 5.origam-list-item (nested)
- Child item inside a ListGroup. Inherits indent via
--origam-list---indent-paddingCSS variable.
API
Props
All props accepted by this component, with their type, default value and description.
- activeClassstring
- Extra CSS class injected on the active ListItem.
- disabledbooleanfalse
- Disables all interaction (pointer-events: none; user-select: none).
- expandIconstring
- Icon used to indicate an expandable group (overrides ListGroup default).
- collapseIconstring
- Icon used to indicate a collapsed group (overrides ListGroup default).
- Controls item min-height and subtitle line-clamp. Values: one | two | three.
- slimbooleanfalse
- Reduces the prepend width to 28 px for tighter layouts.
- navbooleanfalse
- Navigation mode: reduces horizontal padding and adjusts font sizes for sidebar navigation patterns.
- itemTypestring'type'
- Key in each item object that identifies its type (item | subheader | divider | group).
- tagstring'div'
- Root HTML element tag. Use "ul" for semantic list markup.
- idstring
- classstring | Array<string> | object
- stylestring | Array<string> | object | StyleValue
- elevationTElevation
- Box-shadow elevation token.
- borderboolean | number | string | TDirectionBoth | Array<TDirectionBoth>false
- Applies a border and removes the box-shadow.
- borderTopboolean | number | string
- borderLeftboolean | number | string
- borderBottomboolean | number | string
- borderRightboolean | number | string
- borderBlockboolean | number | string
- borderInlineboolean | number | string
- borderInlineStartboolean | number | string
- borderInlineEndboolean | number | string
- borderBlockStartboolean | number | string
- borderBlockEndboolean | number | string
- borderColorstring
- borderStylestring
- borderTopColorTColor
- borderRightColorTColor
- borderBottomColorTColor
- borderLeftColorTColor
- borderInlineStartColorTColor
- borderInlineEndColorTColor
- borderBlockStartColorTColor
- borderBlockEndColorTColor
- Adjusts item padding density. default | compact.
- sizeTSize | number
- Border-radius token or boolean.
- roundedTopRightboolean | number | string
- roundedTopLeftboolean | number | string
- roundedBottomLeftboolean | number | string
- roundedBottomRightboolean | number | string
- roundedStartStartboolean | number | string
- roundedStartEndboolean | number | string
- roundedEndStartboolean | number | string
- roundedEndEndboolean | number | string
- heightnumber | string
- maxHeightnumber | string
- maxWidthnumber | string
- minHeightnumber | string
- minWidthnumber | string
- widthnumber | string
- selectStrategyTSelectStrategy | TSelectStrategyFn
- openStrategyTOpenStrategy | TOpenStrategyFns
- selectedArray<unknown>
- openedArray<unknown>
- mandatoryboolean
- itemsArray<any>[]
- Data array. Each element is mapped to a ListItem, ListGroup or ListSubheader by ListChildren.
- Key (or getter) used to extract the title text from each item object.
- Key (or getter) used to extract the selection value from each item object.
- Key (or getter) used to extract nested children (creates a ListGroup).
- Key (or getter) that returns extra props merged onto each ListItem.
- returnObjectbooleanfalse
- When true, emits the full item object instead of itemValue.
- valueComparatortypeof deepEqual
- color
- Foreground / active item color, propagated down to child ListItems.
- bgColor
- Background color propagated down to child ListItems.
- paddingboolean | number | string
- paddingTopboolean | number | string
- paddingLeftboolean | number | string
- paddingBottomboolean | number | string
- paddingRightboolean | number | string
- paddingBlockboolean | number | string
- paddingInlineboolean | number | string
- paddingInlineStartboolean | number | string
- paddingInlineEndboolean | number | string
- paddingBlockStartboolean | number | string
- paddingBlockEndboolean | number | string
- marginboolean | number | string
- marginTopboolean | number | string
- marginLeftboolean | number | string
- marginBottomboolean | number | string
- marginRightboolean | number | string
- marginBlockboolean | number | string
- marginInlineboolean | number | string
- marginInlineStartboolean | number | string
- marginInlineEndboolean | number | string
- marginBlockStartboolean | number | string
- marginBlockEndboolean | number | string
API
Slots
Content slots exposed by this component.
- #default
- Full control of item rendering. When absent, ListChildren auto-renders from the items prop.
- #childrenItem
- Custom renderer for child items inside a ListGroup.
- #divider
- Custom renderer for divider rows (type: "divider" in items).
- #subheader
- Custom renderer for subheader rows.
- #group
- Custom renderer for group rows.
- #groupActivator
- Custom renderer for the group activator header. isOpen exposes the current open state; events holds the click handler.
- #item
- Custom renderer for each item row. itemProps is the merged props for the auto-rendered ListItem.
API
Emits
Events emitted by this component.
- @update:selectedArray<unknown>
- Emitted when the selected items change.
- @update:openedArray<unknown>
- Emitted when open groups change.
- @click:open{ id: unknown, value: boolean, path: Array<unknown> }
- Fired when the user clicks a group activator to open/close a group.
- @click:select{ id: unknown, value: boolean, path: Array<unknown> }
- Fired when the user clicks a selectable item.
API
Exposed members
Properties and methods accessible via template ref (defineExpose). Use them for programmatic control.
- (id: unknown, value: boolean) => void
- Programmatically open or close a ListGroup by its item id.
- (id: unknown, value: boolean) => void
- Programmatically select or deselect a ListItem by its item id.
- (location?: TFocusLocation) => void
- Focuses the first / last / next / prev interactive item. Used internally by keyboard navigation.
- Ref<Map<unknown, unknown[]>>
- Map of parent → children IDs for the nested tree.
- Ref<Map<unknown, unknown>>
- Map of child → parent IDs for the nested tree.
- <T extends object>(props: T, exclude?: string[]) => Partial<T>
- Utility to forward a filtered subset of props to a child.
- Ref<string>
- Reactive CSS string generated by useStyle.
- string
- Unique style-sheet ID for this instance.
- () => void
- Injects the computed style sheet. Called automatically on mount.
- () => void
- Removes the injected style sheet. Called automatically on unmount.
- Ref<boolean>
- True once the style sheet has been injected into the DOM.
Customisation
CSS variables
CSS custom properties exposed by this component. Override them to customise the component without losing theme compatibility.
- List background color.
- List foreground color inherited by items.
- List box shadow. Removed when border is active.
- Top padding of the list container.
- Bottom padding of the list container.
- Density offset applied to item padding. compact: -8px.
- Minimum height of each ListItem.
- Title font size. Overridden in --nav mode.
- Subtitle font size.
- Subheader label font size.
Inclusion
Accessibility
ARIA roles, keyboard navigation and focus management. Sourced from the real component template.
ARIA roles
Keyboard interactions
| Key | Action |
|---|---|
| ArrowDown | Moves focus to the next list item. |
| ArrowUp | Moves focus to the previous list item. |
| Home | Moves focus to the first list item. |
| End | Moves focus to the last list item. |
| Enter / Space | Activates (selects or follows link of) the focused item. |
| Tab | Tab exits the list and moves to the next focusable element in the page. |
Notes
- OrigamList renders with <code>role="listbox"</code>. Individual items receive <code>tabindex="-2"</code> (managed tab focus) while the list root itself holds <code>tabindex="0"</code> when not focused internally.
- For navigation lists, prefer wrapping OrigamList in a <code><nav></code> landmark and setting <code>tag="ul"</code> on OrigamList with <code>tag="li"</code> on each ListItem.
- When disabled=true, pointer-events and user-select are set to none, but the element remains in the DOM. The list is still focusable — add aria-disabled="true" manually if needed.
Foundation
Design tokens
Excerpt from this component's token declarations — the --origam-<component>---<property> variables, declared in its hand-maintained token sheet with no build step.
- colorvar(--origam-color__surface---default)
- Default list background.
- colorvar(--origam-color__text---primary)
- Default foreground color.
- dimension56px
- Minimum height of each list item.
- dimensionvar(--origam-space---4)
- Start padding of each list item.
- dimensionvar(--origam-font__size---lg)
- List item title font size.
- dimensionvar(--origam-font__size---md)
- List item subtitle font size.
- dimensionvar(--origam-font__size---md)
- Subheader font size.
- colorvar(--origam-color__text---secondary)
- Subheader text color.
Interactive
Playground
Edit props live and see the component update in real time. The generated code snippet updates as you change values.
Rendering the live preview…
Usage
Examples
Ready-to-paste code snippets for your templates.
Basic list from data
Navigation list (nav mode)
Grouped list
Ecosystem
Family
Components from the same folder that share conventions and often compose together.