Documentation

This page contains the documentation for Ripple and how to use it.

Options

The options are important if you want to customize Ripple to your needs.

There are 2 different sets of options in Ripple: Global options and Trigger options.

Global options


							//	These are the default options.
							let options = {
								'debug': false,
								'ripple': {
									'duration': 225,
									'delay': 200,
									'disabledAttribute': true,
									'disabled': false,
									'centered': false,
									'copyBorderRadius': true,
									'keyboardTrigger': [' ', 'Enter'],
									'helperClass': true,
									'container': '.ripple-container',
									'target': false
								}
							}

							//	Initializes Ripple with custom options.
							Ripple.initialize(options)

Note: All of these properties are optional and their values can be omitted or undefined. If a property is omitted it will be set to its default value as shown below.

Option Default value Description Accepts
debug false Exposes the Ripple.effect Object which could be useful to developers. Boolean
ripple Options for ripple effects. Object
ripple.duration 225 Ripple effect duration in milliseconds. Number
ripple.delay 200 Time to wait before showing the ripple effect on touch hold (to prevent showing the effect when the user wants to scroll the page) in milliseconds. Number
ripple.disabledAttribute true Disables the ripple effect if the trigger or target elements contain the disabled HTML attribute. Boolean
ripple.disabled false Disables the ripple effect. Boolean
ripple.centered false Makes the ripple effects appear from the center of their parent elements. Boolean
ripple.copyBorderRadius true Copies the border radius CSS property value from the target element and applies it to the ripple container. Boolean
ripple.keyboardTrigger 
[' ', 'Enter']
 Keyboard keys that will trigger a ripple effect on a focused element when pressed. False means keyboard keys won't trigger a ripple effect. Array, String or false
ripple.helperClass true Adds .ripple-helper-class class name to the target element while it is "rippling". Boolean
ripple.container '.ripple-container' Class name that the ripple container will have. If an element inside the target element matches the class name it will be used instead. False or empty string means no container. String or false
ripple.target false Makes another element ripple instead of the targeted one. False means the targeted element will ripple. Array, String, Element or false

Trigger options

Trigger options inherit options from Global options' ripple property. 


							//	If we want specific elements to have different options from
							//	the global options we can only specify the options that we
							//	want to change as shown below.
							let noContainerOptions = {
								'container': false
							}

							//	Attach ripple to '.no-container' class name elements with
							//	no container options.
							Ripple.attach('.no-container', noContainerOptions)

Properties

In Ripple there are 3 objects that can be accessed: Ripple.options, Ripple.triggerClasses and Ripple.triggerElements.

Ripple.options (read only)

Ripple.options object contains a full list of the global options for the current instance of Ripple.

Ripple.options object is frozen (read only) which means that it is impossible to change its values for the current instance of Ripple. Changing the global options more than once is considered to be a bad practice and can only be done by reinitializing Ripple.

Ripple.triggerClasses

Ripple.triggerClasses object contains a list of objects that have the names of currently attached class list triggers.

Each one of the class list trigger objects contain a nested 'ripple' object containing only the options that differ from the global options' 'ripple' object. 


							//	This is an example on what `Ripple.triggerClasses` could look like.
							
							{
								"ripple-effect": {
									"ripple": {}
								},
								"no-container": {
									"ripple": {
										"container": false
									}
								}
							}

Ripple.triggerElements

Ripple.triggerElements object is very similar to Ripple.triggerClasses object where the only difference is that the objects inside of Ripple.triggerElements object are named with a 16 character long string of random uppercase and lowercase characters and there is a new object 'elements' containing the elements that should trigger the effect. 


							//	This is an example on what `Ripple.triggerElements` could look like.
							
							{
								"fLxabfQdgnYLmgzs": {
									"ripple": {},
									"elements": [HTMLElement] // Array of HTMLElements.
								}
							}

Methods

In Ripple there are a few methods that provide the basic functionality of creating Ripple effects.

Ripple.initialize(options)

Initializes Ripple with optional options.

Arguments:

  • options (optional) - An Object that provides a way of configuring Ripple.

							//	Enable debug mode.
							let options = {
								'debug': true
							}

							//	Initializes Ripple with debug mode option.
							Ripple.initialize(options)

Note: Calling Ripple.initialize() function multiple times will automatically reinitialize Ripple.

Ripple.deinitialize()

Removes the event listeners that are responsible for creating Ripple effects. 


							//	Stop listening for events.
							Ripple.deinitialize()

Ripple.attach(elements, options)

Attaches elements to Ripple with optional options.

Arguments:

  • elements - A String, HTMLElement or Array of class names and/or elements that should be able to ripple.
  • options (optional) - An Object that provides a way of configuring Ripple for this trigger only.

							//	Attaches a Ripple trigger with custom options.

							//	Class name trigger.
							Ripple.attach('.first-element', {'target': '.second-element'})

							//	HTMLElement trigger.
							Ripple.attach(document.querySelector('.first-element'), {'target': '.second-element'})

							//	Array with a class name trigger. (Arrays can contain HTMLElements too)
							Ripple.attach(['.first-element'], {'target': '.second-element'})

Note: If using an HTMLElement when attaching a Ripple trigger, the element will not ripple if it has been replaced in the DOM.

Ripple.detach(elements)

Detaches elements from Ripple.

Arguments:

  • elements - A String, HTMLElement or Array of class names and/or elements that should no longer be able to ripple.

							//	Removes a Ripple trigger.

							//	Class name trigger.
							Ripple.detach('.button')

							//	HTMLElement trigger.
							Ripple.detach(document.querySelectorAll('.icon-button'))

							//	Array of triggers.
							Ripple.detach(['.first-element', document.querySelectorAll('.icon-button')])