@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, Functions, and Custom Properties

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
elevation-box-shadow($z-value, $color, $opacity-boost)	Returns the box-shadow for the elevation z-space for that given elevation z-value, and optionally sets the color and/or boosts the opacity of the shadow

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.

Custom Property | Default value | Description --- | --- --mdc-elevation-overlay-opacity | 0 | The opacity of the elevation overlay. --mdc-elevation-overlay-fill-color | #fff | The color of the elevation overlay

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

10.0.0 (2021-02-05)

Bug Fixes

• data-table: fix style ordering wrt select & use new variable-width mixin (afb6889), closes #6599
• dialog: add property to customize suppressDefaultPressSelector (772cc10)
• linear-progress: fix RTL rendering (c7c5da2)
• list: add support for density scaling. (419e035)
• list: add support for non-interactive list roles. (fc8b045)
• list: ensure divider appears in IE high contrast mode. (eff7b46)
• menu: Remove anchorSize height from calculations when anchored to bottom (1631198)
• notched-outline: fix notched outline no-label style (99cfb6b)
• select: debounce click on anchor (b39094d)
• select: set aria-expanded false earlier when menu closes (df00c2b)
• slider: Add aria-hidden to value indicator container, to avoid duplicate value announcements for screenreader users. (9687353)
• slider: Adjust hidden input dimensions to take slider dimensions, such that screenreader focus indicators show a highlight around the entire slider. (fd22355)
• slider: Fire custom change event on input change. (07deaec)
• slider: Fix bug where value indicator container took space and could be hovered over / clicked when hidden. (832668d)
• slider: Mark ripple event handler as passive. Fixes #6746 (abdd100)
• slider: Remove big step options. Now that we're using a native range input, big step is not customizable - we follow browser defaults for big step. (ae27b44)
• slider: Update both thumbs' value indicator UI's if layout is invoked with undefined thumb. (489d4c2)
• slider: Use pointer-events: none instead of visibility: hidden to hide the value indicator container. Adding visibility: hidden removes the exit animation since the value indicator is immediately hidden. (a94bd8d)
• slider: Use mouse/touch events on iOS, to work around pointer events bug. (671d72d), closes #6715
• tabs: Expose min width mixin and set to 90px per spec. (c4ab987)
• theme: ensure either() works with false values (8e66dbf)
• tooltip: Adds "will-change" into CSS to prevent the tooltip from "jittering" when animating in. (7a003ac)
• tooltip: Change foundation to check for "dialog" on the anchor element's aria-haspopup attribute instead of checking for "true". (b8a1a58)
• tooltip: Clear hideTimeout in handleAnchorMouseEnter so that the tooltip will not be hidden if the user rapidly moves the mouse in and out of the anchor element. (365c693)
• tooltip: Fix rich tooltip tests to not use aria-describedby to associate rich tooltips with their anchor elements. This is because interactive rich tooltips should not be used with aria-describedby per a11y guidance. (251ac04)
• adjust meta baseline and update color mixins. (07f3e01)

Code Refactoring

• Remove MDC theme's deep-get, used sass:map's get API instead. (37fbae1)

Features

