ListItem
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…
simpleRendu de l’aperçu en cours…
subtitleRendu de l’aperçu en cours…
activeRendu de l’aperçu en cours…
disabledStructure
Anatomie
Décomposition visuelle de la structure interne du composant avec les appels de classes BEM.
<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
Toutes les props acceptées par ce composant, avec leur type, valeur par défaut et 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
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.
- @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
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
| Touche | 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.
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.
- 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).
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
Title + subtitle
Clickable / link items