Ripple

The LmnRippleDirective provides the Material Design ink ripple interaction effect. It can be applied to host elements to visually indicate user interaction (like clicks or taps) with an expanding and fading circular animation originating from the point of interaction.

Technical Overview

The lmnRipple directive attaches event listeners to a specified trigger element (or its host element by default) to detect pointer down events (mousedown, touchstart, keydown) and pointer up events. Upon activation, it dynamically creates and animates ripple div elements (.lmn-ripple-element) within the host element.

Key Features

• Ripple Effect: Provides the standard ink ripple animation on user interaction.
• Configurable Appearance: Allows customization of ripple behavior (centered, unbounded), radius, color, and negative state styling.
• Customizable Animation: Supports overriding default enter/exit animation durations. Respects Angular's NoopAnimationsModule.
• Flexible Triggering: Can bind ripple triggers to the host element or a different specified trigger element. Supports keyboard triggers (Enter by default, configurable).
• Manual Control: Provides methods (launch, fadeOutAll, fadeOutAllNonPersistent) to programmatically trigger or dismiss ripples.
• Interaction Filtering:
  • Ignores synthetic mouse events following touch events.
  • Detects and ignores fake mousedown events from screen readers.
  • Allows specifying CSS selectors for descendant elements whose events should not trigger the ripple on the parent.
• Global Configuration: Supports global ripple options via the LMN_RIPPLE_GLOBAL_OPTIONS injection token (e.g., disabling ripples globally, setting default animation).
• Styling: Uses CSS variables for theming (--lmn-ripple-background-color, --lmn-ripple-background-color-negative) and applies host classes (lmn-ripple, lmn-ripple-negative, lmn-ripple-unbounded).

When to Use

Use the lmnRipple directive when:

• You want to provide standard feedback for user interactions on clickable or interactive elements (buttons, list items, cards, etc.).
• You need a visual indication of where a user interaction occurred on an element.
• You want to enhance the perceived responsiveness of UI elements.

Implementation

Apply the [lmnRipple] (or [lmn-ripple]) directive to the host element where the ripple effect should appear.

Selector: [lmnRipple], [lmn-ripple]

Export As: lmnRipple

Inputs:

• lmnRippleNegative: Optional (boolean, default: false). Applies negative styling (e.g., for dark backgrounds). Adds lmn-ripple-negative class.
• lmnRippleUnbounded: Optional (boolean, default: false). If true, ripples can render outside the host element's bounds. Adds lmn-ripple-unbounded class.
• lmnRippleCentered: Optional (boolean, default: false). If true, ripples always originate from the center of the host element, ignoring the event location.
• lmnRippleRadius: Optional (number, default: 0). Sets a fixed radius in pixels for the ripple. If 0, the radius expands to the furthest corner.
• lmnRippleAnimation: Optional (LmnRippleAnimationConfig). Allows specifying custom { enterDuration?: number, exitDuration?: number } in milliseconds. Overrides global animation settings. Ignored if NoopAnimationsModule is used.
• lmnRippleTriggerKeys: Optional (LmnRippleTriggerKey[], default: [LMN_KEY_CODE_ENTER]). Specifies which keyboard key codes (e.g., LMN_KEY_CODE_SPACE) should trigger the ripple effect, in addition to pointer events.
• lmnRippleDisabled: Optional (boolean, default: false). Disables automatic ripple generation on user interaction. Manual launching via launch() is still possible. Considers global disabled option.
• lmnRippleTrigger: Optional (HTMLElement, default: the host element). Specifies a different element within the component to listen for trigger events.
• lmnRippleIgnoreElementsSelectors: Optional (string[], default: []). An array of CSS selectors. If an interaction event originates from an element matching one of these selectors (or its descendant) within the trigger element, the ripple effect on this host will be suppressed.

Public Methods (accessible via exportAs='lmnRipple'):

• launch(config: LmnRippleConfig): LmnRippleRef: Launches a ripple programmatically using the provided configuration, originating from the center.
• launch(x: number, y: number, config?: LmnRippleConfig): LmnRippleRef: Launches a ripple programmatically from the specified viewport coordinates (x, y), optionally overriding default/input configurations.
• fadeOutAll(): void: Fades out all currently active ripples, including persistent ones.
• fadeOutAllNonPersistent(): void: Fades out only the non-persistent ripples that are currently active.

Global Options (LMN_RIPPLE_GLOBAL_OPTIONS):

Provide this token at the root or module level to configure default behavior:

{
  provide: LMN_RIPPLE_GLOBAL_OPTIONS,
  useValue: {
    disabled: false, // Globally set disable or not ripples
    animation: { enterDuration: 500, exitDuration: 450 }, // Default animation timings
    terminateOnPointerUp: true // Ripples start fading immediately on pointer up
  }
}

Styling

• Key CSS variables:
  • --lmn-ripple-background-color
  • --lmn-ripple-background-color-negative
• Host classes applied by the directive:
  • lmn-ripple (always applied)
  • lmn-ripple-negative (when negative input is true)
  • lmn-ripple-unbounded (when unbounded input is true)
• The ripple elements themselves have the class lmn-ripple-element.