diff --git a/guides/elevation.md b/guides/elevation.md new file mode 100644 index 000000000000..270913f47c56 --- /dev/null +++ b/guides/elevation.md @@ -0,0 +1,50 @@ +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 when the +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,