diff --git a/src/lib/tooltip/tooltip.md b/src/lib/tooltip/tooltip.md index f270fbf4909..3e7104c3a0a 100644 --- a/src/lib/tooltip/tooltip.md +++ b/src/lib/tooltip/tooltip.md @@ -20,22 +20,46 @@ the positions `before` and `after` should be used instead of `left` and `right`, | `before` | Display to the left in left-to-right layout and to the right in right-to-left layout | | `after` | Display to the right in left-to-right layout and to the right in right-to-left layout| + ### Showing and hiding -The tooltip is immediately shown when the user's mouse hovers over the element and immediately -hides when the user's mouse leaves. A delay in showing or hiding the tooltip can be added through -the inputs `matTooltipShowDelay` and `matTooltipHideDelay`. The default show and hide delays can be -configured through the `MAT_TOOLTIP_DEFAULT_OPTIONS` injection token. +By default, the tooltip will be immediately shown when the user's mouse hovers over the tooltip's +trigger element and immediately hides when the user's mouse leaves. On mobile, the tooltip is displayed when the user longpresses the element and hides after a -delay of 1500ms. The longpress behavior requires HammerJS to be loaded on the page. +delay of 1500ms. The longpress behavior requires HammerJS to be loaded on the page. To learn more +about adding HammerJS to your app, check out the Gesture Support section of the Getting Started +guide. -The tooltip can also be shown and hidden through the `show` and `hide` directive methods, +#### Show and hide delays + +To add a delay before showing or hiding the tooltip, you can use the inputs `matTooltipShowDelay` +and `matTooltipHideDelay` to provide a delay time in milliseconds. + +The following example has a tooltip that waits one second to display after the user +hovers over the button, and waits two seconds to hide after the user moves the mouse away. + + + +#### Changing the default delay behavior + +You can configure your app's tooltip default show/hide delays by configuring and providing +your options using the `MAT_TOOLTIP_DEFAULT_OPTIONS` injection token. + + + +#### Manually calling show() and hide() + +To manually cause the tooltip to show or hide, you can call the `show` and `hide` directive methods, which both accept a number in milliseconds to delay before applying the display change. -To turn off the tooltip and prevent it from showing to the user, use the `matTooltipDisabled` input -flag. + + +#### Disabling the tooltip from showing + +To completely disable a tooltip, set `matTooltipDisabled`. While disabled, a tooltip will never be +shown. ### Accessibility diff --git a/src/material-examples/example-module.ts b/src/material-examples/example-module.ts index 99e1b2d1349..37bcb666013 100644 --- a/src/material-examples/example-module.ts +++ b/src/material-examples/example-module.ts @@ -119,7 +119,10 @@ import {TabsTemplateLabelExample} from './tabs-template-label/tabs-template-labe import {ToolbarMultirowExample} from './toolbar-multirow/toolbar-multirow-example'; import {ToolbarOverviewExample} from './toolbar-overview/toolbar-overview-example'; import {TooltipOverviewExample} from './tooltip-overview/tooltip-overview-example'; +import {TooltipDelayExample} from './tooltip-delay/tooltip-delay-example'; import {TooltipPositionExample} from './tooltip-position/tooltip-position-example'; +import {TooltipManualExample} from './tooltip-manual/tooltip-manual-example'; +import {TooltipModifiedDefaultsExample} from './tooltip-modified-defaults/tooltip-modified-defaults-example'; export interface LiveExample { title: string; @@ -597,6 +600,18 @@ export const EXAMPLE_COMPONENTS: {[key: string]: LiveExample} = { title: 'Basic tooltip', component: TooltipOverviewExample }, + 'tooltip-delay': { + title: 'Tooltips with delay', + component: TooltipDelayExample + }, + 'tooltip-manual': { + title: 'Tooltips with manual show button', + component: TooltipManualExample + }, + 'tooltip-modified-defaults': { + title: 'Tooltips with modified default values', + component: TooltipModifiedDefaultsExample + }, 'tooltip-position': { title: 'Tooltip with custom position', component: TooltipPositionExample @@ -718,6 +733,9 @@ export const EXAMPLE_LIST = [ ToolbarMultirowExample, ToolbarOverviewExample, TooltipOverviewExample, + TooltipDelayExample, + TooltipManualExample, + TooltipModifiedDefaultsExample, TooltipPositionExample, ]; diff --git a/src/material-examples/tooltip-delay/tooltip-delay-example.css b/src/material-examples/tooltip-delay/tooltip-delay-example.css new file mode 100644 index 00000000000..56d5205c068 --- /dev/null +++ b/src/material-examples/tooltip-delay/tooltip-delay-example.css @@ -0,0 +1,3 @@ +button { + margin: 8px; +} diff --git a/src/material-examples/tooltip-delay/tooltip-delay-example.html b/src/material-examples/tooltip-delay/tooltip-delay-example.html new file mode 100644 index 00000000000..7cd4a164b32 --- /dev/null +++ b/src/material-examples/tooltip-delay/tooltip-delay-example.html @@ -0,0 +1,7 @@ + + + diff --git a/src/material-examples/tooltip-delay/tooltip-delay-example.ts b/src/material-examples/tooltip-delay/tooltip-delay-example.ts new file mode 100644 index 00000000000..3e7ce9c5846 --- /dev/null +++ b/src/material-examples/tooltip-delay/tooltip-delay-example.ts @@ -0,0 +1,11 @@ +import {Component} from '@angular/core'; + +/** + * @title Tooltip with a show and hide delay + */ +@Component({ + selector: 'tooltip-delay-example', + templateUrl: 'tooltip-delay-example.html', + styleUrls: ['tooltip-delay-example.css'], +}) +export class TooltipDelayExample {} diff --git a/src/material-examples/tooltip-manual/tooltip-manual-example.css b/src/material-examples/tooltip-manual/tooltip-manual-example.css new file mode 100644 index 00000000000..7432308753e --- /dev/null +++ b/src/material-examples/tooltip-manual/tooltip-manual-example.css @@ -0,0 +1 @@ +/** No CSS for this example */ diff --git a/src/material-examples/tooltip-manual/tooltip-manual-example.html b/src/material-examples/tooltip-manual/tooltip-manual-example.html new file mode 100644 index 00000000000..3e5ca183924 --- /dev/null +++ b/src/material-examples/tooltip-manual/tooltip-manual-example.html @@ -0,0 +1,5 @@ + + + + I have a tooltip + diff --git a/src/material-examples/tooltip-manual/tooltip-manual-example.ts b/src/material-examples/tooltip-manual/tooltip-manual-example.ts new file mode 100644 index 00000000000..e39a760af29 --- /dev/null +++ b/src/material-examples/tooltip-manual/tooltip-manual-example.ts @@ -0,0 +1,11 @@ +import {Component} from '@angular/core'; + +/** + * @title Tooltip that can be manually shown/hidden. + */ +@Component({ + selector: 'tooltip-manual-example', + templateUrl: 'tooltip-manual-example.html', + styleUrls: ['tooltip-manual-example.css'], +}) +export class TooltipManualExample {} diff --git a/src/material-examples/tooltip-modified-defaults/tooltip-modified-defaults-example.css b/src/material-examples/tooltip-modified-defaults/tooltip-modified-defaults-example.css new file mode 100644 index 00000000000..7432308753e --- /dev/null +++ b/src/material-examples/tooltip-modified-defaults/tooltip-modified-defaults-example.css @@ -0,0 +1 @@ +/** No CSS for this example */ diff --git a/src/material-examples/tooltip-modified-defaults/tooltip-modified-defaults-example.html b/src/material-examples/tooltip-modified-defaults/tooltip-modified-defaults-example.html new file mode 100644 index 00000000000..8dcc0d0ed4a --- /dev/null +++ b/src/material-examples/tooltip-modified-defaults/tooltip-modified-defaults-example.html @@ -0,0 +1,3 @@ + diff --git a/src/material-examples/tooltip-modified-defaults/tooltip-modified-defaults-example.ts b/src/material-examples/tooltip-modified-defaults/tooltip-modified-defaults-example.ts new file mode 100644 index 00000000000..53cd3bc2805 --- /dev/null +++ b/src/material-examples/tooltip-modified-defaults/tooltip-modified-defaults-example.ts @@ -0,0 +1,22 @@ +import {Component} from '@angular/core'; +import {MAT_TOOLTIP_DEFAULT_OPTIONS, MatTooltipDefaultOptions} from '@angular/material'; + +/** Custom options the configure the tooltip's default show/hide delays. */ +export const myCustomTooltipDefaults: MatTooltipDefaultOptions = { + showDelay: 1000, + hideDelay: 1000, + touchendHideDelay: 1000, +}; + +/** + * @title Tooltip with a show and hide delay + */ +@Component({ + selector: 'tooltip-modified-defaults-example', + templateUrl: 'tooltip-modified-defaults-example.html', + styleUrls: ['tooltip-modified-defaults-example.css'], + providers: [ + {provide: MAT_TOOLTIP_DEFAULT_OPTIONS, useValue: myCustomTooltipDefaults} + ], +}) +export class TooltipModifiedDefaultsExample {}