ListItem
Single row inside a List. Supports prepend/append icons or avatars, title, subtitle, active state, and polymorphic link rendering.
Preview
Rendering the live preview…
simpleRendering the live preview…
subtitleRendering the live preview…
activeRendering the live preview…
disabledStructure
Anatomy
Visual breakdown of the component's internal structure with BEM class call-outs.
<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. RendersprependIcon,prependAvatar, or the#prependslot.v-if="hasPrepend". - 3.origam-list-item__content
grid-area: content. Contains title, subtitle and the#defaultslot.- 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-boxclamp via thelinesprop.v-if="hasSubtitle". - 6.origam-list-item__append
- Trailing icon/avatar zone.
grid-area: append. RendersappendIcon,appendAvatar, or the#appendslot.v-if="hasAppend". - 7.origam-list-item__overlay
- Absolute interaction scrim.
opacity: 0at 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.
- activebooleanfalse
- Forces the active visual state regardless of router link match or selection.
- activeClassstring
- Extra CSS class applied when the item is active.
- disabledbooleanfalse
- 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.
- linkbooleanfalse
- Opt into explicit link mode. Adds cursor: pointer, ripple, and keyboard activation even without an href/to.
- navbooleanfalse
- Compact nav variant — reduces inline padding and adjusts title/subtitle typography.
- slimbooleanfalse
- Reduces the prepend area width for tighter layouts.
- subtitlestring | number
- Secondary text rendered below the title. Truncated with ellipsis per the lines prop.
- titlestring | number
- Primary text rendered inside the content area. Can also be provided via the #title slot.
- valueany
- Selectable value when the item is inside a list group. Drives isSelected via useNestedItem.
- borderboolean | number | string | TDirectionBoth | Array<TDirectionBoth>false
- Applies a border to the item.
- borderTopboolean | number | string
- borderLeftboolean | number | string
- borderBottomboolean | number | string
- borderRightboolean | number | string
- borderBlockboolean | number | string
- borderInlineboolean | number | string
- borderInlineStartboolean | number | string
- borderInlineEndboolean | number | string
- borderBlockStartboolean | number | string
- borderBlockEndboolean | number | string
- borderColorstring
- borderStylestring
- borderTopColorTColor
- borderRightColorTColor
- borderBottomColorTColor
- borderLeftColorTColor
- borderInlineStartColorTColor
- borderInlineEndColorTColor
- borderBlockStartColorTColor
- borderBlockEndColorTColor
- idstring
- classstring | Array<string> | object
- stylestring | Array<string> | object | StyleValue
- Adjusts vertical padding density via the --origam-list---density variable.
- heightnumber | string
- maxHeightnumber | string
- maxWidthnumber | string
- minHeightnumber | string
- minWidthnumber | string
- widthnumber | string
- elevationTElevation
- Box-shadow elevation token applied to the item.
- Border-radius token or boolean applied to the item.
- roundedTopRightboolean | number | string
- roundedTopLeftboolean | number | string
- roundedBottomLeftboolean | number | string
- roundedBottomRightboolean | number | string
- roundedStartStartboolean | number | string
- roundedStartEndboolean | number | string
- roundedEndStartboolean | number | string
- roundedEndEndboolean | number | string
- sizeTSize | number
- tagstring'div'
- Root HTML element. Becomes <a> when href or to is set via useLink.
- hrefstring
- Renders the item as an anchor tag pointing to this URL.
- replaceboolean
- Vue Router destination. Automatically renders the item as an anchor using router-link.
- exactboolean
- color
- Foreground color applied to text and icons.
- bgColor
- Background color of the item row.
- rippleboolean | { class: string }true
- Enables the Material ripple effect on click when the item is clickable.
- paddingboolean | number | string
- paddingTopboolean | number | string
- paddingLeftboolean | number | string
- paddingBottomboolean | number | string
- paddingRightboolean | number | string
- paddingBlockboolean | number | string
- paddingInlineboolean | number | string
- paddingInlineStartboolean | number | string
- paddingInlineEndboolean | number | string
- paddingBlockStartboolean | number | string
- paddingBlockEndboolean | number | string
- marginboolean | number | string
- marginTopboolean | number | string
- marginLeftboolean | number | string
- marginBottomboolean | number | string
- marginRightboolean | number | string
- marginBlockboolean | number | string
- marginInlineboolean | number | string
- marginInlineStartboolean | number | string
- marginInlineEndboolean | number | string
- marginBlockStartboolean | number | string
- marginBlockEndboolean | number | string
- appendAvatarstring
- Image URL for an avatar rendered in the append zone.
- appendIcon
- MDI or custom icon rendered in the append zone.
- prependAvatarstring
- Image URL for an avatar rendered in the prepend zone.
- prependIcon
- MDI or custom icon rendered in the prepend zone.
- prependAriaLabelstring
- appendAriaLabelstring
- hoverboolean | IStateEffectConfig
- hoverClassstring
- fontSizeTFontSize
- fontWeightTFontWeight
- lineHeightTLineHeight
- letterSpacingTLetterSpacing
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.
- @clickMouseEvent
- Fired on item click (or Enter/Space for keyboard users when the item is clickable).
- @click:appendMouseEvent
- Fired when the user clicks the append zone.
- @click:prependMouseEvent
- 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
| Key | Action |
|---|---|
| Enter / Space | Activates a clickable item (fires click event, navigates, or toggles selection). |
| Tab | Moves 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.
- dimension56px
- Default minimum row height.
- dimensionvar(--origam-space---4)
- Default inline-start padding (16px). Added to list indent-padding and density.
- colorcurrentColor
- Overlay tint color for hover/active states.
- dimensionvar(--origam-font__size---lg)
- Title font size (1rem).
- dimensionvar(--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
Title + subtitle
Clickable / link items