TypeScript icon, indicating that this package has built-in type declarations

4.1.1 • Public • Published


A scrollyteller component for React


The scrollyteller takes a series of panels of content nodes and turns them into a series of elements which scroll over the <Scrollyteller> component's children.

The panels prop is in the format of:

    data: {
      info: 'Some kind of config that is given when this marker is active'
    nodes: [<DOM elements for this panel>]
    data: {
      thing: 'This will be given when the second marker is hit'
    nodes: [<DOM elements for this panel>]

When a new box comes into view onMarker will be called with the data of the incoming panel.

import * as React from 'react';
import Scrollyteller from '@abcnews/scrollyteller';

// Some kind of dockable visualisation that goes with the scrolling text
import GraphicOfSomeKind from './GraphicOfSomeKind';

export default () => {
  const [something, setSomething] = React.useState('');
  const [progressPct, setProgresPct] = React.useState('');

  // Content is loaded somehow into an array of { data: {...}, nodes: [...DOMNodes] }
  const panels = ...?

  return (
      onMarker={({thing}) => setSomething(data.thing)}
      onProgress={({pctAboveFold}) => setProgress(pctAboveFold)}>
      <GraphicOfSomeKind property={something} />

For a more complete example using Typescript see the vanilla example app.


The Scrollyteller can take a panelClassName prop which it will pass to each panel component for customising the look. It can also take firstPanelClassName and lastPanelClassName props which it will pass to the respective panel components, for customising their specific looks.

To completely customise how panels are rendered you can pass in panelComponent. The main requirement for this component is that it calls props.reference with a ref to its outermost wrapper.

import * as React from 'react';

interface Props {
  nodes: HTMLElement[];
  reference: (el: HTMLElement) => void;

export default (({nodes, reference}): Props) => {
  const base = React.useRef(null);
  const innerBase = React.useRef(null);

  React.useEffect(() => {
    nodes.forEach((node: HTMLElement) => {
  }, [reference]);

  return (
    <div ref={base} style={{ zIndex: 1, height: '80vh', fontSize: '40px' }}>
      <strong>THIS IS A PANEL:</strong>
      <div ref={innerBase} />

And then specify <Scrollyteller panelComponent={CustomPanel}>.

Usage with Odyssey

When developing ABC News stories with Odyssey you can use the loadScrollyteller function to gather panels within a CoreMedia article.

See a more complete usage example with Odyssey in the example project.

CoreMedia text:

This is the opening paragraph panel
This is a second panel
This is another paragraph

JS Code:

import Scrollyteller, { loadScrollyteller } from '@abcnews/scrollyteller';

const scrollyData = loadScrollyteller(
  "",       // If set to eg. "one" use #scrollytellerNAMEone in CoreMedia
  "u-full", // Class to apply to mount point u-full makes it full width in Odyssey
  "mark"    // Name of marker in CoreMedia eg. for "point" use #point default: #mark

// Then pass them to the Scrollyteller component
  <Scrollyteller panels={scrollyData.panels} {...scrollyData.config} />,

// You could also use React Portals to mount on the mount node
  <Scrollyteller ... />,


This project uses tsdx for build/dev tooling and np for release management.

The recommended workflow is to run TSDX in one terminal:

npm start

This builds to /dist and runs the project in watch mode so any edits you save inside src causes a rebuild to /dist.

Then run the example inside another:

cd example
npm i
aunty serve

The example imports and live reloads whatever is in /dist, so if you are seeing an out of date component, make sure TSDX is running in watch mode as recommended above.

To do a one-off build, use npm run build.

To run tests, use npm test or yarn test.


Mostly to aid development and demonstrate usage, there is an example project in /example. It uses aunty as the build tool to match the usual ABC News interactive development work flow.


Jest tests are set up to run with npm test or yarn test.

Bundle analysis

Calculates the real cost of your library using size-limit with npm run size and visulize it with npm run analyse.


To release a new version to NPM run npm run release and follow the prompts.


Jest tests are set up to run with npm test or yarn test.

Bundle analysis

Calculates the real cost of your library using size-limit with npm run size and visulize it with npm run analyze.


Please see the main tsdx optimizations docs. In particular, know that you can take advantage of development-only optimizations:

// ./types/index.d.ts
declare var __DEV__: boolean;

// inside your code...
if (__DEV__) {


See the full list of contributors.




Package Sidebar


npm i @abcnews/scrollyteller

Weekly Downloads






Unpacked Size

159 kB

Total Files


Last publish


  • ashkyd
  • jtfell
  • phocks
  • andrewkesper
  • drzax