List

Data Display
stable

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.

Anatomy of OrigamListSchematic of the List component with subheader, items and group. SECTION HEADER i List item title Subtitle text Active item Group header (collapsed) ▶ Nested child item 1 2 3 4 5
Anatomy of <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-padding CSS variable.

API

Props

Toutes les props acceptées par ce composant, avec leur type, valeur par défaut et description.

activeClass
string
Extra CSS class injected on the active ListItem.
disabled
boolean
false
Disables all interaction (pointer-events: none; user-select: none).
expandIcon
string
Icon used to indicate an expandable group (overrides ListGroup default).
collapseIcon
string
Icon used to indicate a collapsed group (overrides ListGroup default).
lines
'one'
Controls item min-height and subtitle line-clamp. Values: one | two | three.
slim
boolean
false
Reduces the prepend width to 28 px for tighter layouts.
nav
boolean
false
Navigation mode: reduces horizontal padding and adjusts font sizes for sidebar navigation patterns.
itemType
string
'type'
Key in each item object that identifies its type (item | subheader | divider | group).
tag
string
'div'
Root HTML element tag. Use "ul" for semantic list markup.
id
string
class
string | Array<string> | object
style
string | Array<string> | object | StyleValue
elevation
TElevation
Box-shadow elevation token.
border
boolean | number | string | TDirectionBoth | Array<TDirectionBoth>
false
Applies a border and removes the box-shadow.
borderTop
boolean | number | string
borderLeft
boolean | number | string
borderBottom
boolean | number | string
borderRight
boolean | number | string
borderBlock
boolean | number | string
borderInline
boolean | number | string
borderInlineStart
boolean | number | string
borderInlineEnd
boolean | number | string
borderBlockStart
boolean | number | string
borderBlockEnd
boolean | number | string
borderColor
string
borderStyle
string
borderTopColor
TColor
borderRightColor
TColor
borderBottomColor
TColor
borderLeftColor
TColor
borderInlineStartColor
TColor
borderInlineEndColor
TColor
borderBlockStartColor
TColor
borderBlockEndColor
TColor
density
'default'
Adjusts item padding density. default | compact.
size
TSize | number
Border-radius token or boolean.
roundedTopRight
boolean | number | string
roundedTopLeft
boolean | number | string
roundedBottomLeft
boolean | number | string
roundedBottomRight
boolean | number | string
roundedStartStart
boolean | number | string
roundedStartEnd
boolean | number | string
roundedEndStart
boolean | number | string
roundedEndEnd
boolean | number | string
height
number | string
maxHeight
number | string
maxWidth
number | string
minHeight
number | string
minWidth
number | string
width
number | string
selectStrategy
TSelectStrategy | TSelectStrategyFn
openStrategy
TOpenStrategy | TOpenStrategyFns
selected
Array<unknown>
opened
Array<unknown>
mandatory
boolean
items
Array<any>
[]
Data array. Each element is mapped to a ListItem, ListGroup or ListSubheader by ListChildren.
itemTitle
'title'
Key (or getter) used to extract the title text from each item object.
itemValue
'value'
Key (or getter) used to extract the selection value from each item object.
itemChildren
'children'
Key (or getter) used to extract nested children (creates a ListGroup).
itemProps
'props'
Key (or getter) that returns extra props merged onto each ListItem.
returnObject
boolean
false
When true, emits the full item object instead of itemValue.
valueComparator
typeof deepEqual
color
Foreground / active item color, propagated down to child ListItems.
bgColor
Background color propagated down to child ListItems.
padding
boolean | number | string
paddingTop
boolean | number | string
paddingLeft
boolean | number | string
paddingBottom
boolean | number | string
paddingRight
boolean | number | string
paddingBlock
boolean | number | string
paddingInline
boolean | number | string
paddingInlineStart
boolean | number | string
paddingInlineEnd
boolean | number | string
paddingBlockStart
boolean | number | string
paddingBlockEnd
boolean | number | string
margin
boolean | number | string
marginTop
boolean | number | string
marginLeft
boolean | number | string
marginBottom
boolean | number | string
marginRight
boolean | number | string
marginBlock
boolean | number | string
marginInline
boolean | number | string
marginInlineStart
boolean | number | string
marginInlineEnd
boolean | number | string
marginBlockStart
boolean | number | string
marginBlockEnd
boolean | 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:selected
Array<unknown>
Emitted when the selected items change.
@update:opened
Array<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

listbox

Interactions clavier

Interactions clavier
ToucheAction
ArrowDownMoves focus to the next list item.
ArrowUpMoves focus to the previous list item.
HomeMoves focus to the first list item.
EndMoves focus to the last list item.
Enter / SpaceActivates (selects or follows link of) the focused item.
TabTab 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>&lt;nav&gt;</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.

Source
color
var(--origam-color__surface---default)
Default list background.
color
var(--origam-color__text---primary)
Default foreground color.
dimension
56px
Minimum height of each list item.
dimension
var(--origam-space---4)
Start padding of each list item.
dimension
var(--origam-font__size---lg)
List item title font size.
dimension
var(--origam-font__size---md)
List item subtitle font size.
dimension
var(--origam-font__size---md)
Subheader font size.
color
var(--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

vue

Navigation list (nav mode)

vue

Grouped list

vue

Écosystème

Famille

Composants du même dossier qui partagent les conventions et se composent souvent ensemble.