Components / Library version 3.26.0

Installation

The component library is distributed as javascript modules (CommonJS and ES modules) to use with a bundler, as well as standalone javascript files that can be loaded directly (e.g. via a script tag). It also includes an ES5 build for older browsers, and we release a separate react-specific package (see instructions at the bottom of this page). The core distribution includes the following builds:

  • dist/cjs CommonJS, for bundlers
  • dist/esm ES modules, for bundlers
  • dist/esm-es5 ES modules, compatible with older browsers
  • dist/collection for lazy loading in other Stencil applications
  • dist/ripple for loading directly, e.g. via a script tag

We recommend that you let Stencil's loader determine which build to use. For this, simply import and execute the defineCustomElements function in dist/loader.

The components use the Material Design Icons, an icon set which is probably already being pulled in your codebase (unless your product has not adopted the Ripple design system yet). If it is not available, make sure to load it before using the components, for instance by adding a link tag in the page head:

<link href="https://cdn.materialdesignicons.com/3.6.95/css/materialdesignicons.min.css" rel="stylesheet">

Installing in a NodeJS application

  1. Add the package:

    npm i @watermarkinsights/ripple@3.26.0

  2. Import the loader and polyfill functions:

    import { applyPolyfills, defineCustomElements } from '@watermarkinsights/ripple/dist/loader';

  3. Call them to load the components:

    applyPolyfills().then(() => {
  defineCustomElements();
});

You can now use the components as you would any other html element: <wm-button>Click me</wm-button>

To update, simply run the install command again, specifying the desired version.

Loading as a script

Alternatively, you can simply load this script to use the library:

<script type="module" src="https://cdn.jsdelivr.net/npm/@watermarkinsights/ripple@3.26.0/dist/ripple/ripple.js"></script>

To update, replace "3.26.0" by the desired version.

Installing React Wrappers

If your project uses React, install this package instead of the core library to use the Ripple component the React way. The components' names and props will be CamelCased rather than hyphenated, and you will be able to hook to events directly on the component (e.g. onWmEventTriggered=...), rather than .addEventListener("wmEventTriggered", ...).

  1. Add the package:

    npm i @watermarkinsights/ripple-react@3.26.0

  2. Import the components at the top of your file:

    import { WmButton, WmSelect, WmOption } from '@watermarkinsights/ripple-react';

As for the core library, the Material Design Icons need to be loaded before using the components.

To update, simply run the install command again, specifying the desired version.

In a compound component like Select or Action Menu, child components are rendered in the parent's slot element, part of its shadow DOM tree. Slots essentially serve as a placeholder for markup that you the developer define in the light DOM tree, like <wm-menuitem>, <wm-option>, text content, or other child elements.

The browser distributes the child elements defined in the light DOM into the shadow DOM of the parent. The result is a flattened DOM tree—a merger of the the light DOM and the shadow DOM. This flattened tree is what you see in DevTools and what is rendered on the page.

With the standard implementation of the component, dynamically updating the child items will throw an error. Elm's efficient diffing of the DOM will register that only the child items have changed and try to update them, but the component has already been composed.

Rendering the component in a Keyed node and giving it a dynamic id will cause the entire component, rather than just the child items, to render anew, avoiding the error.