ripple.md

Ripple

This documentation is fully rendered on the Material Web catalog

Ripples are state layers used to communicate the status of a component or interactive element.

A state layer is a semi-transparent covering on an element that indicates its state. A layer can be applied to an entire element or in a circular shape.

• Design article
• API Documentation
• Source code

Usage

Ripples display on hover and press pointer interactions. They may be attached to a control in one of three ways.

1. Attached to the parent element

   <style>
     .container {
       position: relative;
     }
   </style>
   <button class="container">
     <md-ripple></md-ripple>
   </button>

2. Attached to a referenced element

   <style>
     .container {
       position: relative;
     }
   </style>
   <div class="container">
     <md-ripple for="control"></md-ripple>
     <input id="control">
   </div>

3. Attached imperatively

   <style>
     .container {
       position: relative;
     }
   </style>
   <div class="container">
     <md-ripple id="ripple"></md-ripple>
     <button id="ripple-control"></button>
   </div>
   <script>
     const ripple = document.querySelector('#ripple');
     const control = document.querySelector('#ripple-control');
     ripple.attach(control);
   </script>

Note: ripples must be placed within a position: relative container.

Unbounded

To create an unbounded circular ripple centered on an element, use the following styles.

.container {
  display: flex;
  place-content: center;
  place-items: center;
  position: relative;
}

md-ripple.unbounded {
  border-radius: 50%;
  inset: unset;
  height: var(--state-layer-size);
  width: var(--state-layer-size);
}

<style>
  .container {
    border-radius: 50%;
    height: 32px;
    width: 32px;

    /* Needed for unbounded ripple */
    display: flex;
    place-content: center;
    place-items: center;
    position: relative;
  }

  md-ripple.unbounded {
    /* Needed for unbounded ripple */
    border-radius: 50%;
    inset: unset;
    height: 64px;
    width: 64px;
  }
</style>
<button class="container">
  <md-ripple class="unbounded"></md-ripple>
</button>

Accessibility

Ripples are visual components and do not have assistive technology requirements.

Theming

Ripples support Material theming and can be customized in terms of color.

Tokens

Token	Default value
--md-ripple-hover-color	--md-sys-color-on-surface
--md-ripple-pressed-color	--md-sys-color-on-surface

• All tokens

Example

<style>
:root {
  --md-sys-color-primary: #006A6A;
  --md-ripple-hover-color: var(--md-sys-color-primary);
  --md-ripple-pressed-color: var(--md-sys-color-primary);
}

.container {
  position: relative;
}
</style>
<button class="container">
  <md-ripple></md-ripple>
</button>

API

MdRipple <md-ripple>

Properties

Property	Attribute	Type	Default	Description
disabled	disabled	boolean	false	Disables the ripple.
htmlFor		string	undefined
control		HTMLElement	undefined

Methods

Method	Parameters	Returns	Description
attach	control	void
detach	None	void