• banner: Add mobile-stacked variant support to banner. (a0b2db2)
• button: Add in HCM support to the mdc button as an opt-in mixin. (121e1f3)
• button: consolidate states into button mixins (637d15d)
• button: thread state keys through theme config (05f2496)
• checkbox: Add CSS custom properties to MDC checkbox for density theming (9244508)
• checkbox: Add validation to MDC Checkbox theme mixin (2d5f32d)
• circular-progress: do not require HTML without whitespaces (8648b82)
• dialog: add custom property for z-index (776c186)
• dialog: Adding styling for scroll bar dividers, and adding logic to show said dividers only when content is scrolled "behind" the header or footer of the dialog. (e383944)
• dialog: Adds and defines styling for the "header bar" on a full-screen dialog. (089de51)
• iconbutton: Add in HCM support to the mdc iconbutton as an opt-in mixin. (fd61b04)
• linear-progress: remove aria-valuemin/max attrs for indeterminate (4321323)
• list: support ctrl + a keyboard shortcut (eefef49), closes #6366
• list: Update the MDC component for List Evolution. (766981c)
• menu,select: enable fixed menu position in mwc-select (b9adb7a), closes #2062
• select: add mixin for variable width (30c11bf)
• slider: Add hidden input to slider, to support forms submission. This is also prep for moving to use an <input type="range"> behind the scenes, in order to support touch-based AT's. (b98d15d)
• slider: Modify continuous slider to use step value by default, and give clients the option to customize step value for continuous sliders. (7ad038e)
• slider: Use input with type="range" to back slider component. This ensures that sliders can be adjusted with touch-based assistive technologies, as the current ARIA spec for sliders is not compatible with e.g. TalkBack/Android. (9083b7d)
• snackbar: Add 1px transparent border for high contrast support (15a4d40)
• theme: add either() utility function (5268222)
• theme: add validation option to disallow custom properties (fec7b42)
• theme: Added validation mixin to validate provided theme configuration keys (1c156d6)
• theme: allow lists in replace maps (d2959b1)
• theme: emit CSS var() declarations when provided a standalone custom prop (1a3a396)
• tooltip: Add positioning adjustment and position specification for rich tooltips. Rich tooltips default to the END position and does not support CENTER positioning. (384a8ee)
• tooltip: Added persistent variant for rich tooltips that shows/hides based on mouse clicks on the anchor element. Clicks on elements other than the anchor will also hide the persistent variant. (9775856)
• tooltip: Adds transform-origin on tooltip surface so tooltip entrance animation has a direction based on its alignment with the anchor element. (623af86)
• tooltip: Adjust tooltip position on scroll and resize events. This ensures that the tooltip remains pinned to the anchor element despite page movement. (a415276)
• tooltip: Adjusting tooltip positioning logic so that the tooltip remains within the viewport even if the anchor element is partially off-screen. (482ff90)
• tooltip: Change rich tooltip to use position absolute instead of fixed and rely on a position relative parent element so that if the parent has a transform, perspective, or filter property set to something other than none, the positioning would still work. (0c95c9f)
• tooltip: Define styling to set the full-screen dialog size depending on the viewport size. (fe13dd1)
• tooltip: Expose hide and isShown methods in the MDCTooltip component. This allows MDC clients to create their own class to enforce only one tooltip being shown at a time. (c5e18b0)
• tooltip: Hide rich tooltip if mouse leaves rich tooltip. Rich tooltip persists if mouse leaves rich tooltip and enters anchor. (6d8574f)
• tooltip: Reducing minimum threshold distance between tooltip and viewport from 32px to 8px. (23491cf)
• tooltip: Restore focus to the anchor element when the ESC button is pressed while the focus is in the tooltip for rich tooltips. Default rich tooltips should have focus restored to anchor and not have rich tooltips show. (eabf9d5)
• tooltip: Set up base sass for rich tooltip. Rich tooltips are currently in development and is not yet ready for use. (4ae94ff)
• tooltip: Set up rich tooltip to persist if mouse leaves anchor and enters rich tooltip. (c927a5d)
• tooltip: The aria-expanded attribute of the anchor element will only be changed for anchor elements with interactive rich tooltips. Non-interactive rich tooltip anchor elements do not have the aria-haspopup and aria-expanded attributes. (c5dda80)
• tooltip: When the anchor element blurs, the rich tooltip will only be hidden if the focus is changed to a non-rich tooltip element. (6871336)
• Added global variable to conditionally emit CSS selector fallback declarations (7b0e2b3)
• tooltip: When the rich tooltip element focuses out, hide the rich tooltip if the new focused element is not the anchor element or an element within the rich tooltip. (1085c3b)

BREAKING CHANGES

• theme: custom-properties.apply() has been renamed to declaration() to better align with css.declaration()
• tooltip: Added adapter methods:
  • getComputedStyleProperty(propertyName: string): string;
  • getParentBoundingRect(): ClientRect|null;
• tooltip: Added adapter method:
  • tooltipContainsElement(element: HTMLElement): boolean;
• Removed deep-get() API from mdc-theme, use sass:map's get() API instead.
• tooltip: Added adapter method:
  • anchorContainsElement(element: HTMLElement): boolean;
• slider: Slider is now backed by an input of type="range". Additionally, adapter methods (focusInput, isInputFocused, registerInputEventHandler, deregisterInputEventHandler) were added.
• tooltip: Added adapter methods:
  • setAnchorAttribute(attr: string, value: string): void;
  • registerEventHandler<K extends EventType>( evtType: K, handler: SpecificEventListener<K>): void;
  • deregisterEventHandler<K extends EventType>( evtType: K, handler: SpecificEventListener<K>): void;
• slider: Adds slider adapter methods (get/setInputValue, get/setInputAttribute, removeInputAttribute). Slider DOM structure now contains a hidden input.