Vue Scrollama

A Vue component to easily setup scroll-driven interactions (aka scrollytelling). Uses Scrollama under the hood.

Jump straight to examples here.

Installation

npm install vue-scrollama intersection-observer

Scrollama makes use of IntersectionObserver and you'll want to manually add its polyfill intersection-observer for cross-browser support.

Basic Usage

Any elements placed directly inside a Scrollama component will be considered as steps. As the user scrolls, events will be triggered and emitted which you can handle as required:

• step-enter: when the top or bottom edge of a step element enters the offset threshold
• step-exit: when the top or bottom edge of a step element exits the offset threshold
• step-progress: continually fires the progress (0-1) a step has made through the threshold

Here's a simple example with three <div> elements as steps and a step-enter event

<template>
  <Scrollama @step-enter="stepEnterHandler">
    <div class="step1" data-step="a">...</div> // classes like .step1 are helpful to adjust the style and dimensions of a step
    <div class="step2" data-step="b">...</div> // data-* attributes are helpful to store instructions to be used in handlers
    <div class="step3" data-step="c">...</div>
  </Scrollama>
</template>

<script>
import 'intersection-observer' // for cross-browser support
import Scrollama from 'vue-scrollama'

export default {
  components: {
    Scrollama
  },
  methods: {
    stepEnterHandler ({element, index, direction}) {
      // handle the step-event as required here
      console.log(element, index, direction)
    }
  }
}

<style src="vue-scrollama/dist/vue-scrollama.css"></style>
<style>
/* your styles here */
</style>

NuxtJS Usage

For usage with NuxtJS & for SSR support, you must create a custom NuxtJS plugin.

Create plugin

plugins/scrollama.client.js

import Vue from 'vue';
import 'intersection-observer' // for cross-browser support
import Scrollama from 'vue-scrollama'

Vue.component('Scrollama', Scrollama);

Include in nuxt.config.js

nuxt.config.js

  plugins: [
    { src: '~/plugins/scrollama.client.js' }
  ]

Usage

Use Scrollama in your components/templates, etc.

<template>
  <client-only>
    <Scrollama @step-enter="stepEnterHandler">
      <div class="step1" data-step="a">...</div> // classes like .step1 are helpful to adjust the style and dimensions of a step
      <div class="step2" data-step="b">...</div> // data-* attributes are helpful to store instructions to be used in handlers
      <div class="step3" data-step="c">...</div>
    </Scrollama>
  </client-only />
</template>

<script>
export default {
  methods: {
    stepEnterHandler ({element, index, direction}) {
      // handle the step-event as required here
      console.log(element, index, direction)
    }
  }
}

<style src="vue-scrollama/dist/vue-scrollama.css"></style>
<style>
/* your styles here */
</style>

Sticky Graphic

To add a sticky graphic element (example), place it into a slot with name 'graphic'.

// classes are helpful to adjust the style and dimensions of the graphic
<template>
  <Scrollama @step-enter="stepEnterHandler">
    <div slot="graphic" class="graphic">...</div> 
    <div class="step1" data-step="a">...</div>
    <div class="step2" data-step="b">...</div>
    <div class="step3" data-step="c">...</div>
  </Scrollama>
</template>

Scrollama Options

Props passed to the Scrollama component will be passed on to scrollama's setup method:

• offset: (number, 0 - 1): How far from the top of the viewport to trigger a step. (default: 0.5)
• progress: (boolean): Whether to fire incremental step progress updates or not. (default: false)
• debug: (boolean): Whether to show visual debugging tools or not. (default: false)
• order: (boolean): Whether to preserve step triggering order if they fire out of sync (eg. ensure step 2 enters after 1 exits). (default: true)
• once: (boolean): Only trigger the step to enter once then remove listener. default: false
• threshold: (number, 1+): The granularity of the progress interval, in pixels (smaller = more granular updates). (default: 4)

// example with offset set to 0.8
  <Scrollama @step-enter="stepHandler" :offset="0.8">
      ...
  </Scrollama>
</template>

Styling

If you inspect the DOM elements set up by Scrollama, you'll see three div elements:

• .scrollama-container: overall container
• .scrollama-steps: container for your step elements
• .scrollama-graphic: container for your sticky graphic

Add to/override styles of these as per your requirements.

For higher specificity, passing an id prop to Scrollama will accordingly postfix the ids of the above div elements. See this example on CodeSandbox.

Examples

On CodeSandbox:

• Basic
• Progress
• Sticky Graphic 1
• Sticky Graphic 2

and more.