@material/elevation

Elevation

Shadows provide important visual cues about objects’ depth and directional movement. They are the only visual cue indicating the amount of separation between surfaces. An object’s elevation determines the appearance of its shadow. The elevation values are mapped out in a "z-space" and range from 0 to 24.

A note about "z-space": Within the spec, elevation is normally referred to as having a dp value. In other words, how many "pixels" above the base material is a piece of material elevated. On a computer, this is normally represented by a 3-d coordinate system. We like z-space (or just "z" for short) because it aligns with the technical definition of, and nomenclature for, a 3-d coordinate system. Therefore, we feel it makes more sense than dp. However, when we refer to z-space (or z), that can be used interchangeably with the spec's dp.

Design & API Documentation

• Material Design guidelines: Shadows & elevation
• Demo

Installation

npm install @material/elevation

Basic Usage

HTML

Elevation is often already included within the baseline styles of other components (e.g. raised buttons, elevated cards).

However, you can also apply elevation to specific components using mdc-elevation--z<N> classes:

  <div class="mdc-elevation--z1">
    <!-- ... content ... -->
  </div>

Elevation Overlay

The elevation overlay should appear above the component container in the stacking context but below the ripple. To accomplish this, the .mdc-elevation-overlay element should appear before the .mdc-<component>__ripple element in the DOM context. Here's sample markup for a button with a touch target.

<button class="mdc-button mdc-button--raised">
  <div class="mdc-elevation-overlay"></div>
  <div class="mdc-button__ripple"></div>
  <i class="material-icons mdc-button__icon" aria-hidden="true">favorite</i>
  <span class="mdc-button__label">Font Icon</span>
</button>

This ensures the ripple parts are rendered above the overlay.

Styles

@use "@material/elevation/mdc-elevation";

Style Customization

CSS Classes

Some components have a set elevation. For example, a raised MDC Button has elevation 2.

If you want to set the elevation of an element, which is not a Material Design component, you can apply the following CSS classes.

CSS Class	Description
mdc-elevation--z<N>	Sets the elevation to the (N)dp, where 1 <= N <= 24
mdc-elevation-transition	Applies the correct css rules to transition an element between elevations

Sass Mixins, Variables, and Functions

Mixin	Description
elevation($z-value, $color, $opacity-boost)	Sets the elevation to the z-space for that given elevation, and optionally sets the color and/or boosts the opacity of the shadow
overlay-common	Called once per application to setup the universal elevation overlay styles
shadow($box-shadow)	Sets the box-shadow of the closest parent selector
overlay-surface-position	Sets the positioning of the overlay's surface element so that the overlay can be appropriately centered
overlay-dimensions($width, $height: $width, $has-content-sizing: true)	Sets the dimensions of the elevation overlay
overlay-fill-color($color)	Sets the color of the elevation overlay
overlay-opacity($opacity)	Sets the opacity of the elevation overlay

Function	Description
transition-value($duration, $easing)	Returns a value for the transition property to transition an element between elevations
overlay-transition-value($duration, $easing)	Returns a value for the transition property to transition the elevation overlay between elevations

Variable	Description
$property	Default property for elevation transitions
$transition-duration	Default duration value for elevation transitions
$transition-timing-function	Default easing value for elevation transitions
$overlay-color	Default color for the elevation overlay
$overlay-property	Default property for the elevation overlay transitions

If you need more configurability over your transitions, use the transition-value function in conjunction with the exported sass variables.

@use "@material/elevation";

.my-component-with-custom-transitions {

  transition:
    elevation.transition-value(),
    /* Configure opacity to use same duration and easing values as elevation */
    opacity elevation.$transition-duration elevation.$transition-timing-function;
  opacity: .7;
  will-change: elevation.$property, opacity;
}

Changelog

6.0.0 (2020-04-22)

Bug Fixes

