ListItem

Data Display
stable

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

Aperçu

Rendu de l’aperçu en cours…

simple

Rendu de l’aperçu en cours…

subtitle

Rendu de l’aperçu en cours…

active

Rendu de l’aperçu en cours…

disabled

Structure

Anatomie

Décomposition visuelle de la structure interne du composant avec les appels de classes BEM.

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

Toutes les props acceptées par ce composant, avec leur type, valeur par défaut et 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

Emplacements de contenu exposés par ce composant.

#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

Événements émis par ce composant.

@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

Membres exposés

Propriétés et méthodes accessibles via ref template (defineExpose). Utilisés pour le contrôle programmatique.

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.

Personnalisation

Variables CSS

Propriétés CSS personnalisées exposées par ce composant. Surchargez-les pour personnaliser sans perdre la compatibilité avec le thème.

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

Accessibilité

Rôles ARIA, navigation clavier et gestion du focus. Sourcé depuis le template réel du composant.

Interactions clavier

Interactions clavier
ToucheAction
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.

Fondation

Design tokens

Extrait des tokens de ce composant — les variables --origam-<composant>---<propriété>, déclarées dans sa feuille de tokens tenue à la main, sans étape de build.

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).

Interactif

Playground

Modifiez les props en direct et observez le composant se mettre à jour. Le snippet de code généré suit vos changements.

Rendu de l’aperçu en cours…

Usage

Exemples

Extraits de code prêts à coller dans vos templates.

Basic items

vue

Title + subtitle

vue

Clickable / link items

vue