Lily Design System™

ScrollerBase

A low-level scroll position tracking primitive for scrollytelling. ScrollerBase uses IntersectionObserver to track which step is currently active and exposes bindable index and progress values that consumers use to drive visual changes.

This headless component uses a <div> element with an aria-label to create a labeled scrollable region for scrollytelling content.

Example

ScrollerBase
Show demo markup 
<div class="scroller-base" aria-label="a low-level scroll position tracking primitive for scrollytelling">ScrollerBase</div>
Usage example 
<ScrollerBase offset={0.5} bind:index bind:progress>
  <div class="step">Step 1 content</div>
  <div class="step">Step 2 content</div>
  <div class="step">Step 3 content</div>
</ScrollerBase>
Show Svelte source 
// In your Svelte component:
import ScrollerBase from "lily-design-system-svelte-headless/components/ScrollerBase/ScrollerBase.svelte";

<ScrollerBase>
  <!-- content -->
</ScrollerBase>

Usage

<ScrollerBase offset={0.5} bind:index bind:progress>
  <div class="step">Step 1 content</div>
  <div class="step">Step 2 content</div>
  <div class="step">Step 3 content</div>
</ScrollerBase>
<ScrollerBase offset={0.3} bind:index>
  <div class="step">
    <h2>Introduction</h2>
    <p>The story begins here.</p>
  </div>
  <div class="step">
    <h2>Development</h2>
    <p>The plot thickens.</p>
  </div>
</ScrollerBase>

Props

  • children: slot (required) -- scrollable content
  • offset: number (default: 0.5) -- viewport offset (0-1) where step triggers (0=top, 0.5=center, 1=bottom)
  • index: number (bindable, default: 0) -- current active step index
  • progress: number (bindable, default: 0) -- overall scroll progress (0-1)
  • ...restProps: Any additional HTML attributes

Keyboard Interactions

  • Standard scroll behavior
  • Tab navigates between focusable step content

ARIA

  • aria-label for the scrollable region
  • Steps should have appropriate roles as needed by the consumer

When to Use

  • Use as the foundation for custom scrollytelling implementations
  • Use when you need fine-grained control over scroll-driven interactions
  • Use when building a custom scrollytelling layout that does not fit the Scroller foreground/background pattern

When Not to Use

  • Do not use directly when you need the full scrollytelling experience with background/foreground composition -- use Scroller instead
  • Do not use for simple scroll-triggered animations -- use IntersectionObserver directly or a simpler approach

Headless

This component provides a <div> element with IntersectionObserver-based scroll tracking, with zero visual styling. The consumer is responsible for all CSS including step layout, spacing, scroll snap, and any visual indicators of the current step.

Styles

The consumer provides all CSS styling. The component renders with a .scroller-base class for targeting. No default styles are included -- this is a fully headless component.

Testing

  • Verify the component renders a <div> element with class scroller-base
  • Verify aria-label is applied
  • Verify child steps are rendered correctly
  • Verify index updates as steps enter the viewport offset
  • Verify progress updates as the user scrolls
  • Verify pass-through attributes are applied

Advice

  • Designers: Plan step content with clear visual transitions in mind. Each step should represent a meaningful narrative beat. Consider how the viewport offset affects the reading experience.
  • Developers: Always provide a descriptive aria-label for the scrollable region. Use the bindable index and progress values to drive visual changes in sibling or parent components. Choose an appropriate offset value based on content type -- 0.5 (center) works well for most cases.

Implementation Notes

  • Uses <div> element with class scroller-base
  • Tracks scroll position using IntersectionObserver
  • Exposes current step index and overall progress as bindable values
  • Steps are child elements; each child becomes a scrollytelling step
  • Consumer uses index/progress to drive visual changes
  • Offset controls where in the viewport a step triggers (0=top, 0.5=center, 1=bottom)

Related components

  • scroller — see components.tsv
  • scroller-video — see components.tsv
  • visible — see components.tsv

References

  • Reuters Graphics ScrollerBase
  • IntersectionObserver API: https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver

Canonical contract

Generated from this component's canonical metadata — the machine-checked source the implementations are held to.

Metadata

  • Component: scroller-base
  • PascalCase: ScrollerBase
  • Description: a low-level scroll position tracking primitive for scrollytelling
  • Status: beta — implemented and unit-tested in all seven frameworks with an axe-clean demo page; not yet exercised in composed flows
  • HTML tag: <div>
  • CSS class: .scroller-base
  • Interactive: yes

ARIA

  • aria-label for the scrollable region
  • Steps should have appropriate roles

Keyboard

  • Standard scroll behavior
  • Tab navigates between focusable step content

Props

  • children: slot (required) -- scrollable content
  • offset: number (default: 0.5) -- viewport offset (0-1) where step triggers (0=top, 0.5=center, 1=bottom)
  • index: number (bindable, default: 0) -- current active step index
  • progress: number (bindable, default: 0) -- overall scroll progress (0-1)
  • ...restProps: Any additional HTML attributes