diff --git a/src/lib/core/ripple/README.md b/src/lib/core/ripple/README.md deleted file mode 100644 index 2cbcbe44a147..000000000000 --- a/src/lib/core/ripple/README.md +++ /dev/null @@ -1,48 +0,0 @@ -# mat-ripple - -`mat-ripple` defines an area in which a ripple animates, usually in response to user action. It is used as an attribute directive, for example `
...
`. - -By default, a ripple is activated when the host element of the `mat-ripple` directive receives mouse or touch events. On a mousedown or touch start, the ripple background fades in. When the click event completes, a circular foreground ripple fades in and expands from the event location to cover the host element bounds. - -Ripples can also be triggered programmatically by getting a reference to the MatRipple directive and calling its `start` and `end` methods. - -### Global options - -Developers are able to 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. - -```ts -const globalRippleConfig: RippleGlobalOptions = { - disabled: true, - baseSpeedFactor: 1.5 // Ripples will animate 50% faster than before. -} - -@NgModule({ - providers: [ - {provide: MAT_RIPPLE_GLOBAL_OPTIONS, useValue: globalRippleConfig} - ] -}) -``` - -Here are all available global options listed: - -| Name | Type | Description | -| --------------- | ------- | ----------------------------------------- | -| disabled | boolean | Whether ripples should show or not. | -| baseSpeedFactor | number | Factor to adjust ripple speed. | - -### API Summary - -Properties: - -| Name | Type | Description | -| --- | --- | --- | -| `matRippleTrigger` | Element | The DOM element that triggers the ripple when clicked. Defaults to the parent of the `mat-ripple`. -| `matRippleColor` | string | Custom color for foreground ripples -| `matRippleCentered` | boolean | If true, the ripple animation originates from the center of the `mat-ripple` bounds rather than from the location of the click event. -| `matRippleRadius` | number | Optional fixed radius of foreground ripples when fully expanded. Mainly used in conjunction with `unbounded` attribute. If not set, ripples will expand from their origin to the most distant corner of the component's bounding rectangle. -| `matRippleUnbounded` | boolean | If true, foreground ripples will be visible outside the component's bounds. -| `matRippleDisabled` | boolean | If true, click events on the trigger element will not activate ripples. The `start` and `end` methods can still be called to programmatically create ripples. diff --git a/src/lib/core/ripple/ripple.md b/src/lib/core/ripple/ripple.md new file mode 100644 index 000000000000..9338ab4b2418 --- /dev/null +++ b/src/lib/core/ripple/ripple.md @@ -0,0 +1,93 @@ +Connect user input to screen reactions by using ripples to both indicate the point of touch, and to +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. + +```html +
+ +
+``` + +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 also 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`. + +```html +
+
+ +
+ +
+
+``` + +### Manual ripples + +Ripples can be shown programmatically by getting a reference to the `MatRipple` directive. + +```ts +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(0, 0, { + persistent: true, + centered: true + }); + + // Fade out the ripple later. + rippleRef.fadeOut(); + } +} +``` + +In the example above, the `x` and `y` parameters will be ignored, because the `centered` +ripple option has been set to `true`. + +Ripples that are being dispatched programmatically can be launched with the `persistent` option. +This means that the ripples will not fade out automatically, and need to be faded out using +the `RippleRef` (*useful for focus indicators*). + +### Global options + +Developers are able to 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. + +```ts +const globalRippleConfig: RippleGlobalOptions = { + disabled: true, + baseSpeedFactor: 1.5 // Ripples will animate 50% faster than before. +} + +@NgModule({ + providers: [ + {provide: MAT_RIPPLE_GLOBAL_OPTIONS, useValue: globalRippleConfig} + ] +}) +``` + +All currently available global options are shown here: + +| Name | Type | Description | +| --------------- | ------- | ----------------------------------------- | +| disabled | boolean | Whether ripples should show or not. | +| baseSpeedFactor | number | Factor to adjust ripple speed. |