Awesome Open Source
Awesome Open Source

mutation-watcher
PaperRipple v0.3.0

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.

๐Ÿ“€ Install

Bower:
$ bower install paper-ripple
NPM:
$ npm install paper-ripple --save

How it looks like

Live example at codepen.

๐Ÿ“‹ Usage

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
	button.appendChild(ripple.$);

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

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:

$('button.paper-button').paperRipple();

Configuration

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>
</div>
var rippleEl = document.querySelector('.paper-ripple'),
	ripple = new PaperRipple(rippleEl);

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

Or you may pass object containing next options:

  • initialOpacity: Number - Defaults to 0.25. The initial opacity of the each wave.
  • opacityDecayVelocity: Number - Defaults to 0.8. How fast (opacity per second) the wave fades out.
  • recenters: Boolean - Defaults to false. If true, waves will exhibit a gravitational pull towards the center of their container as they fade away.
  • center: Boolean - Defaults to false. If true, waves will center inside its container.
  • round: Boolean - Defaults to false. If true, ripple effect will apply within a circle.
  • target: HTMLElement - Defaults to null. Target DOM element as the container for the waves.
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.

Styling

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.

๐Ÿ“— Browser Support

  • Chrome
  • Firefox
  • Safari
  • Opera
  • IE9+

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.

๐ŸŽ“ Docs

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

๐Ÿ“† Changelog

0.2.0 (December 07, 2015)

  • Added new round property on main PaperRipple class.

0.3.0 (June 01, 2017)

๐Ÿ“— License

Licensed under the MIT license.

Copyright (c) 2017 Bohdan Shtepan


modern-dev.com ย ยทย  GitHub @virtyaluk ย ยทย  Twitter @virtyaluk


Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
javascript (68,711)ย 
css (7,240)ย 
animation (1,042)ย 
material-design (654)ย 
js (521)ย 
jquery (520)ย 
material (373)ย 
effect (32)ย 
ripple (29)ย 
wave (22)ย 

Find Open Source By Browsing 7,000 Topics Across 59 Categories

Advertising ๐Ÿ“ฆย 10
All Projects
Application Programming Interfaces ๐Ÿ“ฆย 124
Applications ๐Ÿ“ฆย 192
Artificial Intelligence ๐Ÿ“ฆย 78
Blockchain ๐Ÿ“ฆย 73
Build Tools ๐Ÿ“ฆย 113
Cloud Computing ๐Ÿ“ฆย 80
Code Quality ๐Ÿ“ฆย 28
Collaboration ๐Ÿ“ฆย 32
Command Line Interface ๐Ÿ“ฆย 49
Community ๐Ÿ“ฆย 83
Companies ๐Ÿ“ฆย 60
Compilers ๐Ÿ“ฆย 63
Computer Science ๐Ÿ“ฆย 80
Configuration Management ๐Ÿ“ฆย 42
Content Management ๐Ÿ“ฆย 175
Control Flow ๐Ÿ“ฆย 213
Data Formats ๐Ÿ“ฆย 78
Data Processing ๐Ÿ“ฆย 276
Data Storage ๐Ÿ“ฆย 135
Economics ๐Ÿ“ฆย 64
Frameworks ๐Ÿ“ฆย 215
Games ๐Ÿ“ฆย 129
Graphics ๐Ÿ“ฆย 110
Hardware ๐Ÿ“ฆย 152
Integrated Development Environments ๐Ÿ“ฆย 49
Learning Resources ๐Ÿ“ฆย 166
Legal ๐Ÿ“ฆย 29
Libraries ๐Ÿ“ฆย 129
Lists Of Projects ๐Ÿ“ฆย 22
Machine Learning ๐Ÿ“ฆย 347
Mapping ๐Ÿ“ฆย 64
Marketing ๐Ÿ“ฆย 15
Mathematics ๐Ÿ“ฆย 55
Media ๐Ÿ“ฆย 239
Messaging ๐Ÿ“ฆย 98
Networking ๐Ÿ“ฆย 315
Operating Systems ๐Ÿ“ฆย 89
Operations ๐Ÿ“ฆย 121
Package Managers ๐Ÿ“ฆย 55
Programming Languages ๐Ÿ“ฆย 245
Runtime Environments ๐Ÿ“ฆย 100
Science ๐Ÿ“ฆย 42
Security ๐Ÿ“ฆย 396
Social Media ๐Ÿ“ฆย 27
Software Architecture ๐Ÿ“ฆย 72
Software Development ๐Ÿ“ฆย 72
Software Performance ๐Ÿ“ฆย 58
Software Quality ๐Ÿ“ฆย 133
Text Editors ๐Ÿ“ฆย 49
Text Processing ๐Ÿ“ฆย 136
User Interface ๐Ÿ“ฆย 330
User Interface Components ๐Ÿ“ฆย 514
Version Control ๐Ÿ“ฆย 30
Virtualization ๐Ÿ“ฆย 71
Web Browsers ๐Ÿ“ฆย 42
Web Servers ๐Ÿ“ฆย 26
Web User Interface ๐Ÿ“ฆย 210