@loipham/material-ripple v14.0.4

Ripple

MDC Ripple provides the JavaScript and CSS required to provide components (or any element at all) with a material "ink ripple" interaction effect. It is designed to be efficient, uninvasive, and usable without adding any extra DOM to your elements.

MDC Ripple also works without JavaScript, where it gracefully degrades to a simpler CSS-Only implementation.

Design & API Documentation

Installation

npm install @loipham/material-ripple

Usage

A ripple can be applied to a variety of elements to represent interactive surfaces. Several MDC Web components, such as Button, FAB, Checkbox and Radio, also use ripples.

A ripple can be added to an element through either a JavaScript or CSS-only implementation. When a ripple is initialized on an element using JS, it dynamically adds a mdc-ripple-upgraded class to that element. If ripple JS is not initialized but Sass mixins are included on the element, the ripple uses a simpler CSS-only implementation which relies on the :hover, :focus, and :active pseudo-classes.

CSS Classes

Sass APIs

In order to fully style the ripple effect for different states (hover/focus/pressed), the following mixins must be included:

• surface, for base styles
• Either radius-bounded or radius-unbounded, to appropriately size the ripple on the surface
• Either the basic or advanced states mixins, as explained below

Using basic states mixins

@use "@loipham/material-ripple";

.my-surface {
  @include ripple.surface;
  @include ripple.radius-bounded;
  @include ripple.states;
}

Using advanced states mixins

.my-surface {
  @include ripple.surface;
  @include ripple.radius-bounded;
  @include ripple.states-base-color(black);
  @include ripple.states-opacities((hover: .1, focus: .3, press: .4));
}

These APIs use pseudo-elements for the ripple effect: ::before for the background, and ::after for the foreground.

Ripple Mixins

NOTE: It is mandatory to include either radius-bounded or radius-unbounded. In both cases, $radius is optional and defaults to 100%.

Basic States Mixins

NOTE: Each of the mixins above adds ripple styles using the indicated color, deciding opacity values based on whether the passed color is light or dark.

NOTE: The states-activated and states-selected mixins add the appropriate state styles to the root element containing &--activated or &--selected modifier classes respectively.

NOTE: $has-nested-focusable-element defaults to false but should be set to true if the component contains a focusable element (e.g. an input) inside the root element.

Advanced States Mixins

When using the advanced states mixins instead of the basic states mixins, every one of the mixins below should be included at least once.

These mixins can also be used to emit activated or selected styles, by applying them within a selector for &--activated or &--selected modifier classes.

NOTE: $has-nested-focusable-element defaults to false but should be set to true if the component contains a focusable element (e.g. an input) inside the root element.

DEPRECATED: The individual mixins states-hover-opacity($opacity), states-focus-opacity($opacity, $has-nested-focusable-element), and states-press-opacity($opacity) are deprecated in favor of the unified states-opacities($opacity-map, $has-nested-focusable-element) mixin above.

Sass Functions

MDCRipple

The MDCRipple JavaScript component allows for programmatic activation / deactivation of the ripple, for interdependent interaction between components. For example, this is used for making form field labels trigger the ripples in their corresponding input elements.

To use the MDCRipple component, first import the MDCRipple JS. Then, initialize the ripple with the correct DOM element.

const surface = document.querySelector('.my-surface');
const ripple = new MDCRipple(surface);

You can also use attachTo() as an alias if you don't care about retaining a reference to the ripple.

MDCRipple.attachTo(document.querySelector('.my-surface'));

NOTE: Surfaces for bounded ripples should have the overflow property set to hidden, while surfaces for unbounded ripples should have it set to visible.

MDCRippleAdapter

NOTE: When implementing browserSupportsCssVars, please take the Safari 9 considerations into account. We provide a supportsCssVariables function within the util.js which we recommend using, as it handles this for you.

MDCRippleFoundation

Tips/Tricks

Using a sentinel element for a ripple

Usually, you'll want to leverage ::before and ::after pseudo-elements when integrating the ripple into MDC Web components. If you can't use pseudo-elements, create a sentinel element inside your root element. The sentinel element covers the root element's surface.

<div class="my-component">
  <div class="mdc-ripple-surface"></div>
  <!-- your component DOM -->
</div>

Unbounded ripple