• auto-init: Fixed issue with multiple default exports (#5464) (8ddd5c6)
• button: Fix outline & ink color according to spec guidance (#5268) (ee1a68c)
• button: Fixed parameter default value in height mixin (#5244) (b0cecf1)
• checkbox: change checkbox event type from change to click and add some logic for IE browser (#5316) (2e491de), closes #4893
• checkbox: Disabled state colors in IE11 high contrast mode (#5263) (d6a1d4b)
• checkbox: Replace unique-id with custom color hash functio… (#5404) (7be9e4a)
• checkbox: update disabled color values (#5209) (821871e)
• checkbox: Use secondary and on-secondary as default colors (b95172e), closes #5730
• chips: .d.ts file generated with syntax error (d154836)
• chips: .d.ts file generated with syntax error (#5577) (98f7faa)
• chips: Do not throw error if chip set becomes empty (#5290) (f978109)
• chips: Fix browser back nav in FF when removing chip with… (#5537) (a1a0deb)
• chips: Handle IE/Edge specific key names in keyboard navigation logic (3657f88)
• chips: Move touch target inside primary action (ad3bbf7)
• circular-progress: Add .npmignore file to ignore typescript files when publishing (#5801) (f172b0f), closes #5800
• circular-progress: fix determinate transition typo & 4 color keyframes (a301636)
• circular-progress: Fix naming in package.json and add to jsBundleFactory (86f7cad)
• circular-progress: Force LTR layout (6a40ef2)
• circular-progress: Switch mixins import to [@use](https://github.com/use) (098ae32)
• core: Fix canary release by excluding test files from default tsconfig (#5317) (c916008)
• data-table: change svg attribute name viewbox to viewBox (#5483) (#5493) (f3adce8)
• data-table: Fix pagination box height (eb28b6e)
• data-table: Fixed default feature targeting query params of sort mixins (e33c49e)
• data-table: Hover styles for sortable header cell (d580805)
• data-table: Reverse the arrow direction icon for column sorting (a7c827f)
• data-table: unable to redefine colors in class-based themi… (#5751) (4d48051)
• data-table: unable to redefine colors in class-based theming (4b45b66)
• dialog: Move aria roles from dialog root to dialog surface… (#5239) (c704b71)
• elevation: Update overlay color mixin (#5331) (b723dfa)
• fab: Add missing dep to fab package.json. (#5236) (e0f6fd9)
• fab: Add overflow: visible to make touch target visible in… (#5241) (5850080)
• fab: Adjust fab line-height (#5254) (525989b)
• fab: Adjust fab line-height to center text (#5258) (591a6ad)
• floatinglabel: Estimate hidden scroll width (#5448) (981ec9b)
• linear-progress: Temporary rollback of #5656 while updating downstream dependencies (9cf5e98)
• linear-progress: support aria attributes (#5248) (7084b40), closes #5248
• list: Ensure disabled colors apply to primary and secondary text (#5322) (878a08b)
• list: No longer emits action event when disabled item selected (f352d03), closes #5571
• menu-surface: Use margin_to_edge as a viewport margin in calculations for autopositioning. (4b04cdb)
• menusurface: open and closed events not fired when already opened or closed (9cff431)
• menusurface: synchronous quick menu does not close on button click (45a6615)
• notched-outline: Restore component test (#5449) (4269133)
• radio: update disabled color values (#5210) (491fddc)
• select: Deduplicate change events (4ad1274), closes #5570
• select: Do not fire change event on programmatic change (#5255) (ec72968)
• select: Fix notch outline width when floating (#5319) (1c494e5)
• slider: slider track not visible (#5512) (f2426d2)
• slider: two change events fired on each up (d10412c)
• slider: use secondary custom property color for slider container (#5132) (aa8e43e)
• slider: Visual bug when slider value is displayed as "-0" (3fc3ab5)
• snackbar: add explicit width for label to wrap in ie11 (#5497) (cd49033)
• snackbar: adjust mixins to meet spec (#5477) (f16f15b)
• switch: add transform transition to switch control to avoid overflow-x issues (8c11ea2)
• switch: always set track to transparent border (9a169f4)
• switch: fix strict generic checks (7f5e0c2)
• switch: handle aria-checked correctly. (#5202) (#5357) (d245a1a)
• switch: set track border to be transparent (#5323) (397905b)
• switch: use CSS custom properties for theming (d6315ef)
• testing: Revert change from #5299. (#5324) (5fb62be)
• textfield: add placeholder mixins and fix disabled colors (#5360) (0a40ced)
• textfield: add separate classes for leading/trailing icons (#5367) (70c708d)
• textfield: change root element to <label> (#5439) (d8d9502)
• textfield: clean up input padding (8639c26)
• textfield: hide filled-variant floating label at <52px (#5553) (5ff3380)
• textfield: IE11 label overlapping placeholder (781434a)
• textfield: incorrect mixin forward path (#5554) (3e782d8)
• textfield: move ripple to separate element (c541ebe)
• textfield: outlined trailing icon's position (#5496) (93e2288)
• textfield: prevent placeholder styles from collapsing with minifiers (d07c78d)
• add missing SASS dependencies (#5337) (d2ae6e1)
• textfield: remove absolute positioning from icons (1e13d1d)
• textfield: remove deprecated dense variant in favor of density (776291e), closes #4142
• textfield: use correct disabled colors for IE11 high contrast (5353985)
• Remove edge detection for CSS custom properties (#5264) (fe444ac)
• server-side rendering errors in linear progress and slider (7d0b983)

Code Refactoring

• migrate to the Sass module system (#5453) (faa9af3)
• grid-list: Deprecate component (#5499) (cf33f11)
• linear-progress: Restructure buffer DOM to allow translucent buffer (98b8434)
• linear-progress: Restructure buffer DOM to allow translucent buffer (9372e49)
• select: Fix alignment issues, upgrade anchor to interactive element (28d10a9), closes #5428
• touchtarget: Rename mdc-touch-target-component => mdc… (#5245) (afe0dd1)

Features

• button: Add disabled state color mixins (#5232) (b5eb51e)
• button: Add overflow ellipsis mixin (#5352) (47949b0)
• button: Expand outlined touch target to include side borders (ce6cb70)
• button: Setup elevation overlay (#5256) (3cbee6d)
• card: Add elevation overlay structure (#5282) (aa0eba4)
• checkbox: Add support for checkbox CSS-only indeterminate checkbox (b273afa)
• chips: Add chips styling (1db5c9f)
• chips: Add elevation overlay structure (#5279) (3e560b3)
• chips: Add focus{in|out} handlers (10af6cf)
• chips: Add keyCode support (82fa986)
• chips: Add trailing action feature targeting test (bec0659)
• chips: Announce when chips are removed (b3f70eb)
• chips: Consolidate interaction event handlers (#5251) (5729943)
• chips: Create trailing action business logic (9ebee4c)
• chips: Expose trailing action chip files (6b48781)
• chips: Restructure trailing action mixins (05f5e15)
• circular-progress: Add foundation methods to get isDeterminate and progress value (7d8f9c8)
• circular-progress: Add Sass styles and tests (bd33cb5)
• circular-progress: Add TS for foundation, adapter, component with tests (548b1d4)
• data-table: Add base styles to support pagination. (927fa90)
• data-table: Add foundation methods to support loading state. (e75deb8)
• data-table: Added styles for table in loading state (35a32aa)
• data-table: Added styles to support column sorting. (17b9699)
• data-table: Foundation changes to support column sorting (6ee0355)
• data-table: Set progress indicator styles based on table body height (c026422)
• dialog: Add elevation overlay structure (#5283) (b8bc4a2)
• dom: Add focus trap utility. (#5505) (63f357d)
• dom: Add keyboard support (5f24faa)
• dom: Create announcer utility (32c1df1)
• elevation: Add elevation overlay mixins (#5249) (b4cfdc4)
• elevation: Update elevation mixins (#5304) (ba879b6)
• fab: Add elevation overlay structure (#5278) (e89750d)
• fab: Add outline in high-contrast mode (deda86d)
• fab: Add support for increased touch target to mini FAB. (#5231) (0c4d8f3)
• floating-label: add feature targeting for styles (#5287) (b240bcc)
• form-field: Add support for space-between (e84b9c8), closes #5747
• formfield: add nowrap class/prop to MDC/MWC (c4b4bba)
• icon-button: Add disabled state color mixins (#5246) (7161170)
• iconbutton: Add icon button variant which supports toggling aria label. (f838c6e)
• line-ripple: add active/inactive states to line-ripple (b6c7f62)
• line-ripple: add feature targeting for styles (#5292) (391674a)
• linear-progress: Add foundation methods to fetch progress and determinate state. (4dc45af)
• menu: Add elevation overlay structure (#5280) (7fd17ce)
• menu: Add mixin to flatten menu top when opened-below anchor (1e17c49)
• menu-surface: Add support for flipping menu corner horizontally. (7b44824)
• notched-outline: add feature targeting for styles (#5289) (c483774)
• progress-indicator: Add common interface for progress indicators (#5564) (ea863cb)
• ripple: Reorganize ripple opacities (008c4d3)
• switch: Add elevation overlay structure (#5281) (50f110a)
• switch: Restructure DOM (#5312) (0ec1fab)
• text-field: Add disabled state color mixins (#5208) (66299b6)
• text-field: add feature targeting for styles (#5378) (e8a9936)
• text-field: Truncate floating label width w/ icons (c141801)
• textfield: add end-alignment (#5356) (847dd1a)
• textfield: add filled class variant (b70bc60)
• textfield: add forced LTR input (490fbdc)
• textfield: add prefix and suffix (6601d24), closes #1892
• Add index stylesheets to each MDC Web package (#5539) (1814866)
• Add index stylesheets to mdc-image-list and mdc-layout-gr… (#5546) (3a85313)
• Use @use syntax in material-components-web Sass file and… (#5573) (b4727e4)
• textfield: add specific label-floating class (a88c8e4)
• textfield: allow character counter to be moved outside of the textarea. (84e7ed5)
• textfield: Create float transition mixin (ca61b65)
• textfield: Limit notched outline max-width (0ab62a6)
• typography: add container baseline mixins for flexbox (69edc6e)

Reverts

• Revert "feat(switch): Add elevation overlay structure (#5281)" (#5329) (1fbf5bd), closes #5281 #5329
• "fix(checkbox): change checkbox event type from change to click and add some logic for IE browser" (ba30399)
• feat(chips): Consolidate interaction event handlers (#5251) (#5301) (5e45d77)
• fix(chips): Do not throw error if chip set becomes empty (#5300) (d10e8cd)
• fix(select): Do not fire change event on programmatic change (#5255) (#5302) (ad9dfe7)

BREAKING CHANGES

• select: HTML Markup significantly changed, see README; REMOVED adapter methods isSelectedTextFocused, getSelectedTextAttr, setSelectedTextAttr; ADDED adapter methods isSelectAnchorFocused, getSelectAnchorAttr, setSelectAnchorAttr; removed variables outlined-dense-label-position-y, icon-padding; added variables minimum-height-for-filled-label, filled-baseline-top, selected-text-height, anchor-padding-left, anchor-padding-left-with-leading-icon, anchor-padding-right.

• text-field: Redundant mixins mdc-text-field-textarea-fill-color, mdc-text-field-textarea-stroke-color, mdc-text-field-fullwidth-bottom-line-color removed. Instead, use mdc-text-field-fill-color, mdc-text-field-outline-color, and mdc-text-field-bottom-line-color respectively to achieve the same effect.

• textfield: mdc-text-field--dense and associated mixins/variables have been removed. Use the density() mixin instead.

• textfield: removed the following variables: $input-padding, $input-padding-top, $input-padding-bottom, $outlined-input-padding-top, $outlined-input-padding-bottom, $input-border-bottom

• linear-progress: DOM for linear progress buffer changed. MDCLinearProgressAdapter method getBuffer, getPrimaryBar, setStyle removed. MDCLinearProgressAdapter method setBufferBarStyle, setPrimaryBarStyle added.

• linear-progress: DOM for linear progress buffer changed. MDCLinearProgressAdapter method getBuffer, getPrimaryBar, setStyle removed. MDCLinearProgressAdapter method setBufferBarStyle, setPrimaryBarStyle added.

• typography: typography.baseline-top() and typography.baseline-bottom() are now private. Use typography.baseline() for containers and typography.text-baseline() for text with $top and $bottom params.

• chips: The touch target and text now appear inside the primary action element. Please see the readme for markup changes.

• textfield: filled text fields must include a <div class="mdc-text-field__ripple"></div>

• textfield: Filled textfields will no longer show a floating label at certain densities. This can be overridden by setting $mdc-text-field-minimum-height-for-filled-label: 40px

• chips: Both MDCChipAdapter and MDCChipSetAdapter have new methods. MDCChipSetFoundation event handlers now accept the corresponding chip event detail interface as the sole argument. The root property has been removed from the MDCChipRemovalEventDetail interface.

• line-ripple: mdc-line-ripple-color() mixin has been renamed to mdc-line-ripple-active-color()

• textfield: Default textfields must now specify mdc-text-field--filled. Disabled outlined textfields no longer have a shaded background. Height mixin no longer specifies a baseline override, use typography's baseline-top mixin.

• Four variables and a mixin in mdc-textfield were renamed to use a mdc-text-field- prefix when depended on via @import (formerly mdc-required-text-field-label-asterisk_, now required-label-asterisk_).

• textfield: icons must use .mdc-text-field__icon--leading or .mdc-text-field__icon--trailing classes. mdc-text-field-icon-color() mixin has been split into mdc-text-field-leading-icon-color() and mdc-text-field-trailing-icon-color().

• switch: Added setNativeControlAttr method in mdc-switch adapter.

• checkbox: remove event listener for 'change' and add event listener for 'click'.

• Add handleClick() method in foundation to handle click event.
• Add setCheck() method into component to change check status.

• switch: Switch DOM structure has changed. See switch README for details
• button: Variable $mdc-button-disabled-container-fill-color renamed to $mdc-button-disabled-container-color.
• Removed $edgeOptOut option from mdc-theme-prop() Sass mixin.
• chips: the handleInteraction and handleTrailingIconInteraction handlers have been removed from the MDCChipFoundation. The handleClick handler has been added to the MDCChipFoundation
• Adds new adapter methods to MDCLinearProgressAdapter.
• elevation: Functions moved into the _functions.scss file
• touchtarget: Renames mixin from mdc-touch-target-component => mdc-touch-target-margin
• grid-list: Per the deprecation notice for grid-list, this component has been removed from MDC-Web. Some of its functionalities are available in the MDC Image List package instead. It is recommended that you migrate to the mdc-image-list package to continue to receive new features and updates.