RippleTouch

Touch with a ripple especially for ES6 supported browsers.

Ripple, ripple, ripple. A ready-to-use, no cofiguration needed web component for modern browsers. 3.89kb (v8.1491.0, minified) in total, followed up with JSDoc syntax, it's fast and elegant. That's it.

Index 😃

• Example
• Usage
• Configuration
• Notes
• Support
• License

---

Example

Click the image above or here to see the demo. Typical code:

<div class="ripples" style="background: #03dac5;" Ripple>
  Ripples?
</div>

and script (dynamic import):

let Ripple;
import('./Ripple.min.js')
  .then((module) => {
    Ripple = module.default;
    Ripple.load();
  });

Usage

Preparation: Click here to download the latest Ripple.zip asset directly, or go to the release page to choose another version of it.

Install

First, extract Ripple.min.js to wherever you want.

Second, add attribute [Ripple] to select the elements which has the effect. Example:

<button Ripple>Boom</button>

Finally, import it from where you extracted it and call Ripple.load. For standard import method using static import statement, remember to give the <script> a type="module", otherwise the import statement will be unusable.

// <scrip src="example.js" type="module"></script> in example.html
// Below is example.js
import Ripple from './lib/Ripple.min.js';
Ripple.load();

or use a function-like dynamic import() like the example does. It's recommended. type="module" is needless there. Done. 😉

Update

Extract the latest achieve to where you stored Ripple.min.js and overwrite it. In most cases, it's done.

From v8.1482.0 or older:

Pay attention to Ripple.markWord. It's called Ripple.mark now.

From v7.1479.1 or older:

Check files whose name starts with Ripple to delete obsolete one. From v7.1479.2, there should only be one file, Ripple.min.js or Ripple.js, in your project folder.

Configuration

Unnecessary but well-tested adjustments in the latest release.

Limit Scope

Post an element to Ripple.load after importing the module:

// ... (Imported Ripple object)
const earth = document.getElementById('earth');
Ripple.load(earth);

Elements outside earth will have no ripple effects even if it has a [Ripple] attribute. RippleTouch uses event listeners to set up effects, and the listeners will be added to the element specified. If no element been posted, document.body will take its place.

Limiting scope may improve performance because outside it will not examine whether the element user interacted has [Ripple] or not anymore. You can use Ripple.load many times to extend scope for different parts of your page. But usually, a single execution without parameter is totally enough.

Avoid Variable Conflicts

[Ripple] identity can be changed. If other HTML or CSS use the same word, change it before the first run of Ripple.load may avoid unexpected behavior. Example here:

// ... (Imported Ripple object but executed Ripple.load)
Ripple.mark += Math.floor(Math.random() * 10 ** 10).toString();
Ripple.load();

// Turn some elements to a lake.
const buttons = document.getElementsByTagName('button');
buttons.forEach((ele) => ele.setAttribute(Ripple.mark, ''));
// ...

Then buttons will be like:

<button Ripple3663492410>Shakalaka</button>

Style Properties

These css custom properties can be changed by Ripple.set at anytime:

styleProperties = {
  initialScale: 0.6,
  backgroundColor: 'rgba(0,0,0,.06)',
  runningDuration: '300ms',
  opacityDuration: '83ms',
};

• At the beginning of the animation, the diameter of ripple is 60% of the longer between the width and height in default. If I want it smaller:

  Ripple.set({ initialScale: 0.3 });

• Ripples' background color is rgba(0, 0, 0, 0.06) in default. Defined by backgroundColor. The same method as initialScale to change it.

• Ripples will enlarge for 300ms until it filled up the element in default. Defined by runningDuration.

• All opacity changes last for 83ms in default. Defined by opacityDuration.

Notes

Suggestions and imperfections in the latest release.

Use dynamic import

If you use static import statement to import modules, you will be UNABLE to access them outside the <script> marked type="module". So, in my personal views, use dynamic import always if there is no need to consider such a small browser compatibility difference. (For example, Chrome leaves 61-63 and Firefox leaves 60-67 away, according to MDN.)

Ignore it if you use tools like Babel.

Determine the mark before load

Stylesheets will be generated and appended to document.body with Ripple.mark at the first execution of Ripple.load.

Changing the word afterwards seems meaningless. So the mark is forced unwritable once Ripple.load has executed.

Ripple.mark = 'Ripple1683247813';
Ripple.load();

// Will not change.
// At strict mode, throws a TypeError:
// "mark" is read-only.
// And will not change, either.
Ripple.mark = 'Ripple2347119623';

One ripple at the same time

Haven't been well-adjusted for mobile devices.

• It can only make one ripple at the same time. Use two fingers touch at the two blocks in the demo, you will get it. There isn't a plan to fix it for now.

Support

Issues will be opened soon. 😛

License

RippleTouch is MIT licensed.