VirtualScrollItem
Per-item wrapper used by OrigamVirtualScroll — attaches a ResizeObserver to measure its height and emits update:height so the virtual engine can recalculate padding spacers.
Structure
Anatomy
Visual breakdown of the component's internal structure with BEM class call-outs.
<origam-virtual-scroll-item> — 2 render modes. In wrapper mode (①) the component renders a .origam-virtual-scroll-item div with the default slot. In renderless mode (②) no root element is rendered — the consumer binds itemRef to its own element.- 1.origam-virtual-scroll-item
- Wrapper div rendered when
renderless=false(default). Observed by ResizeObserver via theresizeRefbinding. Emitsupdate:heighton any height change. - 2#renderless slot
- When
renderless=trueno wrapper is rendered. TheitemRefslot prop must be bound to the consumer element so ResizeObserver can observe it.
API
Props
All props accepted by this component, with their type, default value and description.
- renderlessbooleanfalse
- When true the component renders no wrapper element — instead it exposes a renderless slot with an itemRef binding for the consumer's root element to be observed by ResizeObserver.
API
Slots
Content slots exposed by this component.
- #default
- Item content rendered inside the wrapper div (non-renderless mode). The wrapper div itself is observed by ResizeObserver.
- #renderless
- Only available when renderless=true. Provides the itemRef template-ref callback that must be bound to the consumer's root element so ResizeObserver can observe it.
API
Emits
Events emitted by this component.
- @update:heightnumber
- Fired whenever the ResizeObserver detects a height change on the item element. The virtual engine uses this value to update its intrinsic-size cache.
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.
- string
- Unique style-sheet ID for this instance.
- () => void
- Injects the computed style sheet into the document.
- () => void
- Removes the injected style sheet.
- 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.
- Estimated item height used by the virtual engine for initial layout. Overridden at runtime via the update:height event.
- Duration for item appear/disappear transitions. Fast to avoid jank during rapid scrolling.
Inclusion
Accessibility
ARIA roles, keyboard navigation and focus management. Sourced from the real component template.
Notes
- OrigamVirtualScrollItem has no ARIA role — it is a transparent measurement wrapper. ARIA semantics are entirely determined by the consuming content in the default/renderless slot.
- In renderless mode the component renders no DOM element — the consumer's own element carries all semantic roles. This makes renderless mode the preferred approach for accessible list items (use a native <li> as the observed element).
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.
- dimension48px
- Default estimated item height used by the virtual engine for initial layout.
- duration{motion.duration.fast}
- Duration for item transitions.
- cubicBezier{motion.easing.standard}
- Easing for virtual scroll item transitions.
Usage
Examples
Ready-to-paste code snippets for your templates.
Within a VirtualScroll (internal usage)
Renderless mode (advanced)
Ecosystem
Family
Components from the same folder that share conventions and often compose together.