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 {}