[Scrollama]((https://github.com/russellsamora/scrollama) is a JavaScript library for creating general [[Scrollytelling]] stories.
## Getting Started
1. Download the [scrollama repo](https://github.com/russellsamora/scrollama)as zip file, unzip, and paste files into your project repo.
2. Open the project folder in VS Code.
3. Start a Live server to review the templates and watch your changes.
4. Choose a project template to start from (either `basic`, `progress`, `sticky-overlay`, or `sticky-side`).
## Key Concepts
- Each section (with `id="scrolly"` ) is a self-contained scollytelling section. Replicate this to create multiple scrollytelling sections on your page (see the docs for additional help).
- The `div` with `id="sticky-thing"` is the thing that sticks during the scroll session. The content of this `div` is updated in the `handleStepEnter` function. We call this "Sticky Thing".
- The `divs` with `class="step"` in the `article` tag is what scrolls past the sticky thing. We call these "Steps".
- Store the desired content and style of the Sticky Thing at each step in data properties of the Step. Use the `handleStepEnter` function to update the Sticky Thing (see example in the template). Data properties *must* be all lowercase.
## Tips
- Change the `offset` parameter in the `init` function to change when the animation triggers.
- Most styling can be edited in the `style` tag of the template. The `style.css` file only handles styling of the demo and can be removed, edited or replaced with your `style.css` file.
- Use [[template literals]] to update the content of the `sticky-thing`. You can also update style attributes and other features.
- Set the `debug` property of the `init` function to `false` to remove the lines that indicate trigger points.
## Images
A common use case is to have text scroll past an image. You can either set the image as a background image or as a regular image, depending on your need. Background images will resize to fit the frame whereas regular images will not.
### Background images
Use the `background-image` style property to update images in the Sticky Thing. If you need to, adjust the `background-size` and `background-position` properties of `.sticky-thing` within the `style` tag.
```html
// Make these changes in the appropriate locations
// As a background image
<style>
.sticky-thing {
background-size: cover;
background-position: center center;
}
</style>
...
<article>
<div class="step" data-step="1" data-image="path/to/image.png">
</div>
<article>
...
<script>
// scrollama event handlers
function handleStepEnter(response) {
...
sticky.style.backgroundImage = `url(${el.dataset.image})`;
}
</script>
```
### Regular images
Use regular images when resizing is not desired. For the best experience, your images should all be roughly the same size. In this case, create an empty image tag in the `sticky-thing` `div` and update it in the `handleStepEnter` function. Create a new css style for the image and update with properties as needed.
```html
// As a regular image
<style>
.sticky-thing img {
min-width:100%;
}
</style>
...
<article>
<div class="step" data-step="1" data-image="path/to/image.png">
</div>
<article>
<div class="sticky-thing">
<img>
</div>
...
<script>
// scrollama event handlers
function handleStepEnter(response) {
...
stick.querySelector("img").src = el.dataset.image
}
</script>
```
> [!example]- Additional Resources
> - [Russel Goldenburg's YT talk](https://www.youtube.com/watch?v=d7wTA9F-l8c)