Skip to content

OrigamList ​

<OrigamList> is the root container of the List family. It lays out rows either from slotted children (OrigamListItem, OrigamListSubheader, OrigamListGroup, …) or from a declarative items array, and it owns the nested selection/expansion state shared by every descendant.

Its ARIA role describes what it is, not what it could do: a plain role="list" by default, and role="listbox" only once the consumer asks for selection. See Accessibility.

Basic usage ​

vue
<template>
    <origam-list>
        <origam-list-item title="Inbox" />
        <origam-list-item title="Sent" />
        <origam-list-item title="Drafts" />
    </origam-list>
</template>

Declarative items ​

Pass an items array instead of slotted children and OrigamList renders each row through OrigamListChildren internally. itemTitle / itemValue / itemChildren / itemProps control how each raw item is read (string key, dot-notation path, array path, or accessor function — see TSelectItemKey).

vue
<template>
    <origam-list
        :items="[
            { title: 'Inbox', value: 'inbox' },
            { title: 'Sent', value: 'sent' }
        ]"
    />
</template>

Items with a children array automatically render as a collapsible OrigamListGroup (see Nested groups) — that check is based on the presence of children, independent of any type field.

returnObject makes selected emit the raw item objects instead of their value; valueComparator (default: deep-equal) controls how a v-model:selected entry is matched back to an item.

itemType (default 'type') and the 'item' | 'subheader' | 'divider' discriminant it is meant to read off each raw item (LIST_ITEM_TYPE) are not currently wired through — see the known-gap note under Props. Until that's fixed, render subheaders/dividers by slotting them directly instead:

vue
<template>
    <origam-list>
        <origam-list-subheader title="Fruits" />
        <origam-list-item title="Apple" />
        <origam-list-item title="Banana" />
        <origam-divider />
        <origam-list-subheader title="Vegetables" />
        <origam-list-item title="Carrot" />
    </origam-list>
</template>

Selection ​

selected (with update:selected) and selectStrategy drive which rows can be selected and how a selection propagates to/from grouped children:

selectStrategy (SELECT_STRATEGY)Behaviour
single-leaf (default)Only one leaf item selected at a time
leafMultiple leaf items selectable
independentEvery node (leaf or group) selects independently
single-independentSingle selection, any node type
classicSelecting a group selects/deselects all its descendants

mandatory prevents the selection from becoming empty. click:select fires with { id, value, path } on every user-driven selection toggle.

vue
<template>
    <origam-list
        :items="items"
        v-model:selected="selected"
        select-strategy="leaf"
        mandatory
    />
</template>

Nested groups ​

Items with a non-empty children array (or slotted OrigamListGroup / OrigamListItem with nested children) become collapsible groups. opened (with update:opened) tracks which group ids are expanded; openStrategy controls how opening one group affects its siblings:

openStrategy (OPEN_STRATEGY)Behaviour
list (default)Opening a group at the root closes its root-level siblings
singleOnly one group open at a time at any depth
multipleAny number of groups can stay open simultaneously

click:open fires with { id, value, path } on every user-driven toggle.

vue
<template>
    <origam-list
        :items="[
            { title: 'Documents', children: [
                { title: 'Resume.pdf' },
                { title: 'Cover letter.pdf' }
            ]}
        ]"
        v-model:opened="opened"
        open-strategy="multiple"
    />
</template>

Keyboard navigation ​

The root listens for ArrowDown / ArrowUp / Home / End and moves focus between rows (focusChild util); focus wraps within the rendered set of focusable descendants.

nav switches to a denser navigation-rail sizing (smaller title/subtitle font and negative indent) and slim reduces the prepend-area width. Both work by setting CSS custom properties on the root (.origam-list--nav, .origam-list--slim) that descendant OrigamListItem / OrigamListSubheader / OrigamListGroup elements inherit through normal CSS variable cascade — no per-item prop wiring needed.

vue
<template>
    <origam-list nav>
        <origam-list-item title="Dashboard" prepend-icon="mdi-view-dashboard" />
    </origam-list>
</template>

lines ​