You can set a ripple to be unbounded, such as those used for MDC Checkboxes and MDC Radio Buttons, either imperatively in JS or declaratively using the DOM.

Using JS

Set the unbounded property on the MDCRipple component.

const ripple = new MDCRipple(root);
ripple.unbounded = true;

Using DOM

Add a data-mdc-ripple-is-unbounded attribute to your root element.

<div class="my-surface" data-mdc-ripple-is-unbounded>
  <p>A surface</p>
</div>

MDCRipple with custom functionality

Usually, you'll want to use MDCRipple along with the component for the actual UI element you're trying to add a ripple to. MDCRipple has a static createAdapter(instance) method that can be used to instantiate a ripple within any MDCComponent that requires custom adapter functionality.

class MyMDCComponent extends MDCComponent {
  constructor() {
    super(...arguments);
    const foundation = new MDCRippleFoundation({
      ...MDCRipple.createAdapter(this),
      isSurfaceActive: () => this.isActive, /* Custom functionality */
    });
    this.ripple = new MDCRipple(this.root, foundation);
  }
}

Handling keyboard events for custom UI components

Different keyboard events activate different elements. For example, the space key activates buttons, while the enter key activates links.

MDCRipple uses the adapter.isSurfaceActive() method to detect whether or not a keyboard event has activated the surface the ripple is on. Our vanilla implementation of the adapter does this by checking whether the :active pseudo-class has been applied to the ripple surface. However, this approach will not work for custom components that the browser does not apply this pseudo-class to.

To make your component work properly with keyboard events, you'll have to listen for both keydown and keyup events to set some state that determines whether or not the surface is "active".

class MyComponent {
  constructor(element) {
    this.root = element;
    this.active = false;
    this.root.addEventListener('keydown', evt => {
      if (isSpace(evt)) {
        this.active = true;
      }
    });
    this.root.addEventListener('keyup', evt => {
      if (isSpace(evt)) {
        this.active = false;
      }
    });
    const foundation = new MDCRippleFoundation(
      ...MDCRipple.createAdapter(this),
      // ...
      isSurfaceActive: () => this.active
    });
    this.ripple = new MDCRipple(this.root, foundation);
  }
}

Specifying known element dimensions for asynchronous style loading

If you asynchronously load style resources, such as loading stylesheets dynamically or loading fonts, then adapter.getClientRect() may return incorrect dimensions if the ripple is initialized before the stylesheet/font has loaded. In this case, you can override the default behavior of getClientRect() to return the correct results.

For example, if you know an icon font sizes its elements to 24px width and height:

const foundation = new MDCRippleFoundation({
  // ...
  computeBoundingRect: () => {
    const {left, top} = element.getBoundingClientRect();
    const dim = 24;
    return {
      left,
      top,
      width: dim,
      height: dim,
      right: left + dim,
      bottom: top + dim
    };
  }
});
this.ripple = new MDCRipple(this.root, foundation);

The util API

External frameworks and libraries can use the following utility methods when integrating a component.

NOTE: The function util.supportsCssVariables cache its results; forceRefresh will force recomputation, but is used mainly for testing and should not be necessary in normal use.

Caveats

Caveat: Safari 9

TL;DR ripples are disabled in Safari 9 because of a bug with CSS variables.

The ripple works by updating CSS variables used by pseudo-elements. Unfortunately, in Safari 9.1, there is a bug where updating a CSS variable on an element will not trigger a style recalculation on that element's pseudo-elements (try out this codepen in Chrome, and then in Safari 9.1 to see the issue). Webkit builds which have this bug fixed (e.g. the builds used in Safari 10+) support CSS 4 Hex Notation while those without the fix don't. We feature-detect whether we are working with a WebKit build that can handle our usage of CSS variables.

Caveat: Mobile Safari

TL;DR for CSS-only ripple styles to work as intended, register a touchstart event handler on the affected element or its ancestor.

Mobile Safari does not trigger :active styles noticeably by default, as documented in the Safari Web Content Guide. This effectively suppresses the intended pressed state styles for CSS-only ripple surfaces. This behavior can be remedied by registering a touchstart event handler on the element, or on any common ancestor of the desired elements.

See this StackOverflow answer for additional information on mobile Safari's behavior.