revealer.js
demonstration | GitHub | npm | donate | @craigbuckler | craigbuckler.com
revealer.js reveals an element with a CSS animation when it is scrolled into view.
Please use the code as you wish. Tweet me @craigbuckler if you find it useful and donate toward development if you use it commercially.
- shows attention-grabbing animations
- fast loading, high performance, uses Intersection Observers
- fully customisable - any CSS reveal effect can be applied
- small: 665 bytes of JavaScript, 185 bytes of CSS (minimum)
- works in all modern browsers (not IE)
- safe progressive enhancement - will not break older browsers
- animation can be disabled by user
- easy to use
Usage instructions
Include the minified CSS and JavaScript anywhere in your page. Typically, the CSS is loaded in the HTML <head> and the JS is loaded just before the closing </body> tag:
CDN URLs are shown above but you can also npm i revealer.js to install via npm and use a bundler.
Then add a data-revealer="class" attribute to any element you wish to animate into view, e.g.
Main titleFive class animations are provided: up, down, left, right, and zoomup, but more can be added.
A CSS prefers-reduced-motion media query disables animations according to user preference.
Custom delays
By default, a delay of at least 300 milliseconds occurs between each element animation. So, if three elements are scrolled into view at the same time, the first animates immediately, the second after 300ms, and the third after 600ms.
An optional data-delay="M" attribute on the same element sets a custom delay to M milliseconds. For example, data-delay="0" on three elements scrolled into the viewport at the same time would animate all immediately.
Custom animations
An element is initially hidden by applying the .revealer class which sets opacity: 0.
When the element is scrolled into view, the class defined by the data-revealer attribute is applied, e.g. data-revealer="up" applies the up class which triggers an animation defined by the .revealer.up selector in the CSS.
Animations should generally set animation-fill-mode: forwards to ensure the animation ends at the state defined by the last (100%) keyframe. That last keyframe should also set the final opacity.
Example from revealer.css:
@ 100% }The element is unobserved once it has been revealed so it remains in-place.
Advanced configuration
revealer.js defines the following configuration variables in a cfg object which can be changed:
cfg.name- attribute data name (defaultrevealer)cfg.delay- attribute data delay (defaultdelay)cfg.threshold- proportion of element visible before triggering animation (default0.6- element must be at least 60% in viewport)cfg.minDelay- minimum delay between each animation unless set with data-delay (default300milliseconds)
The Intersection observer options can also be changed if necessary:
root- root element (defaultnullfor viewport)margin- margin around root element (default0px)
Further considerations
Avoid using revealer.js on large elements where it is not possible to show 60% of the item on-screen so the revealing animation is never triggered.
Version history
v1.1.0, 16 March 2020
prefers-reduced-motionmedia query
v1.0.1, 12 June 2019
- size and performance optimisation
- build update
v1.0.0, 30 May 2019
- Gulp.js minification
- published on npm, CDN information
v1.0.0, 19 April 2019
- Initial commit