legitRipple.js

A jQuery plugin for legit Material-Design ripple effects.<br> <br> <img src="https://raw.githubusercontent.com/matthias-vogt/legitRipple.js/gh-pages/demo-media/demo.gif" alt="Demo" height="90"> <br> Demo: https://matthias-vogt.github.io/legitRipple.js/

Lightweight: <2kb gzipped
Configurable: Lots of options, custom HTML, custom CSS (custom transition durations)
CSS based: Smooth CSS transitions
Legit: Nice interaction, Glorious multi-touch

Usage

legitRipple.js depends on jQuery, so make sure you have that loaded. When the DOM is ready, you can use it like this:

//ripple with default options
$(".some, .elements").ripple();

//ripple with custom options
$(".elements").ripple({
  scaleMode: false,
  maxDiameter: "100%"
});

You can also use alternative syntax if you have a lot of ripple elements with different options.

$.ripple({
  ".material": {},
  ".material.circle": {maxDiameter: "100%"},
  ".customHTML": {template: $("<p/>").text("Custom ripple content!")},
  ".callback": {
    callback: function($container, $ripple, posI, maxDiameter) {
      //is called whenever the ripple's css properties change
    }
  }
});

You can't apply the ripple effect on void elements (those that can't have child elements; <img>, <input>, …). However, you can simply wrap them and apply the effect to the wrapper element.

Install

<link href="stylesheet" type="text/css" href="ripple.min.css">
<script src="jquery.min.js"></script>
<script src="ripple.min.js"></script>

For better loading performance, I'd recommend loading the script as non-critical content (by putting the <script> and <style> tags at the end of the body tag). Please also consider concatenating it with your other dependencies.

Install and update easily using bower:

bower install --save legitripple

Options

| Option | Description | Expected Input | Default | |-------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------|-----------| | maxDiameter | Gives the ripple a max-width. adaptPos: true requires this to be in %; can be any unit with adaptPos: false. 100% for circles. | Number with unit as String ("100%" or "3.125em") | false | | dragging | Whether the ripple should be able to be dragged. | Boolean | true | | adaptPos | Whether to take the mouse position relative to the ripple-container's dimensions into account when positioning the ripple. Note: more info on "adaptPos" | Boolean | true | | scaleMode | How to scale the ripple while dragging:<br><br>"proportional": Proportional to the amount it was dragged. Will probably become much bigger than its container.<br><br>"fixed": Don't scale and release ripple while dragging upwards.<br><br>falsey values: Don't scale while dragging | String or falsey value | "fixed" | | template | Set the HTML content of ripples. See: custom ripple element. | NodeList, Element or true when the template is in the HTML markup | null | | fixedPos | Gives the ripple a fixed position in the parent. | true for centered position or Array with x- and y-coordinates relative to the parent's offset (e.g. [20, 40] = x: 20px, y: 40px) | false | | allowDragging | HTML5 dragging is disabled on ripple elements by default for nicer interaction. | Boolean | false | | unbind | When set, unbinds all of the ripple's event handlers. Doesn't remove any elements or classes. (see Destroying, unbinding and overwriting) | Boolean | false | | touchDelay | Time to delay triggering of ripples on touch devices (e.g. to enable scrolling past ripple elements without triggering ripples) | Time in ms as number | 100 | | callback | A function to be called each time the ripple element's style property changes | function | null |

Coming soon

| Option | Description | Expected Input | Default | |----------------------|-------------------------------------------------------------------|--------------------------------------------|---------| | rippleOnHover | Whether to use the ripple as a hover effect | Boolean | false | | destination | An element other than the clicked one the ripple should travel to | NodeList, Element or selector String or Array of coordinates in px | null |

Destroying, unbinding and overwriting

Ripples can be overwritten as you'd expect:

$(".ripple").ripple();
$(".ripple.noScale").ripple({scaleMode: 0});
//.ripple has default options
//.ripple.noScale has default options and {scaleMode: 0}

$(".ripple.noScale").ripple({scaleMode: 0});
$(".ripple").ripple();
//.ripple and ripple.noScale have default options

You can also unbind event handlers from ripples or destroy all ripples.

$(".ripple").ripple({unbind: true});
//removes all event handlers from a ripple element.
//if you call it during a ripple animation, the animation
//will still complete

$.ripple.destroy();
//stops any ripple animations in their tracks and removes any
//plugin created elements, classes and event bindings.
//calling .ripple() will still work

Custom ripples

Custom CSS

Ripples can be targeted using the .legitRipple-ripple class, their containers using .legitRipple. CSS selectors for ripples shouldn't be order-specific to target all ripples since there can be multiple ripples active in an element at once.

.container .legitRipple-ripple {
    background: yellow;
    /* You can change the transition properties too!
       Just don't try and change the width transition's easing. */
    transition-duration: .15s, .9s; /*width, opacity*/
}

Custom elements

You can even use custom elements for ripples by setting the template option with an Element or NodeList as the value, like template: $("<p/>").text("Look, ma, I'm custom!").

Alternatively, you can set the template option to true and add the following markup to your HTML:

<div>
    Container Element
    <div class="legitRipple-template">Your custom element</div>
</div>

How the code will look when a ripple is triggered:

<div class="legitRipple">
    Container Element
    <div class="legitRipple-template">Your custom element</div>
    <span class="legitRipple-ripple legitRipple-custom">
        <div>Your custom element</div>
    </span>
</div>

The custom element is used as a template and will be hidden by CSS on load. When a ripple is triggered, the custom element will be .clone()'d, the legitRipple-template class removed and wrapped in a <span/> with a legitRipple-ripple class before being appended to the ripple container.

By default, when using custom ripple elements, each direct child o

LegitRipple.js

Install / Use

README