We can connect user input to screen reactions by using ripples to indicate the point of touch and confirm that touch input was received. For touch or mouse, this occurs at the point of contact.
The matRipple attribute directive defines an area in which a ripple animates on user interaction.
<div matRipple [matRippleColor]="myColor">
<ng-content></ng-content>
</div>By default, a ripple is activated when the host element of the matRipple directive receives mouse or touch events. Upon being pressed, a ripple will begin fading in from the point of contact, radiating to cover the host element. Each ripple will fade out only upon release of the mouse or touch.
Ripples can be triggered programmatically by getting a reference to the MatRipple directive and calling its launch method.
Ripple Trigger
By default ripples will fade in on interaction with the directive’s host element. In some situations, developers may want to show ripples on interaction with some other element, but still want to have the ripples placed in another location. This can be done by specifying the matRippleTrigger option that expects a reference to an HTMLElement.
<div>
<div matRipple [matRippleTrigger]="trigger" class="my-ripple-container">
<!-- This is the ripple container, but not the trigger element for ripples. -->
</div>
<div #trigger></div>
</div> Manual ripples
Ripples can be shown programmatically by getting a reference to the MatRipple directive.
class MyComponent {
/** Reference to the directive instance of the ripple. */
@ViewChild(MatRipple) ripple: MatRipple;
/** Shows a centered and persistent ripple. */
launchRipple() {
const rippleRef = this.ripple.launch({
persistent: true,
centered: true
});
// Fade out the ripple later.
rippleRef.fadeOut();
}
} In the example above, no specific coordinates have been passed because the centered ripple option has been set to true, and the coordinates would not matter.
Ripples that are being dispatched programmatically can be launched with the persistent option. It means that the ripples will not fade out and need to be faded out using the RippleRef (useful for focus indicators).
In case developers want to launch ripples at specific coordinates within the element, the launch() method also accepts x and y coordinates as parameters. Those coordinates are relative to the ripple container element.
const rippleRef = this.ripple.launch(10, 10, {persistent: true}); Global options
Developers can specify options for all ripples inside of their application.
The speed of the ripples can be adjusted, and the ripples can be disabled globally as well.
Global ripple options can be specified by setting the MAT_RIPPLE_GLOBAL_OPTIONS provider.
const globalRippleConfig: RippleGlobalOptions = {
disabled: true,
animation: {
enterDuration: 300,
exitDuration: 0
}
};
@NgModule({
providers: [
{provide: MAT_RIPPLE_GLOBAL_OPTIONS, useValue: globalRippleConfig}
]
}) All available global options can be seen in the RippleGlobalOptions interface.
Disabling animation
The animation of ripples can be disabled by using the global animation option. If the enterDuration and exitDuration are being set to 0, ripples will appear without any animation.
It is specifically useful in combination with the disabled global option because globally, disabling ripples won’t affect the focus indicator ripples. If someone still wants to disable those ripples for performance reasons, the duration can be set to 0 to remove the rippling feel.
const globalRippleConfig: RippleGlobalOptions = {
disabled: true,
animation: {
enterDuration: 0,
exitDuration: 0
}
}; Note: Ripples will also have no animation if the NoopAnimationsModule is being used. It means that the durations in the animation configuration won’t be taken into account.
Animation behavior
There are two different animation behaviors for the fade-out of ripples shown in the Material Design specifications.
By default, all ripples will start fading out if the mouse or touch is released and the enter animation is completed. The second possible behavior, which is also shown in the specifications, is that ripples start to fade immediately on mouse or touch release.
In some scenarios, developers might prefer that behavior over the default and would like to have the same for Angular Material. This behavior can be activated by specifying the terminateOnPointerUp global ripple option.
const globalRippleConfig: RippleGlobalOptions = {
terminateOnPointerUp: true
}; Updating global options at runtime
To change global ripple options at runtime, inject the MAT_RIPPLE_GLOBAL_OPTIONS provider and update the desired options.
There are various ways of injecting global options. To make it easier to inject and update options at runtime, it’s recommended to create a service that implements the RippleGlobalOptions interface.
@Injectable({providedIn: 'root'})
export class AppGlobalRippleOptions implements RippleGlobalOptions {
/** Whether ripples should be disabled globally. */
disabled: boolean = false;
}
@NgModule({
providers: [
{provide: MAT_RIPPLE_GLOBAL_OPTIONS, useExisting: AppGlobalRippleOptions},
]
})
export class MyModule {...} Now the global ripple options are set to a service we can inject, the service can be used update any global ripple option at runtime.
@Component(...)
export class MyComponent {
constructor(private _appRippleOptions: AppGlobalRippleOptions) {}
disableRipples() {
this._appRippleOptions.disabled = true;
}
}
Leave a Reply