luncheon/ripplet.js

Fully controllable vanilla-js material design ripple effect generator.

Fully controllable vanilla-js material design ripple effect generator.
This can be used with any JavaScript framework and/or any CSS framework.

Demo

Installation

npm

$ npm i ripplet.js

import ripplet from 'ripplet.js';

element.addEventListener('pointerdown', ripplet);

CDN (jsDelivr)

<script src="https://cdn.jsdelivr.net/npm/[email protected]"></script>
<button onpointerdown="ripplet(arguments[0])">Click me!</button>

Download directly

Download ripplet.min.js

API

ripplet(targetSuchAsPointerEvent, options?) => HTMLElement

Generate a ripple effect.

Parameters

• targetSuchAsPointerEvent: Object (required) (in most cases, pass the received PointerEvent object)

Property name	Description
currentTarget	Target element
clientX	Client x-coordinate of center of ripplet
clientY	Client y-coordinate of center of ripplet

• options: Object (optional)

Property name	Default	Description
className	""	Class name to be set for the ripplet element (not for this library to use, but for user to style that element)
color	"currentColor"	Ripplet color that can be interpreted by browsers. Specify null if the color or image of the ripple effect is based on the CSS className above. If the special value "currentColor" is specified, the text color of the target element (getComputedStyle(currentTarget).color) is used.
opacity	0.1	Ripplet opacity between 0 and 1.
spreadingDuration	".4s"	As its name suggests.
spreadingDelay	"0s"	As its name suggests.
spreadingTimingFunction	"linear"	As its name suggests. See https://developer.mozilla.org/docs/Web/CSS/transition-timing-function
clearing	true	Whether or not to clear automatically. If false is specified, the ripple effect should be cleared using ripplet.clear(currentTarget)
clearingDuration	"1s"	As its name suggests.
clearingDelay	"0s"	As its name suggests.
clearingTimingFunction	"ease-in-out"	As its name suggests. See https://developer.mozilla.org/docs/Web/CSS/transition-timing-function
centered	false	Whether to force the origin centered (and ignore clientX and clientY).
appendTo	"auto"	"auto" | "target" | "parent" | CSS selector string like "body". Specify the element to which the ripple effect element will be appended. If "auto" is specified, it will be the target or its closest ancestor that is not an instance of HTMLInputElement, HTMLSelectElement, HTMLTextAreaElement, HTMLImageElement, HTMLHRElement or SVGElement.

Return value

Generated element.

ripplet.clear(currentTarget?, generatedElement?) => void

Fade out and remove the ripplet. Use only when the option clearing is false.

Parameters

• currentTarget: Element (optional)

The target element that was passed to ripplet(). If this parameter is not passed, all the ripplets will be cleared.

• generatedElement: Element (optional)

The generated element that was returned by ripplet(). If this parameter is not passed, all the ripplets (of the currentTarget above) will be cleared.

Example

<button
  onpointerdown="ripplet(arguments[0], { clearing: false })"
  onpointerup="ripplet.clear(this)"
  onpointerleave="ripplet.clear(this)"
>Keep pressing!</button>

ripplet.defaultOptions

You can change the default ripplet options for your app.
For example:

import ripplet from 'ripplet';

ripplet.defaultOptions.color = 'rgb(64, 128, 255)';

Declarative Edition

If you don't need detailed control, you can use declarative edition that captures pointerdown events.
Load "ripplet-declarative.js" and add data-ripplet attribute to html elements with/without options.
Elements dynamically appended also have the ripple effect if data-ripplet attribute is available.

In declarative edition, the ripple effect remains until the pointerup or pointerleave event occurs.

Example Usage

<script src="https://cdn.jsdelivr.net/npm/[email protected]/umd/ripplet-declarative.min.js"></script>
<!-- <script>ripplet.defaultOptions.color = 'rgb(0, 255, 0)';</script> -->

<button data-ripplet>Default</button>
<button data-ripplet="color: rgb(64, 192, 255); spreading-duration: 2s; clearing-delay: 1.8s;">Sky Blue Slow</button>

or

import 'ripplet.js/es/ripplet-declarative';
// require(ripplet.js/umd/ripplet-declarative.min');

// import { defaultOptions } from 'ripplet.js/es/ripplet-declarative';
// defaultOptions.color = 'rgb(255, 128, 0)';

or

Download ripplet-declarative.min.js

Tips

I recommend applying following styles to the ripple target elements:

1. Erase tap highlight effect for mobile devices
2. Disable tap-to-hover behavior and double-tap-to-zoom behavior for mobile devices

/* Example for the declarative edition */
[data-ripplet] {
  -webkit-tap-highlight-color: transparent; /* 1 */
  touch-action: manipulation; /* 2 */
}

License

WTFPL

ripplet.js's Issues

Ripple doesn't work on bootstrap modal

Hi,

Whenever I put a ripple inside of a bootstrap modal, it does not display on the button. This is maybe because on bootstrap model, it has z-index of 240 so the ripple could maybe be just below the modal or something.

Also, I love this library, thanks for making it!

transform animation not playing on chrome in react

Not sure how I am misusing this library, but everything looks and behaves correctly on Firefox. When using on chrome, however, the transform animation will not play. The opacity animation seems to play fine. What is odd is that the demo site plays fine on chrome. I assume the demo site is running the same 0.3.0 version.

Sometimes the ripple just flickers instead of 'ripples'?

Sometimes in my tests on Angular apps, when clicking on an element that has implemented ripplet.js it will just flicker instead of have the ripple effect, as though it recognizes the click but it skips the ripple animation. Do you have any ideas about how I might fix this?

Option to set class for parent of ripple element

It would be nice to have an option to set the class for the parent of the ripple effect, which can be set with the option className already. This would make styling much easier.

Various ripple effects

Hi,
first of all, awesome work you did !
Far better than every other ripple library.

I am working on my Bootstrap buttons : https://djibe.github.io/material/docs/4.4/material/buttons/

• I want a dark ripple on every button.
• I want a light ripple on btn-primary, btn-secondary, btn-info, etc ...
• I want a customized colored ripple on each btn-outlined-* and btn-flat-*

How can I declare these in Javascript ?

I started with

ripplet.defaultOptions.color = 'rgba(0, 0, 0, 0.12)';

let buttonsRippleArr = document.querySelectorAll('.btn:not([disabled])');

buttonsRippleArr.forEach(function(elem) {
  elem.addEventListener('mousedown', ripplet);
});

But I don't know how to create custom declarations for various components.

Thanks for your help and impressive work.

Disable right click for ripple effect?

Hi, is there a way to disable the ripple effect for right click events, to only allow left click and touch input?
Thank you!

Do not despawn ripple element until mouseup is triggered

As per the material design guidelines, the ripple effect should not be removed until the mouse is lifted.

Example: https://vuetifyjs.com/en/directives/ripples/#ripple-directive

RTL support

When using ripplet in RTL container, the ripple X position is off.
This can be fixed with adding a 'direction' option:

export const defaultOptions = {
  ...
  direction: 'ltr' as string | null, // ltr as default
}

and then changing line 117 to:

/^rtl$/i.test(options.direction!) ? rippletStyle.marginRight = `${targetRect.right - clientX - radius}px` : rippletStyle.marginLeft = `${clientX - targetRect.left - radius}px`

FeatureRequest: Append to targetElement

would it be possible to add the feature to append the ripple to the events targetElement?