Svelte Scrollyteller

A scrollyteller component for Svelte. Svelte port of the ABC News React Scrollyteller.

Installation

npm install @abcnews/svelte-scrollyteller

Add aunty config to package.json:

"aunty": {
  "type": "svelte",
  "build": {
    "entry": [
      "index"
    ],
    "includedDependencies": [
      "@abcnews/svelte-scrollyteller"
    ]
  }
}

Usage

The scrollyteller takes an array 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: 'Any arbitrary data, returned to you when this marker is active'
    },
    align: 'left', // optional: align the panels to the left or right
    panelClass: 'my-custom-target', // optional: in case you want to style it manually
    nodes: [<DOM elements for this panel>]
  },
  {
    data: {
      thing: 'Config when this second marker is hit'
    },
    nodes: [<DOM elements for this panel>]
  }
]

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

<script lang="ts">
	import Scrollyteller from '@abcnews/svelte-scrollyteller';
	import MyGraphic from 'MyGraphic.svelte';

  let {panels} = $props();
  let marker = $state(0);
  let progress = $state();

</script>

<Scrollyteller
	{panels}
	onMarker={({ detail }) => {
		marker = detail;
	}}
	onProgress={({ detail }) => {
		progress = detail;
	}}
  layout={{
    align: 'left',
    // resizeInteractive: true
    // transparentFloat: true
  }}
>
	<MyGraphic marker="{marker}" />
</Scrollyteller>

<style lang="scss">
// Optionally create a ratio box for your graphic. It will self-centre itself
// into the appropriate space when resizeInteractive=true
.myGraphic{
  aspect-ratio: 16/9;
  height: 100%;
  width: unset;
  @container (max-aspect-ratio:16/9) {
    width: 100%;
    height: auto;
  }
}
 </style>

For a more complete example using Typescript see the examples.

Props

| Property | Type | Description | Default | | --------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | | panels | Refer to Usage | required Array of nodes and data which dictate the markers | | onMarker | callback function | required Called when a marker intersects and returns that markers data | | | onProgress | callback function | Fires on scroll and returns the scrollyteller progress | | | customPanel | Svelte Component | Component to replace the default panel component | Panel.svelte | | observerOptions | IntersectionObserverInit | Options for the intersection observer. Refer to the docs | {threshold: 0.5} |

Using layouts/styling your own

The layout={} prop controls how the scrollyteller is laid out, and has the following options:

| Property | Type | Description | | ----------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | align | string | Alignment for blocks. One of left/right/centre/none. "none" applies no breakpoint styling so you can do your own custom styles. | | resizeInteractive | boolean | Defaults to true if not set. This handles the scrollyteller graphic position according to the current breakpoint. | | transparentFloat | boolean | Defaults to true if align is left or right. Removes the block background for left/right aligned pieces, for a better reading experience. | | mobileVariant | string | Toggle mobile betwen:blocks: traditional block layout scrolling over the vizrows: split screen layout with viz on top and text below |

The resizeInteractive prop lets you opt into predefined graphic sizes and placements. When enabled, the graphic will appear toward the top on mobile, and in the centre when left/right aligned. On mobile this allows the most space for blocks to scroll without hitting the graphic, and looks aesthetically pleasing on desktop/larger portrait tablets like the iPad Pro.

The graphic slot has position:relative set, uses flexbox to put its contents into the correct spot, and allows you to use container queries to size your interactive. This works best when your interactive fits itself to its container and reserves only the space it needs. See the examples above for some example code using aspect-ratio to fit an interactive to the graphic slot, although you could use any number of methods.

You can opt out of the resizeInteractive behaviour if you want to use your own styles, at which point you can take over the entire screen.

Changing block styles

The scrollyteller inherits the light/dark colour scheme from Odyssey.

The Svelte Scrollyteller also uses the following CSS variables that you can set anywhere in the DOM above the scrollyteller:

| Attribute | Variable to use | Fallback value | | ----------------------- | -------------------------- | ----------------------- | | background-color | --color-panel-background | dark/light mode variant | | Text colour | --color-panel-text | dark/light mode variant | | Background opacity | --color-panel-opacity | 1 | | Background CSS filter | --color-panel-filter | blur(2.5px) | | Background border | --color-panel-border | none |

You can also specify a panelClass class and style the panels manually (see Usage above).

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.

CoreMedia text:

#scrollytellerVARIABLEvalue
This is the opening paragraph panel
#markVARIABLEvalue
This is a second panel
#markVARval
This is another paragraph
#endscrollyteller

JS Code:

import { loadScrollyteller } from "@abcnews/svelte-scrollyteller";
import App from "App.svelte";

/** Optionally, specify generics to type your markers */
type MyPanelData = {
  electorate: string;
  viz: "map" | "hex" | "chart";
};

const scrollyData = loadScrollyteller<MyPanelData>(
  "", // 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
);

new App({
  target: scrollyData.mountNode,
  props: { panels: scrollyData.panels },
});

Usage with other non-Svelte frameworks

The scrollyteller is available as a Web Component for use in other frameworks. See README.WebComponent.md for more info.

Development

The Svelte components are packaged using SvelteKit svelte-package.

The Web Component is built separately using Vite with the vite-webcomponents.config.js config.

Add #debug=true to your story to enable debug mode and clearly outline each section, block, breakpoint, and observer trigger point.

Get started

git clone [email protected]:abcnews/svelte-scrollyteller.git
cd svelte-scrollyteller
npm i
npm run dev

This will get a SvelteKit app to use for development and testing up and running.

Releasing new versions

npm run release

This will:

• install dependences
• build
• test
• lint
• bump version
• commit
• publish to npm