Skip to content

OrigamListItem ​

<OrigamListItem> renders a single interactive or informational row inside an OrigamList. It supports a title and subtitle (as props or slots), leading / trailing icons or avatars via the prepend and append slots, and a full set of visual, spacing, link and typography props.

Basic usage ​

vue
<template>
    <OrigamList>
        <OrigamListItem title="Primary text" subtitle="Secondary line" />
    </OrigamList>
</template>

With prepend / append icons ​

vue
<template>
    <OrigamList>
        <OrigamListItem
            title="Inbox"
            prepend-icon="mdi-inbox"
            append-icon="mdi-chevron-right"
        />
    </OrigamList>
</template>

Typography on title and subtitle ​

fontSize, fontWeight, lineHeight and letterSpacing drive both the title and subtitle surfaces simultaneously via two dedicated CSS variable prefixes (list-item__title and list-item__subtitle).

vue
<template>
    <OrigamList>
        <OrigamListItem
            title="Bold title"
            subtitle="Compact subtitle"
            font-size="lg"
            font-weight="semibold"
            line-height="tight"
            letter-spacing="wide"
        />
    </OrigamList>
</template>

Props ​

PropTypeDefaultDescription
titlestring | number—Primary text (also available as #title slot)
subtitlestring | number—Secondary text (also available as #subtitle slot)
activebooleanfalseForces the active state
activeClassstring—CSS class applied when active
disabledbooleanfalsePrevents interaction
linesTLines—Clamp subtitle to one, two or three lines
linkbooleanfalseMakes the item behave as a link
navbooleanfalseNav-mode sizing (0.8125rem title, 0.75rem subtitle)
slimbooleanfalseHalves the row's inline padding (16px → 8px) via --origam-list-item--slim---padding-inline-{start,end}. Block padding is untouched — it belongs to the size rungs
tagstring'div'Root HTML element
hrefstring—Anchor href (renders as <a>)
toRouteLocationRaw—Router-link target
valueany—Selectable value within a list group
prependIconstring—Icon shown before content
appendIconstring—Icon shown after content
prependAvatarstring—Avatar image URL shown before content
appendAvatarstring—Avatar image URL shown after content
densityTDensity—Row density (default · compact · comfortable). Shifts the row height by 0 / -8px / +8px. The row has authority — see below
sizeTSize—Row-height rung — see the section below. Inherited from the parent list unless set
colorTColor—Foreground (text) colour — an intent (primary, success, …) or a raw CSS colour. Inherited from the parent list / group unless set
bgColorTColor—Surface colour. An intent also pairs the matching contrast foreground automatically. Inherited from the parent list / group unless set

Props — density: who decides the row height ​

The row decides; the list only supplies a default (#571).

  • A row that is not given a density inherits the one its parent <origam-list> carries. This is the common case and it is unchanged.
  • A row that is given a density wins over its list, because it re-declares the same custom property (--origam-list---density) on itself, closer in the cascade.
  • A row with no list ancestor at all now honours its own density. Before #571 it did not: the value reached only a class (origam-list-item--density-*) that no rule read, so a standalone row rendered at the default rung whatever you passed it.

⛔ The row re-declares the property, it does not add a second term to the calc(). The distinction is load-bearing: measured in Chromium on a compact list, re-declaring keeps the row at 48px (unchanged), while adding a second term would count -8px twice and drop it to 40px.

list compactlist comfortableno list
row density unset48px64px56px
row compact48px48px48px
row comfortable64px64px64px

The shipped origam theme sets density: 'compact' on origam-list only. It used to set it on origam-list-item as well; that entry was removed in #571, because once the row has authority a blanket theme default on every row would beat any density a consumer puts on the list.

Props — size: the row-height scale ​

size selects a rung of the shared control-height scale — the same one --origam-input__control---height-{sm,md,lg,xl} drives — so a row and a field carrying the same size end up with an identical vertical footprint. This is what lets an OrigamSelect dropdown match its own control.

sizeRow heightBlock paddingNotes
(unset)40px8pxHistorical default — unchanged for lists that never opt in
x-small36px6pxDeliberately mapped onto the default rung: .origam-field has no x-small rule either, so a smaller row would re-create the mismatch
small28px2px
default36px6px
large44px10px
x-large52px14px

Two behaviours worth knowing:

  • The title is NOT scaled. .origam-field keeps a fixed 16px text at every size, so shrinking the row title would re-introduce the very mismatch this scale exists to remove — __title holds its own 1rem / 1.5rem line box whatever the rung. size does still emit the origam--text-{rung} utility on the row root, so anything inheriting the row's font size (default slot content, for instance) follows the rung. Use the typography props below if you want the title itself to follow.
  • size composes with density, it does not replace it. The resolved height is max(rung + density, titleLineHeight + blockPadding) — the exact model .origam-field__input uses, flooring included. A small row at compact density therefore stays at 28px rather than collapsing to 20px, just as the field does.

Each rung is overridable per theme through --origam-list-item---height-{sm,md,lg,xl} and --origam-list-item---padding-block-{sm,md,lg,xl}. The rung is the total row height: the row declares box-sizing: border-box on its own base rule (it does not rely on the consumer's reset), so the rung goes into --origam-list-item---min-height whole — that min-height is the rendered height. The block padding does not subtract from it; it only positions the 24px title line box inside the row.

Props — Typography (title and subtitle surfaces) ​

Both __title and __subtitle respond to the same prop set — one value controls both children simultaneously.

PropTypeDefaultDescription
fontSizeTFontSize—Font-size token (xs · sm · md · lg · xl · …). Sets --origam-list-item__title---font-size and --origam-list-item__subtitle---font-size. Overrides nav-mode sizing.
fontWeightTFontWeight—Font-weight token (regular · medium · semibold · bold · …). Sets --origam-list-item__title---font-weight and --origam-list-item__subtitle---font-weight.
lineHeightTLineHeight—Line-height token (none · tight · snug · normal · relaxed · loose). Sets --origam-list-item__title---line-height and --origam-list-item__subtitle---line-height.
letterSpacingTLetterSpacing—Letter-spacing token (tight · normal · wide · wider · widest). Sets --origam-list-item__title---letter-spacing and --origam-list-item__subtitle---letter-spacing.

Emits ​

EventPayloadDescription
clickMouseEventFired on item click
click:prependMouseEventFired when the prepend area is clicked
click:appendMouseEventFired when the append area is clicked

Slots ​

SlotScopeDescription
default{ isActive, select, isSelected, isIndeterminate }Arbitrary content inside the content area
title{ title }Custom title content
subtitle{ subtitle }Custom subtitle content
prependslot propsLeading avatar / icon override
appendslot propsTrailing avatar / icon override
wrapper—Full content wrapper override

Accessibility ​

  • The row does not choose its own role (#424). It reads the one its list published through ORIGAM_LIST_KEY: role="listitem" inside a plain role="list", role="option" inside a role="listbox". An option outside a listbox — or a listitem inside one — is a broken ARIA contract, and neither is reachable from here. Which mode a list runs in is documented on OrigamList.
  • A link row (href / to) in list mode renders <div role="listitem"><a> (#1249). An explicit role replaces the implicit one, so role="listitem" on the <a> made a link announce as a list item and vanish from the links rotor. The role now sits on a wrapper div (.origam-list-item-wrapper); the <a> keeps link and stays the whole visual row (classes, styles, ripple, tabindex, handlers). Selection mode (option) and every non-link row keep the flat structure.
  • Two rows still get no role at all: one rendered outside any list (no OrigamList / OrigamListChildren ancestor) — no ARIA is better than a role whose promised container doesn't exist — and a group activator row, which only toggles expand/collapse and never fires a selection, so it is a control rather than one of the list's rows.
  • aria-selected mirrors isSelected, and aria-disabled mirrors the disabled prop, only in the option role. Both are required state on an option and meaningless on a listitem: a plain list row reporting "not selected" would invent a selection the list does not offer.
  • A group activator row (rendered inside OrigamListGroupActivator) never gets role="option" — clicking it only toggles expand/collapse, it never fires a selection (see OrigamListGroup's role="group" region).

Tokens ​

VariableDefaultUsed for
--origam-list-item__title---font-size1remtitle font size
--origam-list-item__title---font-weight400title font weight
--origam-list-item__title---letter-spacing0.009375emtitle letter spacing
--origam-list-item__title---line-height1.5remtitle line height
--origam-list-item__subtitle---font-size0.875remsubtitle font size
--origam-list-item__subtitle---font-weight400subtitle font weight
--origam-list-item__subtitle---letter-spacing0.0178571429emsubtitle letter spacing
--origam-list-item__subtitle---line-height1remsubtitle line height
--origam-list-item---min-heightundeclared — resolves through --origam-list__item---min-height (56px)row minimum border-box height, i.e. the rendered row height (density-adjusted). Set to the whole rung by the size prop's --size-* rules; padding does not subtract from it
--origam-list-item---overlay-opacity-hover0.08overlay opacity of a link row on hover / focus-visible
--origam-list-item---overlay-opacity-active0.12overlay opacity of an active row (--active, expanded group activator); set 0 to show the row's bare bgColor
--origam-list-item---overlay-opacity-active-hover0.16overlay opacity of an active row on hover / focus-visible
--origam-list-item---padding-block-start8pxtop padding
--origam-list-item---padding-inline-start16pxleft padding (indent-adjusted)
--origam-list-item---height-sm / -md / -lg / -xl28px / 36px / 44px / 52pxtotal row height per size rung
--origam-list-item---padding-block-sm / -md / -lg / -xl2px / 6px / 10px / 14pxblock padding per size rung
--origam-list-item--slim---padding-inline-start / -end8px / 8pxinline padding when slim is set