Skip to content

Parallax documentation

Jump to bottom
Shishir Phadke edited this page Feb 24, 2022 · 2 revisions

Parallax JS uses GSAP Plugins. Specifically, Timeline and ScrollTrigger.

Installation

There are few options on how to include/import Parallax into your project:

Use Parallax Core CSS and JS Files from CDN

Parallax Js requires following 3 Gsap Plugins for its functionality to work correctly.

  • GSAP's core library

    • The GreenSock Animation Platform (GSAP) animates anything JavaScript can touch (CSS properties, SVG, React, canvas, generic objects, whatever) and solves countless browser inconsistencies, all with blazing speed (up to 20x faster than jQuery).

  • GSAP's ScrollTrigger plugin

    • ScrollTrigger creates scroll-based animations with minimal code or trigger anything scroll-related, even if it has nothing to do with animation.

  • GSAP's EasePack plugin

    • SlowMo is a configurable ease that produces a slow-motion effect that decelerates initially, then moves linearly for a certain portion of the ease (which you can choose) and then accelerates again at the end; it’s great for effects like zooming text onto the screen, smoothly moving it long enough for people to read it, and then zooming it off the screen.
<script src="https://cdnjs.cloudflare.com/ajax/libs/gsap/3.9.1/gsap.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/gsap/3.9.1/ScrollTrigger.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/gsap/3.9.1/EasePack.min.js"></script>

Registering GSAP Plugins

Since we are loading GSAP via a <script> tag (i.e. not a build tool) GSAP will attempt to auto-register the plugins as long as the core has already loaded, but the documentation still recommends registering plugins so that build tools don't drop them during tree shaking.

We can register all our plugins at once, like:

gsap.registerPlugin(ScrollTrigger, SlowMo);

Include UNDP specific Parallax CSS and JS

In addition to Parallax's Core JS files, we may need to add some custom styles to set Parallax custom components.

<link rel="stylesheet" href="dist/css/base-minimal.min.css"/>
<link rel="stylesheet" href="dist/css/components/cta-link.min.css"/>

Based on the Parallax Cards component, use the following corresponding minified CSS in your HTML.
(Kindly note that below example is based on Parallax Cards and you need not include the swiper related files for parallax js to work.)

<link rel="stylesheet" href="dist/css/components/parallax-cards.min.css"/>
<link rel="stylesheet" href="dist/css/components/parallax-card.min.css"/>
<link rel="stylesheet" href="dist/css/components/swiper.min.css"/>

Include the Parallax specific JS

<script src="dist/js/parallax.min.js"></script>
<script src="dist/js/swiper.min.js"></script>

Add Parallax HTML Layout

Now, we need to add basic Parallax layout to our HTML:

<!-- Parallax main container -->
<div class="parallax-card">
  <!-- Parallax child elements -->
  <div clas="parallax-card__image">Image 1</div>
  <div clas="parallax-card__content">Title and Description 1</div>
</div>

<div class="parallax-card">
  <div clas="parallax-card__image">Image 2</div>
  <div clas="parallax-card__content">Title and Description 2</div>
</div>

<div class="parallax-card">
  <div clas="parallax-card__image">Image 3</div>
  <div clas="parallax-card__content">Title and Description 3</div>
</div>

<div class="parallax-card">
  <div clas="parallax-card__image">Image 4</div>
  <div clas="parallax-card__content">Title and Description 4</div>
</div>

<div class="parallax-card">
  <div clas="parallax-card__image">Image 5</div>
  <div clas="parallax-card__content">Title and Description 5</div>
</div>

Initialize Parallax

Finally, we need to initialize Parallax JS:

The parallaxEffect() method accepts 7 arguments in UNDP, and all parallax options except trigger and selector are optional.

parallaxEffect(trigger, selector, start, end, direction, device, percent)

Following are the arguments that can be passed in the parallax funtion.

Argument Type Default Available Options Description
trigger CSSSelector null null String with CSS selector of the element that will work like "trigger" container for selector on page scroll and whose position in the normal document flow is used to calculate where the ScrollTrigger starts.
selector CSSSelector null null String with CSS selector of the element that will be the selector on which parallax will work.
start String | Number | Function 'top bottom' For all available options, refer start property in ScrollTrigger create document. The ScrollTrigger's starting scroll position (numeric, in pixels). This value gets calculated when the ScrollTrigger is refreshed, so anytime the window/scroller gets resized it'll be recalculated.
You can read more here
end String | Number | Function 'bottom top' For all available options, refer end property in ScrollTrigger create document. The ScrollTrigger's ending scroll position (numeric, in pixels). This value gets calculated when the ScrollTrigger is refreshed, so anytime the window/scroller gets resized it'll be recalculated.
You can read more here
direction string 'horizontal' 'horizontal' | 'vertical' Custom option for setting the scroll direction for UNDP's custom implementation.
device string 'desktop' 'desktop' |'all' Custom option for setting the device breakpoint for Parallax to work. This is also for UNDP's custom implementation.
percent string 'pixels' 'pixels' | 'percent' Custom option which sets the GSAP to translateY in either pixel or percent.

These options are javascript objects that can directly be passed as function argument.

Example use of the Parallax Js method (Parallax Cards in following case):

<script>
  // Parallax Card Init
  parallaxEffect('.parallax-card', ['.parallax-card__image', '.parallax-card__content'], 'top center', 'bottom+=85 center', 'vertical', 'desktop', 'percent')

  // Swiper Init
  swiper('.parallax__content');
</script>

For more extensive technical documentation and examples you can refer to GSAP Documentation

Clone this wiki locally