ListSubheader
Section heading rendered inside a List. Supports inset indent and sticky positioning.
Preview
Rendering the live preview…
defaultRendering the live preview…
insetRendering the live preview…
stickyStructure
Anatomy
Visual breakdown of the component's internal structure with BEM class call-outs.
<origam-list-subheader> — 2 internal parts. The root ① is a flex container; the inner text element ② truncates with ellipsis.- 1.origam-list-subheader
- Root element. Flex container (align-items: center). Renders as
<div>by default; usetag="h2"–"h6"for semantic sectioning. - 2.origam-list-subheader__text
- Label text wrapper.
overflow: hidden; text-overflow: ellipsis; white-space: nowrap. Rendered only when the title prop or default slot is provided.
API
Props
All props accepted by this component, with their type, default value and description.
- insetbooleanfalse
- Adds an indent (32px) to align with list items that have a prepend icon/avatar.
- stickybooleanfalse
- Makes the subheader stick to the top of the scrollable list container (position: sticky; top: 0).
- titlestring
- Subheader label text. Can also be provided via the default slot.
- idstring
- classstring | Array<string> | object
- stylestring | Array<string> | object | StyleValue
- tagstring'div'
- Root HTML element. Consider using a semantic heading tag (h2–h6) when appropriate.
- color
- Text color override. Defaults to the semantic secondary text color.
- bgColor
- Background color override. Inherits the list background by default.
- 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
- borderboolean | number | string | TDirectionBoth | Array<TDirectionBoth>false
- Applies a border to the subheader element.
- 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 or boolean applied to the subheader.
- roundedTopRightboolean | number | string
- roundedTopLeftboolean | number | string
- roundedBottomLeftboolean | number | string
- roundedBottomRightboolean | number | string
- roundedStartStartboolean | number | string
- roundedStartEndboolean | number | string
- roundedEndStartboolean | number | string
- roundedEndEndboolean | number | string
- fontSizeTFontSize
- fontWeightTFontWeight
- lineHeightTLineHeight
API
Slots
Content slots exposed by this component.
- #default
- Subheader label content. Receives the title prop as a slot binding. Overrides the title prop when provided.
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 to a child component.
- Ref<string>
- Reactive CSS string generated by useStyle from the computed listSubheaderStyles.
- string
- Unique style-sheet ID for this instance.
- () => 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.
- Text color of the subheader label. Defaults to the semantic secondary text color.
- Font size of the subheader label.
- Font weight of the subheader label.
- Minimum height of the subheader row. Transitions with density changes.
- Trailing padding to avoid text running to the edge.
- Line height of the subheader text.
- Indent padding applied when --inset modifier is active. Aligns the label with prepend icons.
- Duration of the min-height transition.
Inclusion
Accessibility
ARIA roles, keyboard navigation and focus management. Sourced from the real component template.
Notes
- For screen-reader accessibility, consider using tag="h2" through "h6" so the subheader is part of the heading outline. The default <div> tag is appropriate when the list is not a standalone section.
- The sticky variant uses position: sticky; top: 0 — the parent list must have overflow: auto or overflow: scroll for this to work correctly.
- The default secondary text color may have reduced contrast. Ensure at least 4.5:1 contrast ratio when customising the color prop.
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__text---secondary)
- Default text color (secondary).
- dimensionvar(--origam-font__size---md)
- Font size (0.875rem).
- dimension40px
- Minimum row height.
- dimension32px
- Indent applied in --inset mode to align with prepend icon items.
- durationvar(--origam-motion__duration---medium)
- Transition duration for min-height changes.
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 subheader
Inset + sticky