From 722f0cbbe8e475e8e1a981beaf1ede0eb8b44b4b Mon Sep 17 00:00:00 2001 From: Will Howell Date: Wed, 1 Nov 2017 10:01:37 -0400 Subject: [PATCH 1/3] docs(elevation): add guide for elevation helpers - Credit to @M-a-c for intitial version --- guides/elevation.md | 52 +++++++++++++++++++ .../elevation-overview-example.css | 4 ++ .../elevation-overview-example.html | 7 +++ .../elevation-overview-example.ts | 13 +++++ src/material-examples/example-module.ts | 8 +++ 5 files changed, 84 insertions(+) create mode 100644 guides/elevation.md create mode 100644 src/material-examples/elevation-overview/elevation-overview-example.css create mode 100644 src/material-examples/elevation-overview/elevation-overview-example.html create mode 100644 src/material-examples/elevation-overview/elevation-overview-example.ts diff --git a/guides/elevation.md b/guides/elevation.md new file mode 100644 index 000000000000..3d1585acfd9d --- /dev/null +++ b/guides/elevation.md @@ -0,0 +1,52 @@ +Angular Material's elevation classes and mixins allow you to add separation between elements along +the z-axis. All material design elements have resting elevations. In addition, some elements may +change their elevation in response to user interaction. The +[Material Design spec](https://material.io/guidelines/material-design/elevation-shadows.html) +explains how to best use elevation. + +Angular Material provides two ways to control the elevation of elements: predefined CSS classes +and mixins. + +### Predefined CSS classes + +The easiest way to add elevation to an element is to simply add one of the predefined CSS classes +`mat-elevation-z#` where `#` is the elevation number you want, 0-24. Dynamic elevation can be +achieved by switching elevation classes: + +```html +
+``` + + + +### Mixins + +Elevations can also be added in CSS via the `mat-elevation` mixin, which takes a number 0-24 +indicating the elevation of the element. In order to use the mixin, you must import +`~@angular/material/theming`: + +```scss +@import '~@angular/material/theming'; + +.my-class { + @include mat-elevation(2); +} +``` + +For convenience, you can use the `mat-elevation-transition` mixin to add a transition between +elevation changes: + +```scss +@import '~@angular/material/theming'; + +.my-class { + @include mat-elevation-transition; + @include mat-elevation(2); + + &:active { + @include mat-elevation(8); + } +} +``` + + diff --git a/src/material-examples/elevation-overview/elevation-overview-example.css b/src/material-examples/elevation-overview/elevation-overview-example.css new file mode 100644 index 000000000000..49e543733c8f --- /dev/null +++ b/src/material-examples/elevation-overview/elevation-overview-example.css @@ -0,0 +1,4 @@ +.example-container { + padding: 16px; + margin-bottom: 16px; +} diff --git a/src/material-examples/elevation-overview/elevation-overview-example.html b/src/material-examples/elevation-overview/elevation-overview-example.html new file mode 100644 index 000000000000..1e38c9220e89 --- /dev/null +++ b/src/material-examples/elevation-overview/elevation-overview-example.html @@ -0,0 +1,7 @@ +
+ Example +
+ + diff --git a/src/material-examples/elevation-overview/elevation-overview-example.ts b/src/material-examples/elevation-overview/elevation-overview-example.ts new file mode 100644 index 000000000000..bcb4c84b770e --- /dev/null +++ b/src/material-examples/elevation-overview/elevation-overview-example.ts @@ -0,0 +1,13 @@ +import {Component} from '@angular/core'; + +/** + * @title Elevation CSS classes + */ +@Component({ + selector: 'elevation-overview-example', + styleUrls: ['elevation-overview-example.css'], + templateUrl: 'elevation-overview-example.html', +}) +export class ElevationOverviewExample { + isActive = false; +} diff --git a/src/material-examples/example-module.ts b/src/material-examples/example-module.ts index 23a4d39a2bdb..1fd0719e1055 100644 --- a/src/material-examples/example-module.ts +++ b/src/material-examples/example-module.ts @@ -45,6 +45,7 @@ import {DialogContentExampleDialog,DialogContentExample} from './dialog-content/ import {DialogDataExampleDialog,DialogDataExample} from './dialog-data/dialog-data-example'; import {DialogElementsExampleDialog,DialogElementsExample} from './dialog-elements/dialog-elements-example'; import {DialogOverviewExampleDialog,DialogOverviewExample} from './dialog-overview/dialog-overview-example'; +import {ElevationOverviewExample} from './elevation-overview/elevation-overview-example'; import {ExpansionOverviewExample} from './expansion-overview/expansion-overview-example'; import {ExpansionStepsExample} from './expansion-steps/expansion-steps-example'; import {MyTelInput,FormFieldCustomControlExample} from './form-field-custom-control/form-field-custom-control-example'; @@ -312,6 +313,12 @@ export const EXAMPLE_COMPONENTS = { additionalFiles: ["dialog-overview-example-dialog.html"], selectorName: 'DialogOverviewExample, DialogOverviewExampleDialog' }, + 'elevation-overview': { + title: 'Elevation CSS classes', + component: ElevationOverviewExample, + additionalFiles: null, + selectorName: null + }, 'expansion-overview': { title: 'Basic expansion panel', component: ExpansionOverviewExample, @@ -785,6 +792,7 @@ export const EXAMPLE_LIST = [ DialogDataExampleDialog,DialogDataExample, DialogElementsExampleDialog,DialogElementsExample, DialogOverviewExampleDialog,DialogOverviewExample, + ElevationOverviewExample, ExpansionOverviewExample, ExpansionStepsExample, MyTelInput,FormFieldCustomControlExample, From c788b47414c4e4d8d3e217717c3fe4542e19bf67 Mon Sep 17 00:00:00 2001 From: Will Howell Date: Wed, 1 Nov 2017 10:31:01 -0400 Subject: [PATCH 2/3] Remove extra newlines --- guides/elevation.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/guides/elevation.md b/guides/elevation.md index 3d1585acfd9d..e7b09e80c9ce 100644 --- a/guides/elevation.md +++ b/guides/elevation.md @@ -48,5 +48,3 @@ elevation changes: } } ``` - - From a8d0466ebe1ceb5a5806abcdebd63443782f5057 Mon Sep 17 00:00:00 2001 From: Will Howell Date: Wed, 1 Nov 2017 12:23:39 -0400 Subject: [PATCH 3/3] Address comments --- guides/elevation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/elevation.md b/guides/elevation.md index e7b09e80c9ce..270913f47c56 100644 --- a/guides/elevation.md +++ b/guides/elevation.md @@ -33,7 +33,7 @@ indicating the elevation of the element. In order to use the mixin, you must imp } ``` -For convenience, you can use the `mat-elevation-transition` mixin to add a transition between +For convenience, you can use the `mat-elevation-transition` mixin to add a transition when the elevation changes: ```scss