Home Reference Source Test Repository

<h1 align="center"> <br/> PaperRipple </h1>

Build Status Code Climate Dependency Status ESDoc Coverage

Material Design Ripple effect in pure JS & CSS.

PaperRipple lets you add a Material Design ripple effect to UI elements.


$ bower install paper-ripple
$ npm install paper-ripple --save

How it looks like

Live example at codepen.


First, you need to include PaperRipple JS and CSS files to your HTML-page.

Assume, you have next HTML:

<button class="paper-button">button</button>
<button class="paper-button blue-text">button</button>
<button class="paper-button orange-text">button</button>

Your JS will look like:

// // Getting all the buttons
var button = document.querySelectorAll('button.paper-button');

// Traversing the buttons
[].forEach.call(buttons, function(button) {
    // New PaperRipple for the button
    var ripple = new PaperRipple();

    // Adding ripple container to the button

    // Subscribing to 'mousedown' and 'mouseup' button events to activate ripple effect
    // when a user clicks on the button.
    button.addEventListener('mousedown', function(ev) {
    button.addEventListener('mouseup', function() {

NOTE: It's important that each element you add the ripple to must be relative position.

If you prefer to work with modules in JS, PaperRipple exports itself in AMD, CommonJS and as global variable if no require or module were found. In addition, under dist\systemjs you may find PaperRipple as SystemJS module.

Even more, if you prefer to work with jQuery you may find jQuery plugin based on PaperRipple under dist folder. So, the previous example may be simplified to the next:



You may pass additional options to the constructor to control PaperRipple behavior:

var ripple = new PaperRipple(cfg);

If you have DOM element you want to use as PaparRipple element, pass it to the constructor. But be careful, PaperRipple element must follow next structure:

<div class="paper-ripple">
    <!-- optional -->
    <div class="paper-ripple__background"></div>

    <!-- optional -->
    <div class="paper-ripple__waves"></div>
var rippleEl = document.querySelector('.paper-ripple'),
    ripple = new PaperRipple(rippleEl);

assert(ripple.$ === rippleEl); // true

Or you may pass object containing next options:

var ripple = new PaperRipple({
    initialOpacity: 0.3,
    recenters: true

Each of these options may be changed after initializing:

ripple.center = true;
ripple.opacityDecayVelocity = 0.7;

NOTE: Changing of $, $background or $waves after initialization not recommended.


Use CSS color property to style the ripple:

.paper-ripple {
    color: #FF9800;

NOTE: CSS color property is inherited so it is not required to set it on the .paper-ripple directly.

If you want to make the rippling effect within a circle, add .paper-ripple--round to main DOM element:

var ripple = new PaperRipple();


Browser Support

NOTE: IE9 doesn't support classList on HTMLElement object and requestAnimationFrame. You need to polyfill it. My choice: classList - bower install classlist or npm install classlist-polyfill; requestAnimationFrame - bower install window.requestanimationframe or npm install window.requestanimationframe.


PaperRipple JS has an excellent documentation. Esdoc is used to generate it. To generate it by yourself do following:

Clone the repo:

$ git clone https://github.com/virtyaluk/paper-ripple.git

Install dependencies:

$ npm install -g gulp && npm install

Generate the docs:

$ gulp docs

Docs will be available under docs folder in the root of the project.

Running tests

Install dependencies:

$ npm install

Run them:

$ gulp test


MIT © Bohdan Shtepan