Skip to content

Commit fbf5648

Browse files
benelliottjelbourn
benelliott
authored and
jelbourn
committed
feat(elevation): add $opacity argument to elevation mixins (#10877)
Add an argument to mat-elevation and mat-overridable-elevation that allows the opacities of the elevation shadow components to be scaled proportionately. Add missing $color argument to mat-overridable-elevation and extract default values into variables. Add documentation for new argument.
1 parent ef0229c commit fbf5648

File tree

2 files changed

+108
-87
lines changed

2 files changed

+108
-87
lines changed

‎guides/elevation.md

Lines changed: 15 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -22,15 +22,27 @@ achieved by switching elevation classes:
2222
### Mixins
2323

2424
Elevations can also be added in CSS via the `mat-elevation` mixin, which takes a number 0-24
25-
indicating the elevation of the element. In order to use the mixin, you must import
26-
`~@angular/material/theming`:
25+
indicating the elevation of the element as well as optional arguments for the elevation shadow's
26+
color tone and opacity.
27+
28+
Since an elevation shadow consists of multiple shadow components of varying opacities, the
29+
`$opacity` argument of the mixin is considered a factor by which to scale these initial values
30+
rather than an absolute value.
31+
32+
In order to use the mixin, you must import `~@angular/material/theming`:
2733

2834
```scss
2935
@import '~@angular/material/theming';
3036

31-
.my-class {
37+
.my-class-with-default-shadow {
38+
// Adds a shadow for elevation level 2 with default color and full opacity:
3239
@include mat-elevation(2);
3340
}
41+
42+
.my-class-with-custom-shadow {
43+
// Adds a shadow for elevation level 2 with color #e91e63 and 80% of the default opacity:
44+
@include mat-elevation(2, #e91e63, 0.8);
45+
}
3446
```
3547

3648
For convenience, you can use the `mat-elevation-transition` mixin to add a transition when the

‎src/lib/core/style/_elevation.scss

Lines changed: 93 additions & 84 deletions
Original file line numberDiff line numberDiff line change
@@ -31,93 +31,93 @@
3131
// created by taking a few reference shadow sets created by Google's Designers and interpolating
3232
// all of the values between them.
3333

34-
@function _get-umbra-map($color) {
34+
@function _get-umbra-map($color, $opacity) {
3535
@return (
36-
0: '0px 0px 0px 0px #{rgba($color, 0.2)}',
37-
1: '0px 2px 1px -1px #{rgba($color, 0.2)}',
38-
2: '0px 3px 1px -2px #{rgba($color, 0.2)}',
39-
3: '0px 3px 3px -2px #{rgba($color, 0.2)}',
40-
4: '0px 2px 4px -1px #{rgba($color, 0.2)}',
41-
5: '0px 3px 5px -1px #{rgba($color, 0.2)}',
42-
6: '0px 3px 5px -1px #{rgba($color, 0.2)}',
43-
7: '0px 4px 5px -2px #{rgba($color, 0.2)}',
44-
8: '0px 5px 5px -3px #{rgba($color, 0.2)}',
45-
9: '0px 5px 6px -3px #{rgba($color, 0.2)}',
46-
10: '0px 6px 6px -3px #{rgba($color, 0.2)}',
47-
11: '0px 6px 7px -4px #{rgba($color, 0.2)}',
48-
12: '0px 7px 8px -4px #{rgba($color, 0.2)}',
49-
13: '0px 7px 8px -4px #{rgba($color, 0.2)}',
50-
14: '0px 7px 9px -4px #{rgba($color, 0.2)}',
51-
15: '0px 8px 9px -5px #{rgba($color, 0.2)}',
52-
16: '0px 8px 10px -5px #{rgba($color, 0.2)}',
53-
17: '0px 8px 11px -5px #{rgba($color, 0.2)}',
54-
18: '0px 9px 11px -5px #{rgba($color, 0.2)}',
55-
19: '0px 9px 12px -6px #{rgba($color, 0.2)}',
56-
20: '0px 10px 13px -6px #{rgba($color, 0.2)}',
57-
21: '0px 10px 13px -6px #{rgba($color, 0.2)}',
58-
22: '0px 10px 14px -6px #{rgba($color, 0.2)}',
59-
23: '0px 11px 14px -7px #{rgba($color, 0.2)}',
60-
24: '0px 11px 15px -7px #{rgba($color, 0.2)}'
36+
0: '0px 0px 0px 0px #{rgba($color, $opacity * 0.2)}',
37+
1: '0px 2px 1px -1px #{rgba($color, $opacity * 0.2)}',
38+
2: '0px 3px 1px -2px #{rgba($color, $opacity * 0.2)}',
39+
3: '0px 3px 3px -2px #{rgba($color, $opacity * 0.2)}',
40+
4: '0px 2px 4px -1px #{rgba($color, $opacity * 0.2)}',
41+
5: '0px 3px 5px -1px #{rgba($color, $opacity * 0.2)}',
42+
6: '0px 3px 5px -1px #{rgba($color, $opacity * 0.2)}',
43+
7: '0px 4px 5px -2px #{rgba($color, $opacity * 0.2)}',
44+
8: '0px 5px 5px -3px #{rgba($color, $opacity * 0.2)}',
45+
9: '0px 5px 6px -3px #{rgba($color, $opacity * 0.2)}',
46+
10: '0px 6px 6px -3px #{rgba($color, $opacity * 0.2)}',
47+
11: '0px 6px 7px -4px #{rgba($color, $opacity * 0.2)}',
48+
12: '0px 7px 8px -4px #{rgba($color, $opacity * 0.2)}',
49+
13: '0px 7px 8px -4px #{rgba($color, $opacity * 0.2)}',
50+
14: '0px 7px 9px -4px #{rgba($color, $opacity * 0.2)}',
51+
15: '0px 8px 9px -5px #{rgba($color, $opacity * 0.2)}',
52+
16: '0px 8px 10px -5px #{rgba($color, $opacity * 0.2)}',
53+
17: '0px 8px 11px -5px #{rgba($color, $opacity * 0.2)}',
54+
18: '0px 9px 11px -5px #{rgba($color, $opacity * 0.2)}',
55+
19: '0px 9px 12px -6px #{rgba($color, $opacity * 0.2)}',
56+
20: '0px 10px 13px -6px #{rgba($color, $opacity * 0.2)}',
57+
21: '0px 10px 13px -6px #{rgba($color, $opacity * 0.2)}',
58+
22: '0px 10px 14px -6px #{rgba($color, $opacity * 0.2)}',
59+
23: '0px 11px 14px -7px #{rgba($color, $opacity * 0.2)}',
60+
24: '0px 11px 15px -7px #{rgba($color, $opacity * 0.2)}'
6161
);
6262
}
6363

64-
@function _get-penumbra-map($color) {
64+
@function _get-penumbra-map($color, $opacity) {
6565
@return (
66-
0: '0px 0px 0px 0px #{rgba($color, 0.14)}',
67-
1: '0px 1px 1px 0px #{rgba($color, 0.14)}',
68-
2: '0px 2px 2px 0px #{rgba($color, 0.14)}',
69-
3: '0px 3px 4px 0px #{rgba($color, 0.14)}',
70-
4: '0px 4px 5px 0px #{rgba($color, 0.14)}',
71-
5: '0px 5px 8px 0px #{rgba($color, 0.14)}',
72-
6: '0px 6px 10px 0px #{rgba($color, 0.14)}',
73-
7: '0px 7px 10px 1px #{rgba($color, 0.14)}',
74-
8: '0px 8px 10px 1px #{rgba($color, 0.14)}',
75-
9: '0px 9px 12px 1px #{rgba($color, 0.14)}',
76-
10: '0px 10px 14px 1px #{rgba($color, 0.14)}',
77-
11: '0px 11px 15px 1px #{rgba($color, 0.14)}',
78-
12: '0px 12px 17px 2px #{rgba($color, 0.14)}',
79-
13: '0px 13px 19px 2px #{rgba($color, 0.14)}',
80-
14: '0px 14px 21px 2px #{rgba($color, 0.14)}',
81-
15: '0px 15px 22px 2px #{rgba($color, 0.14)}',
82-
16: '0px 16px 24px 2px #{rgba($color, 0.14)}',
83-
17: '0px 17px 26px 2px #{rgba($color, 0.14)}',
84-
18: '0px 18px 28px 2px #{rgba($color, 0.14)}',
85-
19: '0px 19px 29px 2px #{rgba($color, 0.14)}',
86-
20: '0px 20px 31px 3px #{rgba($color, 0.14)}',
87-
21: '0px 21px 33px 3px #{rgba($color, 0.14)}',
88-
22: '0px 22px 35px 3px #{rgba($color, 0.14)}',
89-
23: '0px 23px 36px 3px #{rgba($color, 0.14)}',
90-
24: '0px 24px 38px 3px #{rgba($color, 0.14)}'
66+
0: '0px 0px 0px 0px #{rgba($color, $opacity * 0.14)}',
67+
1: '0px 1px 1px 0px #{rgba($color, $opacity * 0.14)}',
68+
2: '0px 2px 2px 0px #{rgba($color, $opacity * 0.14)}',
69+
3: '0px 3px 4px 0px #{rgba($color, $opacity * 0.14)}',
70+
4: '0px 4px 5px 0px #{rgba($color, $opacity * 0.14)}',
71+
5: '0px 5px 8px 0px #{rgba($color, $opacity * 0.14)}',
72+
6: '0px 6px 10px 0px #{rgba($color, $opacity * 0.14)}',
73+
7: '0px 7px 10px 1px #{rgba($color, $opacity * 0.14)}',
74+
8: '0px 8px 10px 1px #{rgba($color, $opacity * 0.14)}',
75+
9: '0px 9px 12px 1px #{rgba($color, $opacity * 0.14)}',
76+
10: '0px 10px 14px 1px #{rgba($color, $opacity * 0.14)}',
77+
11: '0px 11px 15px 1px #{rgba($color, $opacity * 0.14)}',
78+
12: '0px 12px 17px 2px #{rgba($color, $opacity * 0.14)}',
79+
13: '0px 13px 19px 2px #{rgba($color, $opacity * 0.14)}',
80+
14: '0px 14px 21px 2px #{rgba($color, $opacity * 0.14)}',
81+
15: '0px 15px 22px 2px #{rgba($color, $opacity * 0.14)}',
82+
16: '0px 16px 24px 2px #{rgba($color, $opacity * 0.14)}',
83+
17: '0px 17px 26px 2px #{rgba($color, $opacity * 0.14)}',
84+
18: '0px 18px 28px 2px #{rgba($color, $opacity * 0.14)}',
85+
19: '0px 19px 29px 2px #{rgba($color, $opacity * 0.14)}',
86+
20: '0px 20px 31px 3px #{rgba($color, $opacity * 0.14)}',
87+
21: '0px 21px 33px 3px #{rgba($color, $opacity * 0.14)}',
88+
22: '0px 22px 35px 3px #{rgba($color, $opacity * 0.14)}',
89+
23: '0px 23px 36px 3px #{rgba($color, $opacity * 0.14)}',
90+
24: '0px 24px 38px 3px #{rgba($color, $opacity * 0.14)}'
9191
);
9292
}
9393

94-
@function _get-ambient-map($color) {
94+
@function _get-ambient-map($color, $opacity) {
9595
@return (
96-
0: '0px 0px 0px 0px #{rgba($color, 0.12)}',
97-
1: '0px 1px 3px 0px #{rgba($color, 0.12)}',
98-
2: '0px 1px 5px 0px #{rgba($color, 0.12)}',
99-
3: '0px 1px 8px 0px #{rgba($color, 0.12)}',
100-
4: '0px 1px 10px 0px #{rgba($color, 0.12)}',
101-
5: '0px 1px 14px 0px #{rgba($color, 0.12)}',
102-
6: '0px 1px 18px 0px #{rgba($color, 0.12)}',
103-
7: '0px 2px 16px 1px #{rgba($color, 0.12)}',
104-
8: '0px 3px 14px 2px #{rgba($color, 0.12)}',
105-
9: '0px 3px 16px 2px #{rgba($color, 0.12)}',
106-
10: '0px 4px 18px 3px #{rgba($color, 0.12)}',
107-
11: '0px 4px 20px 3px #{rgba($color, 0.12)}',
108-
12: '0px 5px 22px 4px #{rgba($color, 0.12)}',
109-
13: '0px 5px 24px 4px #{rgba($color, 0.12)}',
110-
14: '0px 5px 26px 4px #{rgba($color, 0.12)}',
111-
15: '0px 6px 28px 5px #{rgba($color, 0.12)}',
112-
16: '0px 6px 30px 5px #{rgba($color, 0.12)}',
113-
17: '0px 6px 32px 5px #{rgba($color, 0.12)}',
114-
18: '0px 7px 34px 6px #{rgba($color, 0.12)}',
115-
19: '0px 7px 36px 6px #{rgba($color, 0.12)}',
116-
20: '0px 8px 38px 7px #{rgba($color, 0.12)}',
117-
21: '0px 8px 40px 7px #{rgba($color, 0.12)}',
118-
22: '0px 8px 42px 7px #{rgba($color, 0.12)}',
119-
23: '0px 9px 44px 8px #{rgba($color, 0.12)}',
120-
24: '0px 9px 46px 8px #{rgba($color, 0.12)}'
96+
0: '0px 0px 0px 0px #{rgba($color, $opacity * 0.12)}',
97+
1: '0px 1px 3px 0px #{rgba($color, $opacity * 0.12)}',
98+
2: '0px 1px 5px 0px #{rgba($color, $opacity * 0.12)}',
99+
3: '0px 1px 8px 0px #{rgba($color, $opacity * 0.12)}',
100+
4: '0px 1px 10px 0px #{rgba($color, $opacity * 0.12)}',
101+
5: '0px 1px 14px 0px #{rgba($color, $opacity * 0.12)}',
102+
6: '0px 1px 18px 0px #{rgba($color, $opacity * 0.12)}',
103+
7: '0px 2px 16px 1px #{rgba($color, $opacity * 0.12)}',
104+
8: '0px 3px 14px 2px #{rgba($color, $opacity * 0.12)}',
105+
9: '0px 3px 16px 2px #{rgba($color, $opacity * 0.12)}',
106+
10: '0px 4px 18px 3px #{rgba($color, $opacity * 0.12)}',
107+
11: '0px 4px 20px 3px #{rgba($color, $opacity * 0.12)}',
108+
12: '0px 5px 22px 4px #{rgba($color, $opacity * 0.12)}',
109+
13: '0px 5px 24px 4px #{rgba($color, $opacity * 0.12)}',
110+
14: '0px 5px 26px 4px #{rgba($color, $opacity * 0.12)}',
111+
15: '0px 6px 28px 5px #{rgba($color, $opacity * 0.12)}',
112+
16: '0px 6px 30px 5px #{rgba($color, $opacity * 0.12)}',
113+
17: '0px 6px 32px 5px #{rgba($color, $opacity * 0.12)}',
114+
18: '0px 7px 34px 6px #{rgba($color, $opacity * 0.12)}',
115+
19: '0px 7px 36px 6px #{rgba($color, $opacity * 0.12)}',
116+
20: '0px 8px 38px 7px #{rgba($color, $opacity * 0.12)}',
117+
21: '0px 8px 40px 7px #{rgba($color, $opacity * 0.12)}',
118+
22: '0px 8px 42px 7px #{rgba($color, $opacity * 0.12)}',
119+
23: '0px 9px 44px 8px #{rgba($color, $opacity * 0.12)}',
120+
24: '0px 9px 46px 8px #{rgba($color, $opacity * 0.12)}'
121121
);
122122
}
123123

@@ -127,29 +127,38 @@ $mat-elevation-transition-duration: 280ms !default;
127127
// The default easing value for elevation transitions.
128128
$mat-elevation-transition-timing-function: $mat-fast-out-slow-in-timing-function;
129129

130+
// The default color for elevation shadows.
131+
$mat-elevation-color: black !default;
132+
133+
// The default opacity scaling value for elevation shadows.
134+
$mat-elevation-opacity: 1 !default;
135+
130136
// Prefix for elevation-related selectors.
131137
$_mat-elevation-prefix: 'mat-elevation-z';
132138

133139
// Applies the correct css rules to an element to give it the elevation specified by $zValue.
134140
// The $zValue must be between 0 and 24.
135-
@mixin mat-elevation($zValue, $color: black) {
141+
@mixin mat-elevation($zValue, $color: $mat-elevation-color, $opacity: $mat-elevation-opacity) {
136142
@if type-of($zValue) != number or not unitless($zValue) {
137143
@error '$zValue must be a unitless number';
138144
}
139145
@if $zValue < 0 or $zValue > 24 {
140146
@error '$zValue must be between 0 and 24';
141147
}
142148

143-
box-shadow: #{map-get(_get-umbra-map($color), $zValue)},
144-
#{map-get(_get-penumbra-map($color), $zValue)},
145-
#{map-get(_get-ambient-map($color), $zValue)};
149+
box-shadow: #{map-get(_get-umbra-map($color, $opacity), $zValue)},
150+
#{map-get(_get-penumbra-map($color, $opacity), $zValue)},
151+
#{map-get(_get-ambient-map($color, $opacity), $zValue)};
146152
}
147153

148154
// Applies the elevation to an element in a manner that allows
149155
// consumers to override it via the Material elevation classes.
150-
@mixin mat-overridable-elevation($zValue) {
156+
@mixin mat-overridable-elevation(
157+
$zValue,
158+
$color: $mat-elevation-color,
159+
$opacity: $mat-elevation-opacity) {
151160
&:not([class*='#{$_mat-elevation-prefix}']) {
152-
@include mat-elevation($zValue);
161+
@include mat-elevation($zValue, $color, $opacity);
153162
}
154163
}
155164

0 commit comments

Comments
 (0)