Ripple

Ripple is a script that adds a ripple effect to most buttons and allows users to add ripples to any element too. Original code from Polymer Project's paper-ripple component.
== ==
== About ==
As described by Material Design, ripples are a visual form of feedback for touch events providing users a clear signal that an element is being touched.
There are three types of ripple motions:
* Default: The ripple emanates from the point of contact and stays there. Found in most ripple surfaces/elements.
* Recentered: The ripple emanates from the point of contact, but it will move to the center of the element during the animation. Usually can be found on small buttons such as those from the classic editor's top toolbar.
* Unbounded: The ripple emanates from the center of the element and stays there. Usually used for circle-shaped elements such as Floating Action Buttons (FABs).
Ripple's duration, color, duration, decay duration, and size are some of the characteristics you can customize to fit your needs and brand/stylistic choices.
== ==
You don't have to do anything besides importing the script to make it work. But you can configurate the script to add more elements to be able to have the ripple effect and you can also change how the ripple itself behaves on certain elements.
=== Adding elements ===
You can allow more elements to have the ripple effect by just creating an object named window.ripplesConfig with any combination of the following properties: normalRipples, recenteredRipples, and/or unboundedRipples. The value of any of these properties should be a NodeList (a list of elements given by the document.querySelectorAll() method).
Each property grants ripples to the matching elements, but their behavior will depend on which category they are set to (see the about section to learn how each category behaves).
TL;DR: An example of a configuration script that uses all three ripple categories looks like this:
window.ripplesConfig = {
 'normalRipples': document.querySelectorAll('.elements-1, .elements-2'),
 'recenteredRipples': document.querySelectorAll('.foo .bar'),
 'unboundedRipples': document.querySelectorAll('.lorem .ipsum')
};
This basically means that:
* Elements with the classes elements-1 and elements-2 will have the default ripple behavior on touch.
* Elements with the classes foo and bar will have a ripple with recentered behavior.
* Elements with the classes lorem and ipsum will have a ripple with unbounded behavior.
Another way is to add any of the following data-attributes to any element to give it a ripple effect on touch without editing any JavaScript:
* [data-ripple] will grant the element a normal ripple.
* [data-recentered] will grant the element a recentered ripple.
* [data-unbounded] will grant the element an unbounded ripple.
An example of each case would be:
Code	Result
 	Touch me!
 	I am re-centered!
 	And I am unbounded!
Another thing you can do is to add a subtle effect when the user is hovering over a ripple surface which may not look like it can trigger such effect. This can be done by using pseudo-classes such as ::before or ::after on a relative-positioned element:
Code 	Result
<tabber>
HTML = 	
Hover and touch me!	
=== Modifying behavior ===
You can change some properties of the ripples on a per-element basis or to groups of elements by using CSS custom properties (variables). To learn what each variable does, go to the API section.
TL;DR: An example of a configuration stylesheet that uses all available variables looks like this:
.nice-button {
 --ripple-config__duration--ms: 1000;
 --ripple-config__end-duration--ms: 500;
 --ripple-config__max-radius--px: 200;
 --ripple-config__min-duration--ms: 600;
 --ripple-config__timing-function: ease;
}
Which means that:
* The element with the nice-button class will have a specific ripple behavior consisting of:
** It's duration will be 1 second (1000ms).
** It's fade-out duration will be half a second (500ms).
** It's maximum radius will be 400px (200 * 2).
** It's minimum duration will be 0.6 seconds (600ms).
** It's timing function will be ease.
Additionally, you can change some visual aspects of it as well:
.nice-button {
 --ripple-color: lime;
 --ripple-border-radius: 0;
 --ripple-opacity: 0.5;
}
Which also means that:
* The element with the nice-button class will have a ripple whose appearance consists of:
** It's color will be lime.
** It will be a square rather than a circle (due to it's border radius being 0).
** It will have an opacity of 50% (0.5).
== ==
== API ==
=== HTML elements ===
Note that you don't have to write any HTML in order to make this script work, but you may want to know the purpose of each generated element.
HTML element	
 	Mandatory. Wraps and limits ripple's location.
 	Mandatory. It's the ripple itself.
=== CSS selectors ===
CSS selector 	
[ripple][data-ripple] 	Selects any element with the ripple attribute. These elements will have a ripple upon script execution.
[recentered][data-recentered]	Selects any element with the recentered attribute. These elements will have a recentered ripple upon script execution.
[unbounded][data-unbounded] 	Selects any element with the unbounded attribute. These elements will have a unbounded ripple upon script execution.
=== CSS variables ===
CSS variable 	
--ripple-config__duration--ms 	Duration (in miliseconds) of the ripple expansion animation. Defaults to, at least, 800ms.
--ripple-config__end-duration--ms	Duration (in miliseconds) of the ripple fade-out animation. Defaults to 150ms (on touch) or 400ms (on key press).
--ripple-config__max-radius--px 	Maximum radius of the ripple (in pixels). Defaults to 300px.
--ripple-config__min-duration--ms	Minimum duration (in miliseconds) of the riple expansion animation. Defaults to 800ms.
--ripple-config__timing-function 	CSS easing function that determines the expansion animation's speed rate. Defaults to cubic-bezier(.2, .9, .1, .9).
--ripple-color 	Determines the ripple's color. Defaults to currentText (the element's current text color).
--ripple-border-radius 	Determines the ripple's border-radius. Defaults to 50% (full circle).
--ripple-opacity 	Determines the ripple's opacity. Defaults to 25%.
--ripple-checked-color 	Determines the ripple's color on checked elements such as checkboxes, radio buttons, and toggles. Defaults to var(--theme-link-color).
--ripple-unchecked-color 	Determines the ripple's color on un-checked elements such as checkboxes, radio buttons, and toggles. Defaults to var(--theme-body-text-color).
--ripple-checked-opacity 	Determines the ripple's opacity on checked elements such as checkboxes, radio buttons, and toggles. Defaults to 20%.
--ripple-unchecked-opacity 	Determines the ripple's opacity on un-checked elements such as checkboxes, radio buttons, and toggles. Defaults to 15%.