Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs (Guides): Mat elevation guide #3917

Closed
wants to merge 11 commits into from
Closed

Docs (Guides): Mat elevation guide #3917

Show file tree
Hide file tree
Changes from 7 commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
935554e
added some basic information
M-a-c Mar 31, 2017
a4a430c
fixed some spelling
M-a-c Apr 1, 2017
3de9111
added some examples there are still some problems
M-a-c Apr 5, 2017
2033bb4
added an example
M-a-c Apr 5, 2017
04dff5d
fixed some spelling
M-a-c Apr 5, 2017
6160ef2
added scss comment block
M-a-c Apr 5, 2017
9b73991
fixed lint and made sure to link the style url
M-a-c Apr 5, 2017
3efe1ec
fixed link to theming
M-a-c Apr 6, 2017
0952077
docs (md elevation guide): $s removed from code.
M-a-c Apr 10, 2017
8b54aab
fixed spelling, and pr
M-a-c Apr 13, 2017
2db4d31
removed no-elevation class
M-a-c Apr 13, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 33 additions & 0 deletions guides/mat-elevation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
# mat-elevation
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

how do you feel about this?

# Elevation
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 best to 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 acheived by switching elevation classes:

```html
<div [class.mat-elevation-z2]="!isActive" [class.mat-elevation-z8]="isActive"></div>
```

<!-- example(elevation-overview) -->

## Mixins
Elevations can also be added in CSS via the `mat-elevation` mixin, which takes a number 0-24 indicating the elevation level of the element. In order to use the mixin you must import `~@angular/material/theming`.

```scss
@import ~@angular/material/theming;

.myClass {
  @include mat-elevation(2);

  &:active {
    @include mat-elevation(8);
  }
}
```

mat-elevation exists to give you separation between elements.
All material design elements have resting elevations.
[`Material design`](https://material.io/guidelines/material-design/elevation-shadows.html)
explains how best to use elevation.


Elevation is implemented with a class, simply adding the class `mat-elevation-z#` where # is the elevation number you want, 0-24.

## Example
<!-- example(elevation-overview) -->


## Mixins
In order to use the mixin for Elevation you must
`@import '~@angular/material/core/style/_elevation.scss';`
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this should be ~@angular/material/theming now that they're using a flat release structure (#3776)

Copy link
Contributor Author

@M-a-c M-a-c Apr 5, 2017 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok yeah I'll have to fix this then

Copy link
Contributor Author

@M-a-c M-a-c Apr 5, 2017 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@willshowell Do you know if i will need to specify elevation.scss from that path?
@import '~@angular/material/theming/style/_elevation.scss';?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@M-a-c no that should error. Using the master builds, check out your node_modules. At /node_modules/@angular/material/_theming.scss you can see that all the mixins/functions/definitions are concatenated together, including mat-elevation().

And due to Sass importing of partials, you don't need the leading underscore or file extension in your import statement.

$zValue must be a value between 0 and 24, inclusive.
`@include mat-elevation($zValue);`


How to use the mixin
```scss
.myClass {
@include $mat-elevation(2);
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

shouldn't this be without the $? -> @include mat-elevation(2);


&:active {
@include $mat-elevation(8);
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

same here

}
}
```

## Deprecated
The use of `mdElevation($zValue)` is deprecated.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we use the words attribute / directive in this text to be more clear?

5 changes: 5 additions & 0 deletions src/examples/elevation-overview/elevation-overview-example.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
<div class="dynamimc">Hover over me!</div>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Did you mean dynamic?


<div class"no-elevation">No Elevation</div>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does adding the no-elevation class here create confusion?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah good point, I removed it in the next commit


<div class="mat-elevation-z24">Static class for styling</div>
20 changes: 20 additions & 0 deletions src/examples/elevation-overview/elevation-overview-example.scss
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
@import '~@angular/material/core/style/_elevation.scss';

div {
width: auto;
display: block;
text-align: center;
height: 50px;
margin-left: auto;
margin-right: auto;
background-color: lightblue;
margin-top: 10px;
}

.dynamimc {
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ditto

@include $mat-elevation(2);
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also without $ ? At least in my Project it won't compile with a $


&:active {
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Shouldn't this be &:hover?

@include $mat-elevation(8);
}
}
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

newline

9 changes: 9 additions & 0 deletions src/examples/elevation-overview/elevation-overview-example.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
import {Component} from '@angular/core';

@Component({
selector: 'elevation-overview-example',
styleUrls: ['./elevation-overview-example.scss'],
templateUrl: './elevation-overview-example.html',
})

export class ElevationOverviewExample {}