List
Accessible list component with support for navigation, selection, groups, subheaders, icons, avatars, single/multi-line items and keyboard traversal.
Structure
Anatomie
Décomposition visuelle de la structure interne du composant avec les appels de classes BEM.
<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
Toutes les props acceptées par ce composant, avec leur type, valeur par défaut et 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
Emplacements de contenu exposés par ce composant.
- #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
Événements émis par ce composant.
- @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
Membres exposés
Propriétés et méthodes accessibles via ref template (defineExpose). Utilisés pour le contrôle programmatique.
- (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.
Personnalisation
Variables CSS
Propriétés CSS personnalisées exposées par ce composant. Surchargez-les pour personnaliser sans perdre la compatibilité avec le thème.
- 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
Accessibilité
Rôles ARIA, navigation clavier et gestion du focus. Sourcé depuis le template réel du composant.
Rôles ARIA
Interactions clavier
| Touche | 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.
Fondation
Design tokens
Extrait des tokens de ce composant — les variables --origam-<composant>---<propriété>, déclarées dans sa feuille de tokens tenue à la main, sans étape de build.
- 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.
Interactif
Playground
Modifiez les props en direct et observez le composant se mettre à jour. Le snippet de code généré suit vos changements.
Rendu de l’aperçu en cours…
Usage
Exemples
Extraits de code prêts à coller dans vos templates.
Basic list from data
Navigation list (nav mode)
Grouped list
Écosystème
Famille
Composants du même dossier qui partagent les conventions et se composent souvent ensemble.