lines (TLines: 'one' | 'two' | 'three', default 'one') is meant to clamp every descendant OrigamListItem subtitle to that many lines, and does add an origam-list--{lines}-line class to the root — but no CSS rule in the codebase selects that class, so today it has no visible effect. The line-clamp itself only works when set directly on each OrigamListItem (origam-list-item--{lines}-line, documented on OrigamListItem). See the known-gap note under Props.

Disabled ​

disabled sets the whole list non-interactive (pointer-events: none, tabindex="-1" on the root).

Density / size / color / shape ​

density (TDensity: 'default' | 'compact' | 'comfortable'), color / bgColor (TColor, cascaded as defaults to every descendant OrigamListItem — an item's own color/bgColor still wins), elevation, rounded, border (+ per-side variants) and padding / margin (+ per-side variants) all follow the standard cross-cutting composables (useDensity, useBothColor, useElevation, useRounded, useBorder, usePadding, useMargin) — see the matching Commons interface for the full per-side prop set.

size (TSize) is a forwarding prop: the list root paints nothing from it, it is pushed down to every descendant OrigamListItem through the same defaults channel as density / color / bgColor, where it selects a rung of the shared control-height scale (28 / 36 / 44 / 52px — the same one --origam-input__control---height-{sm,md,lg,xl} drives). It exists so a container that owns a size — an OrigamSelect dropdown, a sized OrigamMenu — can keep its popup rows on the same vertical scale as its control. x-small maps onto the default rung, mirroring .origam-field, which has no x-small rule either.

size and density compose rather than compete: the row height resolves to max(rung + density, titleLineHeight + blockPadding), the exact model .origam-field__input uses. A list left without a size keeps the historical 40px row.

Dimension ​

height, width, minHeight, minWidth, maxHeight and maxWidth (IDimensionProps, via useDimension) size the root element — useful to cap a scrollable list (max-height + the default overflow: auto).

Props ​

PropTypeDefaultDescription
tagstring'div'Root HTML element
itemsArray<any>[]Declarative row definitions (see Declarative items)
itemTitleTSelectItemKey'title'Key/path/accessor read for each item's title
itemValueTSelectItemKey'value'Key/path/accessor read for each item's value
itemChildrenTSelectItemKey'children'Key/path/accessor read for nested children
itemPropsTSelectItemKey'props'Key/path/accessor read for the props forwarded to the row renderer
itemTypestring'type'Key/path/accessor read off each raw items entry to discriminate item / subheader / divider (LIST_ITEM_TYPE)
returnObjectboolean—selected carries the raw item objects instead of their value
valueComparator(a, b) => booleandeepEqualCustom equality check used to match a selected value back to an item
selectedArray<unknown>—v-model:selected — currently selected id(s)
openedArray<unknown>—v-model:opened — currently expanded group id(s)
selectStrategyTSelectStrategy | TSelectStrategyFn'single-leaf'Selection propagation strategy (see Selection)
openStrategyTOpenStrategy | TOpenStrategyFns'list'Group-expansion propagation strategy (see Nested groups)
mandatoryboolean—Prevents the selection from becoming empty
linesTLines'one'Intended subtitle line-clamp — currently has no visible effect, see lines note above
navbooleanfalseNav-rail sizing (smaller fonts, negative indent), cascaded via CSS variables
slimbooleanfalseReduced prepend-area width, cascaded via CSS variables
disabledbooleanfalseDisables the whole list (non-interactive)
colorTColor—Text color intent, cascaded as a default to descendant items
bgColorTColor—Background color intent, cascaded as a default to descendant items
densityTDensity'default'Row density, cascaded as a default to descendant items
sizeTSize—Row-height rung (28/36/44/52px), cascaded as a default to descendant items. Paints nothing on the root — see note above
elevationTElevation—Shadow rung
roundedboolean | number | string | TRounded—Corner radius (+ per-corner variants)
borderboolean | number | string | TDirectionBoth | Array<TDirectionBoth>—Border (+ per-side variants and borderColor / borderStyle)
paddingboolean | number | string—Padding (+ per-side variants)
marginboolean | number | string—Margin (+ per-side variants)
height / width / minHeight / minWidth / maxHeight / maxWidthnumber | string—Root dimension overrides
activeClassstring—Declared on IListProps but not currently read by OrigamList (see note below)
expandIcon / collapseIconstring—Declared on IListProps but not currently read by OrigamList (see note below)

Known gaps

  • activeClass, expandIcon and collapseIcon are part of IListProps (packages/ds/src/interfaces/List/list.interface.ts) but OrigamList.vue neither reads them in its <script setup> nor forwards them through slotDefaults to descendants. Passing them today has no effect. OrigamListGroup, by contrast, does have working expandIcon / collapseIcon props (defaulting to MDI_ICONS.CHEVRON_DOWN / MDI_ICONS.CHEVRON_UP, i.e. 'mdi:mdi-chevron-down' / 'mdi:mdi-chevron-up').
  • lines computes an origam-list--{lines}-line class (OrigamList.vue, lineClasses) but no SCSS rule in the codebase selects that class name — grepping the whole packages/ds/src tree for list--one-line / list--two-line / list--three-line only turns up the class-generation line itself. Passing lines on OrigamList today has no visible effect; each OrigamListItem needs its own lines prop for the clamp to actually apply. Flagging all of the above rather than guessing at intended behaviour.

Fixed (#424) — itemType / structural items entries used to be dropped during transform: transformListItem (packages/ds/src/utils/List/list-item.util.ts) never read props.itemType and never set a type field on its returned object, so OrigamListChildren's hasDivider / hasSubheader (which only match on item.type === LIST_ITEM_TYPE.DIVIDER / .SUBHEADER) always fell through to the default OrigamListItem branch — a { type: 'divider' } entry has no title key, so the un-stringified raw item leaked into the row's title prop and Vue rendered it as a literal JSON dump. Both are fixed: type is read and forwarded, and the row's resolved title is always coerced to a string before being handed to a component prop. { type: 'subheader', title: '…' } / { type: 'divider' } entries in a plain items array now render as a real OrigamListSubheader / <origam-divider role="separator">, exactly like the OrigamList.story.vue fixtures (itemsWithSubheader, itemsWithDivider) intend.

Emits ​

EventPayloadDescription
update:selectedArray<unknown>Fired when the selection changes
update:openedArray<unknown>Fired when the expanded-group set changes
click:select{ id, value, path }Fired on every user-driven selection toggle
click:open{ id, value, path }Fired on every user-driven group-expansion toggle

Slots ​

SlotScopeDescription
default—Slotted rows (OrigamListItem, OrigamListSubheader, OrigamListGroup, …); overrides the items-driven renderer entirely
itemspread item.props (OrigamList.vue re-emits via v-bind="itemProps", not { itemProps })Overrides the row renderer for the fallback/plain-item case
subheaderspread item.props (same spread as item, not { itemProps })Overrides the row renderer — but OrigamListChildren.hasSubheader is slots.subheader || item.type === 'subheader', so merely providing this slot makes every row match it (unless a divider slot is also supplied, which is checked first)
dividerspread item.props (same spread as item, not { itemProps })Overrides the row renderer — but OrigamListChildren.hasDivider is slots.divider || item.type === 'divider', so merely providing this slot makes every row match it (it's checked before subheader / group / item)
groupspread item.props (same spread as item, not { itemProps })Overrides the row renderer for group (parent) items — rows whose children array is non-empty; unlike subheader / divider this check is purely data-driven, not slot-gated
groupActivator{ props, isOpen, events, toggleIcon }Overrides the clickable header of a group
childrenItem{ item, index }Overrides the wrapper rendered around every item (item + its <div class="origam-list-children__item">)

subheaderTitle ({ title }) exists on OrigamListChildren (which owns the subheader's title content), but OrigamList does not forward it — it only forwards childrenItem, divider, subheader, group, groupActivator and item (OrigamList.vue). Passing #subheaderTitle to <OrigamList> has no effect.

Composition — the List family ​

OrigamList is the entry point of a small family of components you compose directly in your templates:

  • OrigamListItem — a single row (title/subtitle, prepend/append icon or avatar, link behaviour).
  • OrigamListSubheader — a section label between groups of items.
  • OrigamListGroup (packages/ds/src/components/List/OrigamListGroup.vue) — a collapsible group: renders an activator row (an OrigamListItem by default) and, when open, a role="group" region with the group's own items. Used automatically for items with a non-empty children array, or can be nested manually in the default slot. No dedicated doc page exists for it yet — flagging this gap rather than inventing one.
  • OrigamListGroupActivator — the low-level wrapper a custom #groupActivator slot content should be placed in; it registers the group-activator context so the activator itself doesn't count as a nested list item.
  • OrigamListChildren — the internal renderer that turns an items array into rows (item / subheader / divider / group); used automatically when you pass items, rarely instantiated directly.

Accessibility ​

Two modes, one decision (#424) ​

The root used to hard-code role="listbox" — unconditionally, for every list ever rendered. A listbox is a selection widget: it promises option children carrying aria-selected, and a screen reader announces it as "list box, N items, selected …". A navigation list, a list of subheaders and dividers, or <OrigamMenu>'s item list is none of those. The role now describes what the list is:

the consumer…rootevery real row
renders a list (default)role="list"role="listitem", no aria-selected
asks for selectionrole="listbox"role="option" + aria-selected (+ aria-disabled when disabled)

Selection mode is entered by passing selected (typically v-model:selected), an explicit selectStrategy, or a listener on update:selected — that emit only ever fires when a selection changes, so wiring it is asking for selection. The first two are exactly what <OrigamSelect> passes — so its combobox contract holds, aria-controls and aria-activedescendant still pointing at a real listbox of real options — and none of the three is what <OrigamMenu> passes, so a menu's list stops claiming to be a listbox it never was.

⛔ The mode is not read from props.selectStrategy. That prop has a withDefaults value, so it is always truthy; reading it would leave every list on earth a listbox. It is read off vnode.props through usePassedProps — the difference between "the consumer asked" and "Vue filled in a default". That is also the only place the update:selected listener is visible: Vue strips the listener of a declared emit out of $attrs.

A row never picks its own role: the list publishes it through ORIGAM_LIST_KEY and the row reads it, so the container and its rows can never disagree. Values live in the LIST_ROLE / LIST_ITEM_ROLE enums.

  • Root carries a roving tabindex (0 when focusable, -1 when disabled or already focused inside).
  • OrigamListSubheader (a label, not a selectable element) and the divider (role="separator", via OrigamDivider) get neither row role. Neither does a group's activator row — it only toggles expand/collapse and never fires a selection, so it is a control, not one of the list's rows. A bare OrigamListItem rendered outside any list (list context absent) gets no role at all — no ARIA is better than a role whose promised container doesn't exist.
  • Passing your own role on <OrigamList> overrides the computed one, for a container that is genuinely something else (a menu, a tablist).
  • Each nested collapsible group (OrigamListGroup) renders its items region as role="group" with aria-labelledby pointing at its activator.
  • Arrow key / Home / End navigation moves focus between rows without changing selection — selection remains an explicit user action (click or the row's own key handling).

CSS variables ​

VariableDefault sourceDescription
--origam-list---backgroundcolor.surface.defaultList background
--origam-list---colorcolor.text.primaryDefault text color
--origam-list---box-shadowshadow.noneElevation shadow
--origam-list---border-radius0pxCorner radius — a single var read by OrigamList.vue (fallback 0px); the four corner tokens declared in list.json (border-{start-start,start-end,end-start,end-end}-radius) are not composed/read by the component today
--origam-list---border-colorcolor.text.primaryBorder color
--origam-list---border-stylesolidBorder style
--origam-list---border-widthborder.width.0Border width — a single shorthand read by OrigamList.vue; the per-side tokens declared in list.json (border-{top,left,bottom,right}-width) are not read by the component today
--origam-list---padding-block-start / -endspace.2 (8px)Vertical padding
--origam-list---padding-inline-start / -endspace.0Horizontal padding
--origam-list---overflowautoOverflow behaviour
--origam-list---indent-padding0pxBase indent added to nested group items
--origam-list---indent-padding-nav-8pxIndent override applied when nav is set
--origam-list---slim-prepend-width28pxPrepend width when slim is set
--origam-list---density0pxDensity modifier
--origam-list__overlay---background-colorcolor.overlay.scrimRow overlay scrim (hover/focus)
--origam-list__overlay---opacityopacity.0Row overlay opacity

Row-level (--origam-list-item---*), subheader-level (--origam-list-subheader---*) and group-level (--origam-list-group---*) variables are documented on their own pages (OrigamListItem, OrigamListSubheader).