or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

adapter.mdcomponent.mdfoundation.mdindex.mdsass.mdutilities.md
tile.json

tessl/npm-material--ripple

Material Design ink ripple effect component for web element interactions with JavaScript and CSS-only implementations

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@material/ripple@14.0.x

To install, run

npx @tessl/cli install tessl/npm-material--ripple@14.0.0

index.mddocs/

Material Ripple

Material Ripple provides Material Design ink ripple interaction effects for web components. It implements the official Material Design specifications for touch feedback animations, offering both JavaScript-enabled and CSS-only fallback implementations for maximum compatibility.

Package Information

  • Package Name: @material/ripple
  • Package Type: npm
  • Language: TypeScript/JavaScript with Sass
  • Installation: npm install @material/ripple

Core Imports

import { MDCRipple, MDCRippleFoundation } from "@material/ripple";

For individual imports:

import { MDCRipple } from "@material/ripple/component";
import { MDCRippleFoundation } from "@material/ripple/foundation";
import { MDCRippleAdapter } from "@material/ripple/adapter";
import * as util from "@material/ripple/util";
import { cssClasses, strings, numbers } from "@material/ripple/constants";

CommonJS:

const { MDCRipple, MDCRippleFoundation } = require("@material/ripple");

Sass imports:

@use "@material/ripple";

Basic Usage

import { MDCRipple } from "@material/ripple";

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

// Using static attachTo method
MDCRipple.attachTo(document.querySelector('.my-surface'));

// Unbounded ripple (like checkboxes/radio buttons)
const unboundedRipple = MDCRipple.attachTo(surface, { isUnbounded: true });

// Programmatic activation
ripple.activate();
ripple.deactivate();

CSS setup:

@use "@material/ripple";

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

Architecture

Material Ripple is built around several key components:

  • MDCRipple Component: Main JavaScript class providing ripple functionality
  • MDCRippleFoundation: Core logic handling ripple state and animations
  • MDCRippleAdapter: Interface for framework integration and DOM operations
  • CSS Variables System: Dynamic styling using CSS custom properties
  • Sass Mixins: Comprehensive styling system for different ripple configurations
  • Event System: Touch, mouse, keyboard, and focus event handling

Capabilities

Component API

Primary JavaScript interface for attaching and controlling ripples programmatically. Provides methods for activation, deactivation, and configuration.

class MDCRipple extends MDCComponent<MDCRippleFoundation> {
  static attachTo(root: Element, opts?: MDCRippleAttachOpts): MDCRipple;
  static createAdapter(instance: MDCRippleCapableSurface): MDCRippleAdapter;
  
  unbounded: boolean;
  disabled: boolean;
  
  activate(): void;
  deactivate(): void;
  layout(): void;
}

Component API

Foundation API

Core ripple logic and state management. Handles activation/deactivation animations, event coordination, and CSS variable updates.

class MDCRippleFoundation extends MDCFoundation<MDCRippleAdapter> {
  static readonly cssClasses: typeof cssClasses;
  static readonly strings: typeof strings;
  static readonly numbers: typeof numbers;
  static readonly defaultAdapter: MDCRippleAdapter;
  
  activate(evt?: Event): void;  
  deactivate(): void;
  layout(): void;
  setUnbounded(unbounded: boolean): void;
  handleFocus(): void;
  handleBlur(): void;
}

Foundation API

Adapter Interface

Integration interface for custom frameworks and components. Defines required methods for DOM manipulation, event handling, and CSS updates.

interface MDCRippleAdapter {
  browserSupportsCssVars(): boolean;
  isUnbounded(): boolean;
  isSurfaceActive(): boolean;
  isSurfaceDisabled(): boolean;
  addClass(className: string): void;
  removeClass(className: string): void;
  containsEventTarget(target: EventTarget | null): boolean;
  updateCssVariable(varName: string, value: string | null): void;
  computeBoundingRect(): DOMRect;
  getWindowPageOffset(): MDCRipplePoint;
}

Adapter Interface

Sass Styling System

Comprehensive mixin system for styling different ripple configurations, including bounded/unbounded ripples and various interaction states.

@mixin surface();
@mixin radius-bounded($radius: 100%);  
@mixin radius-unbounded($radius: 100%);
@mixin states($color, $has-nested-focusable-element: false);
@mixin states-base-color($color);
@mixin states-opacities($opacity-map, $has-nested-focusable-element: false);

@function states-opacity($color, $state);

Sass API

Utility Functions

Helper functions for CSS variable support detection and event coordinate normalization across different input types.

function supportsCssVariables(windowObj: typeof globalThis, forceRefresh?: boolean): boolean;
function getNormalizedEventCoords(evt: Event | undefined, pageOffset: MDCRipplePoint, clientRect: DOMRect): MDCRipplePoint;

Utilities

Types

Package Types

interface MDCRippleAttachOpts {
  isUnbounded?: boolean;
}

interface MDCRippleCapableSurface {
  root: Element;
  unbounded?: boolean;
  disabled?: boolean;
}

interface MDCRipplePoint {
  x: number;
  y: number;
}

type MDCRippleFactory = (el: Element, foundation?: MDCRippleFoundation) => MDCRipple;

External Base Types

From @material/base:

abstract class MDCComponent<FoundationType extends MDCFoundation> {
  readonly root: Element;
  destroy(): void;
  static attachTo(root: Element): MDCComponent<any>;
}

abstract class MDCFoundation<AdapterType> {
  protected adapter: AdapterType;
  init(): void;
  destroy(): void;
}

From @material/base/types:

type EventType = keyof HTMLElementEventMap;
type SpecificEventListener<K extends EventType> = (event: HTMLElementEventMap[K]) => void;