List

Data Display
stable

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.

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

All props accepted by this component, with their type, default value and 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

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

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

listbox

Keyboard interactions

Keyboard interactions
KeyAction
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.

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.

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.

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

vue

Navigation list (nav mode)

vue

Grouped list

vue

Ecosystem

Family

Components from the same folder that share conventions and often compose together.