ListItem

Data Display
stable

Single row inside a List. Supports prepend/append icons or avatars, title, subtitle, active state, and polymorphic link rendering.

Preview

Rendering the live preview…

simple

Rendering the live preview…

subtitle

Rendering the live preview…

active

Rendering the live preview…

disabled

Structure

Anatomy

Visual breakdown of the component's internal structure with BEM class call-outs.

Anatomy of OrigamListItemSchematic of the ListItem component with 7 numbered internal parts. prepend title subtitle append 1 2 3 4 5 6 7 origam-list-item ⑦ = overlay — absolute, opacity: 0 at rest, visible on hover/active
Anatomy of <origam-list-item> — 7 internal parts. The grid layout places prepend ② / content ③ / append ⑥ in a 3-column grid. Title ④ and subtitle ⑤ live inside content. The overlay ⑦ is an absolute layer that paints hover/active tints.
1.origam-list-item
Root element. Renders as <div> by default, <a> when href/to is set. Grid container: 3 columns (prepend / content / append).
2.origam-list-item__prepend
Leading icon/avatar zone. grid-area: prepend. Renders prependIcon, prependAvatar, or the #prepend slot. v-if="hasPrepend".
3.origam-list-item__content
grid-area: content. Contains title, subtitle and the #default slot.
4.origam-list-item__title
Primary text. Truncates with ellipsis (white-space: nowrap). v-if="hasTitle".
5.origam-list-item__subtitle
Secondary text. Uses -webkit-box clamp via the lines prop. v-if="hasSubtitle".
6.origam-list-item__append
Trailing icon/avatar zone. grid-area: append. Renders appendIcon, appendAvatar, or the #append slot. v-if="hasAppend".
7.origam-list-item__overlay
Absolute interaction scrim. opacity: 0 at rest → 0.08 on hover/focus → 0.12 when active. Only rendered when the item is clickable or active.

API

Props

All props accepted by this component, with their type, default value and description.

active
boolean
false
Forces the active visual state regardless of router link match or selection.
activeClass
string
Extra CSS class applied when the item is active.
disabled
boolean
false
Disables pointer events and reduces opacity. Sets aria-disabled when rendered as an anchor.
lines
Controls subtitle line-clamp: one-line, two-line, three-line. three-line also aligns prepend/append to the top.
link
boolean
false
Opt into explicit link mode. Adds cursor: pointer, ripple, and keyboard activation even without an href/to.
nav
boolean
false
Compact nav variant — reduces inline padding and adjusts title/subtitle typography.
slim
boolean
false
Reduces the prepend area width for tighter layouts.
subtitle
string | number
Secondary text rendered below the title. Truncated with ellipsis per the lines prop.
title
string | number
Primary text rendered inside the content area. Can also be provided via the #title slot.
value
any
Selectable value when the item is inside a list group. Drives isSelected via useNestedItem.
border
boolean | number | string | TDirectionBoth | Array<TDirectionBoth>
false
Applies a border to the item.
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
id
string
class
string | Array<string> | object
style
string | Array<string> | object | StyleValue
density
'default'
Adjusts vertical padding density via the --origam-list---density variable.
height
number | string
maxHeight
number | string
maxWidth
number | string
minHeight
number | string
minWidth
number | string
width
number | string
elevation
TElevation
Box-shadow elevation token applied to the item.
Border-radius token or boolean applied to the item.
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
size
TSize | number
tag
string
'div'
Root HTML element. Becomes <a> when href or to is set via useLink.
href
string
Renders the item as an anchor tag pointing to this URL.
replace
boolean
Vue Router destination. Automatically renders the item as an anchor using router-link.
exact
boolean
color
Foreground color applied to text and icons.
bgColor
Background color of the item row.
ripple
boolean | { class: string }
true
Enables the Material ripple effect on click when the item is clickable.
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
appendAvatar
string
Image URL for an avatar rendered in the append zone.
appendIcon
MDI or custom icon rendered in the append zone.
prependAvatar
string
Image URL for an avatar rendered in the prepend zone.
prependIcon
MDI or custom icon rendered in the prepend zone.
prependAriaLabel
string
appendAriaLabel
string
hover
boolean | IStateEffectConfig
hoverClass
string
fontSize
TFontSize
fontWeight
TFontWeight
lineHeight
TLineHeight
letterSpacing
TLetterSpacing

API

Slots

Content slots exposed by this component.

#wrapper
Replaces the entire inner layout (prepend / content / append). Use for advanced custom layouts.
#prepend
Replaces the prepend icon/avatar with custom content.
#title
Replaces the default title text rendering.
#subtitle
Replaces the default subtitle text rendering.
#default
Content rendered inside the __content zone, after title and subtitle.
#append
Replaces the append icon/avatar with custom content.

API

Emits

Events emitted by this component.

@click
MouseEvent
Fired on item click (or Enter/Space for keyboard users when the item is clickable).
@click:append
MouseEvent
Fired when the user clicks the append zone.
@click:prepend
MouseEvent
Fired when the user clicks the prepend zone. Propagation is stopped.

API

Exposed members

Properties and methods accessible via template ref (defineExpose). Use them for programmatic control.

boolean
True when this item acts as the activator of a ListGroup. Prevents selection toggling on click.
Ref<boolean>
Reactive selection state from useNestedItem. True when the item value is selected in the parent list.
ListProvide | null
Parent list context injected by OrigamList. Null when the item is used standalone.
(value: boolean, event?: Event) => void
Programmatically select or deselect this item within the parent list.
<T extends object>(props: T, exclude?: string[]) => Partial<T>
Utility to forward a filtered subset of props to a child component.
Ref<string>
Reactive CSS string generated by useStyle from the computed listItemStyles.
() => 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.

Minimum row height. Adjusted by the density modifier.
Block-start padding. Added to the density offset.
Inline-start padding. Added to the indent-padding and density offsets.
Item border radius. Overridden by the rounded prop.
Cursor style when the item is in link/clickable mode.
Opacity applied when the item is disabled.
Overlay opacity. Animates to 0.08 on hover/focus and 0.12 when active.
Title font size. Overridden to 0.8125rem in nav mode.
Subtitle font size.

Inclusion

Accessibility

ARIA roles, keyboard navigation and focus management. Sourced from the real component template.

Keyboard interactions

Keyboard interactions
KeyAction
Enter / SpaceActivates a clickable item (fires click event, navigates, or toggles selection).
TabMoves focus. tabindex=0 for standalone clickable items; tabindex=-2 inside a list group.

Notes

  • When disabled=true and rendered as an anchor, aria-disabled="true" is set instead of the disabled attribute. Pointer events are removed via CSS.
  • When href or to is set, the item renders as a native <a> element — full keyboard navigation and focus management are inherited from the browser.
  • When inside a selectable list (value prop set), selection state is driven by useNestedItem. The active CSS class provides a visual selected indicator.

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
dimension
56px
Default minimum row height.
dimension
var(--origam-space---4)
Default inline-start padding (16px). Added to list indent-padding and density.
color
currentColor
Overlay tint color for hover/active states.
dimension
var(--origam-font__size---lg)
Title font size (1rem).
dimension
var(--origam-font__size---md)
Subtitle font size (0.875rem).

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 items

vue

Title + subtitle

vue

Clickable / link items

vue