Appearance
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
| Prop | Type | Default | Description |
|---|---|---|---|
title | string | number | — | Primary text (also available as #title slot) |
subtitle | string | number | — | Secondary text (also available as #subtitle slot) |
active | boolean | false | Forces the active state |
activeClass | string | — | CSS class applied when active |
disabled | boolean | false | Prevents interaction |
lines | TLines | — | Clamp subtitle to one, two or three lines |
link | boolean | false | Makes the item behave as a link |
nav | boolean | false | Nav-mode sizing (0.8125rem title, 0.75rem subtitle) |
slim | boolean | false | Halves 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 |
tag | string | 'div' | Root HTML element |
href | string | — | Anchor href (renders as <a>) |
to | RouteLocationRaw | — | Router-link target |
value | any | — | Selectable value within a list group |
prependIcon | string | — | Icon shown before content |
appendIcon | string | — | Icon shown after content |
prependAvatar | string | — | Avatar image URL shown before content |
appendAvatar | string | — | Avatar image URL shown after content |
density | TDensity | — | Row density (default · compact · comfortable). Shifts the row height by 0 / -8px / +8px. The row has authority — see below |
size | TSize | — | Row-height rung — see the section below. Inherited from the parent list unless set |
color | TColor | — | Foreground (text) colour — an intent (primary, success, …) or a raw CSS colour. Inherited from the parent list / group unless set |
bgColor | TColor | — | 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
densityinherits the one its parent<origam-list>carries. This is the common case and it is unchanged. - A row that is given a
densitywins 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 compact | list comfortable | no list | |
|---|---|---|---|
| row density unset | 48px | 64px | 56px |
row compact | 48px | 48px | 48px |
row comfortable | 64px | 64px | 64px |
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.
size | Row height | Block padding | Notes |
|---|---|---|---|
| (unset) | 40px | 8px | Historical default — unchanged for lists that never opt in |
x-small | 36px | 6px | Deliberately mapped onto the default rung: .origam-field has no x-small rule either, so a smaller row would re-create the mismatch |
small | 28px | 2px | |
default | 36px | 6px | |
large | 44px | 10px | |
x-large | 52px | 14px |
Two behaviours worth knowing:
- The title is NOT scaled.
.origam-fieldkeeps a fixed 16px text at every size, so shrinking the row title would re-introduce the very mismatch this scale exists to remove —__titleholds its own1rem/1.5remline box whatever the rung.sizedoes still emit theorigam--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. sizecomposes withdensity, it does not replace it. The resolved height ismax(rung + density, titleLineHeight + blockPadding)— the exact model.origam-field__inputuses, flooring included. Asmallrow atcompactdensity 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.
| Prop | Type | Default | Description |
|---|---|---|---|
fontSize | TFontSize | — | 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. |
fontWeight | TFontWeight | — | Font-weight token (regular · medium · semibold · bold · …). Sets --origam-list-item__title---font-weight and --origam-list-item__subtitle---font-weight. |
lineHeight | TLineHeight | — | Line-height token (none · tight · snug · normal · relaxed · loose). Sets --origam-list-item__title---line-height and --origam-list-item__subtitle---line-height. |
letterSpacing | TLetterSpacing | — | Letter-spacing token (tight · normal · wide · wider · widest). Sets --origam-list-item__title---letter-spacing and --origam-list-item__subtitle---letter-spacing. |
Emits
| Event | Payload | Description |
|---|---|---|
click | MouseEvent | Fired on item click |
click:prepend | MouseEvent | Fired when the prepend area is clicked |
click:append | MouseEvent | Fired when the append area is clicked |
Slots
| Slot | Scope | Description |
|---|---|---|
default | { isActive, select, isSelected, isIndeterminate } | Arbitrary content inside the content area |
title | { title } | Custom title content |
subtitle | { subtitle } | Custom subtitle content |
prepend | slot props | Leading avatar / icon override |
append | slot props | Trailing 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 plainrole="list",role="option"inside arole="listbox". Anoptionoutside a listbox — or alistiteminside one — is a broken ARIA contract, and neither is reachable from here. Which mode a list runs in is documented onOrigamList. - A link row (
href/to) in list mode renders<div role="listitem"><a>(#1249). An explicitrolereplaces the implicit one, sorole="listitem"on the<a>made a link announce as a list item and vanish from the links rotor. The role now sits on a wrapperdiv(.origam-list-item-wrapper); the<a>keepslinkand 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/OrigamListChildrenancestor) — 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-selectedmirrorsisSelected, andaria-disabledmirrors thedisabledprop, only in theoptionrole. Both are required state on an option and meaningless on alistitem: a plain list row reporting "not selected" would invent a selection the list does not offer.- A group activator row (rendered inside
OrigamListGroupActivator) never getsrole="option"— clicking it only toggles expand/collapse, it never fires a selection (seeOrigamListGroup'srole="group"region).
Tokens
| Variable | Default | Used for |
|---|---|---|
--origam-list-item__title---font-size | 1rem | title font size |
--origam-list-item__title---font-weight | 400 | title font weight |
--origam-list-item__title---letter-spacing | 0.009375em | title letter spacing |
--origam-list-item__title---line-height | 1.5rem | title line height |
--origam-list-item__subtitle---font-size | 0.875rem | subtitle font size |
--origam-list-item__subtitle---font-weight | 400 | subtitle font weight |
--origam-list-item__subtitle---letter-spacing | 0.0178571429em | subtitle letter spacing |
--origam-list-item__subtitle---line-height | 1rem | subtitle line height |
--origam-list-item---min-height | undeclared — 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-hover | 0.08 | overlay opacity of a link row on hover / focus-visible |
--origam-list-item---overlay-opacity-active | 0.12 | overlay opacity of an active row (--active, expanded group activator); set 0 to show the row's bare bgColor |
--origam-list-item---overlay-opacity-active-hover | 0.16 | overlay opacity of an active row on hover / focus-visible |
--origam-list-item---padding-block-start | 8px | top padding |
--origam-list-item---padding-inline-start | 16px | left padding (indent-adjusted) |
--origam-list-item---height-sm / -md / -lg / -xl | 28px / 36px / 44px / 52px | total row height per size rung |
--origam-list-item---padding-block-sm / -md / -lg / -xl | 2px / 6px / 10px / 14px | block padding per size rung |
--origam-list-item--slim---padding-inline-start / -end | 8px / 8px | inline padding when slim is set |