Gorres Scrollytelling

Gorres Scrollytelling turns a web page into a story driven by scrolling: scrollytelling.

Scrollytelling (from “scrolling” and “storytelling”) is a way of telling stories on the web in which scrolling itself moves the story forward. Instead of merely moving the page down, every scroll step triggers a change: graphics build up, maps zoom, images change, charts animate to match the text.

With Gorres Scrollytelling, one medium fills the screen and stays in place while the text of the current step scrolls across it. As soon as the next step reaches the middle of the screen, the medium behind it changes.

A story is put together from four kinds of blocks, and it can hold as many of them as it needs:

• Scrollytelling Story — the frame. It holds the layout of the text boxes, the dimming of the media and the length of a step.
• Scrollytelling Step — one step of the story. It carries its own image or video plus any blocks you want as text. A story takes any number of steps. A step without a medium keeps the medium of the step before, so several text boxes can scroll across the same image or video one after the other.
• Scrollytelling Row — optional group of steps inside a story that pass sideways: the screen stays in place and the steps move through it while the visitor keeps scrolling down. Steps before and after the row scroll vertically as usual.
• Scrollytelling Afterword — optional content that follows the last step. Below a stage that is limited to the medium it shows up right under the stage from the first step on, instead of leaving that space empty.

What you can set

• Position of the text boxes: left, center or right, horizontally and vertically, for the whole story or per step
• A text box that stays in place on the screen for the length of its step, for a hint or a headline on top of a medium
• Width of the text boxes in percent of the available column
• Look of a text box per step: background, border, rounded corners, shadow and padding
• Typography per step: font family, size, weight and style, line height, letter spacing, letter case, decoration and text alignment
• How the text boxes appear and disappear: fade, slide, zoom, rotate or dissolve, for the whole story or per step
• Direction: steps scroll up the screen, steps inside a row pass sideways, and a story can mix both
• How a medium fills the screen: crop to fill, or show the whole medium
• With a stage limited to the medium: pull the content after the story up below the stage, so it shows from the first step on
• Dimming of the media so that text stays readable
• Offset from the top, for sites with a fixed menu
• Height of a step, which decides how long its medium stays in place, for the whole story or per step
• Several text boxes in front of one medium: steps without a medium of their own, as close together as you like through their own height
• Cross-fade or instant change between media
• Focal point per medium, so the right part survives the crop
• An image that scrolls away with its step instead of staying in place, for an opening screen that lifts like a curtain
• A second image per step for portrait screens, so a landscape image does not lose its sides on a phone held upright

Built to behave

• No JavaScript library. The front end script is about seven kilobytes, a little over two when compressed, and uses the browser’s own IntersectionObserver.
• Readable without JavaScript. The first medium stays visible and the text follows underneath, so the page never breaks. The steps of a row then simply follow each other.
• Respects reduced motion. No cross-fade, no text effect, no sideways movement and no playing video when the visitor asked for less motion.
• Works with the keyboard. A link or a field in a step of a row that is not on screen yet is brought into view when it receives the focus, and so is a step that a link points to.
• Screen readers get one medium at a time. All media of a story live in the document at once; only the visible one is exposed.
• Sharp images. The plugin calculates the sizes attribute from the aspect ratio of the image, because a screen-high medium needs a wider file than the screen itself.

The online help shows every block and setting live, see the section Documentation.

Documentation

• Online help: a help site that runs in WordPress Playground, in English and German. Every page shows the blocks live, with the settings they describe.
• Source code: the plugin on GitHub.

Source code

The files in build/ are compiled and minified. Their human-readable sources ship with the plugin in the folder src/, one subfolder per block: src/story/, src/step/, src/row/ and src/after/. The complete source code, including the development tools, is public at github.com/jgorres/gorres-scrollytelling-plugin.

The build tool is @wordpress/scripts (webpack); package.json ships with the plugin. To regenerate build/ from src/, run these commands in the plugin folder, with Node.js and npm installed:

1. npm install
2. npm run build

The plugin uses no third-party libraries.