CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-material--ripple

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

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

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;
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@material/ripple@14.0.x
Publish Source
CLI
Badge
tessl/npm-material--ripple badge