DataList
Semantic description list (<dl>) with two layout modes: avatar (icon + title/text stacked) and kv (key/value rows aligned side-by-side).
Structure
Anatomy
Visual breakdown of the component's internal structure with BEM class call-outs.
<origam-data-list> in avatar mode (left) and kv mode (right). Avatar mode renders a <dl> with <dt> titles and <dd> text rows. KV mode renders a key/value grid layout.- 1.origam-data-list
- Root element. Renders as
<dl>in avatar mode,<div>in kv mode. Background, padding and border-radius from tokens. - 2.origam-data-list__title
<dt>element. Hosts theOrigamDataTitlewith its prepend avatar/icon and text. Only in avatar mode.- 3.origam-data-list__text (first)
<dd>elements. Each text row rendered byOrigamDataText. Stacked below the title in avatar mode.- 4.origam-data-list__text (nth)
- Additional text rows. Multiple rows are stacked vertically within the item.
- 5.origam-data-list__kv-value
<dd>element for the value in kv mode. Right-aligned. Accepts inline components (Chip, Avatar…).- 6.origam-data-list__kv-key
<dt>element for the key in kv mode. Width fixed by--origam-data-list__kv---key-width. Muted colour.
API
Props
All props accepted by this component, with their type, default value and description.
- modeTDataListMode'avatar'
- Layout mode. 'avatar' renders icon+title/text stacks; 'kv' renders key/value rows aligned side-by-side.
- items| Array<IDataItem> | { [key: string]: IDataItem } | Array<IDataListKVItem> | { [key: string]: IDataListKVItem }
- Data source. Shape depends on mode: avatar items use IDataItem; kv items use IDataListKVItem. Accepts arrays or keyed objects.
- idstring
- classstring | Array<string> | object
- stylestring | Array<string> | object | StyleValue
- appendAvatarstring
- appendIconTIcon
- prependAvatarstring
- Default avatar image URL for every item prepend area.
- prependIcon
- Default icon for every item prepend area (can be overridden per-item).
- prependAriaLabelstring
- appendAriaLabelstring
- color
- Text/foreground colour applied to the list.
- bgColor
- Background colour of the list.
- marginboolean | number | string
- Margin shorthand applied to the list container.
- 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
- paddingboolean | number | string
- Padding shorthand applied to the list container.
- 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
- Vertical padding density for each item.
- borderboolean | number | string | TDirectionBoth | Array<TDirectionBoth>false
- Adds a border around the list and bottom dividers between items.
- 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
- Border-radius token applied to the list container.
- roundedTopRightboolean | number | string
- roundedTopLeftboolean | number | string
- roundedBottomLeftboolean | number | string
- roundedBottomRightboolean | number | string
- roundedStartStartboolean | number | string
- roundedStartEndboolean | number | string
- roundedEndStartboolean | number | string
- roundedEndEndboolean | number | string
- elevationTElevation
- Box-shadow elevation of the list container.
- fontSizeTFontSize
- fontWeightTFontWeight
- lineHeightTLineHeight
- letterSpacingTLetterSpacing
API
Slots
Content slots exposed by this component.
- #default
- Full override of the list content. Use when the items prop is not sufficient.
- #key
- #value
- #item
- #item.title
- Custom title renderer for avatar-mode items. Receives the item data and its index.
- #item.title.append
- Custom append area inside the title row (avatar-mode).
- #item.title.prepend
- Custom prepend area inside the title row (avatar-mode).
- #item.text
- Custom text renderer for each text row inside an avatar-mode item.
- #item.text.append
- #item.text.prepend
API
Exposed members
Properties and methods accessible via template ref (defineExpose). Use them for programmatic control.
- <T extends object>(props: T, exclude?: string[]) => Partial<T>
- Utility to forward a filtered subset of props.
- Ref<string>
- Reactive CSS string for the injected style sheet.
- string
- Unique style-sheet ID for this instance.
- () => void
- Injects the style sheet into the document.
- () => void
- Removes the style sheet from the document.
- Ref<boolean>
- True once the style sheet has been injected.
Customisation
CSS variables
CSS custom properties exposed by this component. Override them to customise the component without losing theme compatibility.
- Root list background colour.
- Root list foreground colour.
- List container border-radius.
- Font size of avatar-mode title rows.
- Font weight of avatar-mode title rows.
- Text colour of avatar-mode title rows.
- Fixed width of the key column in kv mode.
- Text colour of kv-mode keys.
- Text colour of kv-mode values.
- Bottom border colour between kv rows.
Inclusion
Accessibility
ARIA roles, keyboard navigation and focus management. Sourced from the real component template.
ARIA roles
Notes
- Avatar mode renders a semantic <dl> with <dt> (term/title) and <dd> (definition/text) elements. This provides native screen-reader association between key and value without ARIA.
- KV mode also uses <dl>/<dt>/<dd> structure, which is the recommended HTML pattern for key/value pairs. Do not use a <table> unless the data is truly tabular (multiple columns with a column header).
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.
- colorvar(--origam-color__surface---default)
- Root list background.
- fontWeightvar(--origam-font__weight---medium)
- Title row font weight.
- dimension160px
- Fixed width of the key column in kv mode.
- colorvar(--origam-color__border---subtle)
- Row bottom border colour in kv mode.
- colorvar(--origam-color__surface---overlay)
- Item background on hover.
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.
Avatar mode (default)
Key/value mode
Custom title slot
Ecosystem
Family
Components from the same folder that share conventions and often compose together.