2020-09-23 03:11:03 +03:00
# `elevation-overlay` [![Published on npm](https://img.shields.io/npm/v/@material/mwc-elevataion-overlay.svg)](https://www.npmjs.com/package/@material/mwc-elevataion-overlay)
> IMPORTANT: The Material Web Components are a work in progress and subject to
> major changes until 1.0 release.
An overlay is a semi-transparent covering on an element that indicates its
state. Overlays provide a systematic approach to visualizing states by using
opacity.
< img src = "images/dark_mode.png" height = "163px" >
[Material Design Guidelines: States - Overlay ](https://material.io/design/interaction/states.html#anatomy )
2021-08-13 01:38:49 +03:00
[Demo ](https://material-components.github.io/material-web/demos/elevation-overlay/ )
2020-09-23 03:11:03 +03:00
## Installation
```sh
npm install @material/mwc -elevation-overlay
```
> NOTE: The Material Web Components are distributed as ES2017 JavaScript
> Modules, and use the Custom Elements API. They are compatible with all modern
> browsers including Chrome, Firefox, Safari, Edge, and IE11, but an additional
> tooling step is required to resolve *bare module specifiers*, as well as
> transpilation and polyfills for IE11. See
> [here](https://github.com/material-components/material-components-web-components#quick-start)
> for detailed instructions.
## Example usage
### Standard
< img src = "images/dark_mode_button.gif" height = "250px" >
```html
< style >
body {
/* dark mode surface color */
background-color: #212121 ;
}
< / style >
< my-element > < / my-element >
< script type = "module" >
2021-05-18 03:17:34 +03:00
import {styles as elevationStyle} from '@material/mwc-elevation-overlay/mwc-elevation-overlay.css';
2021-09-29 00:58:32 +03:00
import {LitElement, css, html} from 'lit';
2020-09-23 03:11:03 +03:00
class MyElement extends LitElement {
static get styles() {
return [
// use overlay styles
elevationStyle,
// this element's styles
css`
button {
/* generic floating elevation */
--mdc-elevation-overlay-opacity: 9%;
}
button:hover,
button:focus {
/* higher interaction elevation */
--mdc-elevation-overlay-opacity: 15%;
}
button:active {
/* highest interaction elevation */
--mdc-elevation-overlay-opacity: 24%;
}
button {
/* Dark mode surface color */
background-color: #212121 ;
/* bounds overlay to element */
position: relative;
/* dark mode text color */
color: #eeeeee ;
/* misc button styling */
border: none;
border-radius: 26px;
height: 52px;
width: 52px;
font-size: 2em;
outline: none;
}
`,
];
}
render() {
return html`
< button >
<!--
Must have class mdc-elevation-overlay and must always come before a
ripple node.
-->
< div class = "mdc-elevation-overlay" > < / div >
<!-- surface content -->
+
< / button >
`;
}
}
customElements.define('my-element', MyElement);
< / script >
```
### Customize colors
< img src = "images/styled.gif" height = "250px" >
Appending to the example from above:
```css
button {
/* Note: try to keep luminosity high on low-opacity colors on dark */
--mdc-elevation-overlay-fill-color: lightgreen;
}
button:hover,
button:focus {
--mdc-elevation-overlay-fill-color: yellow;
}
button:active {
--mdc-elevation-overlay-fill-color: red;
}
.mdc-elevation-overlay {
/* transition animation to sync up color with opacity change */
transition: opacity 280ms cubic-bezier(0.4, 0, 0.2, 1), background-color 280ms cubic-bezier(0.4, 0, 0.2, 1);
}
```
## API
### CSS Custom Properties
Name | Default | Description
-------------------------------------- | ------------------------------------- | -----------
`--mdc-elevation-overlay-opacity` | `0` | Opacity of the overlay.
2020-09-25 02:17:51 +03:00
`--mdc-elevation-overlay-fill-color` | `#fff` | Fill color of the overlay.
2020-09-23 03:11:03 +03:00
`--mdc-elevation-overlay-width` | `100%` | Width of the overlay (`absolute` positioning may need to be set as well e.g. `.mdc-elevation-overlay {--mdc-elevation-overlay-width: 50%; left: 50%;}` ).
`--mdc-elevation-overlay-height` | `100%` | Height of the overlay (`absolute` positioning may need to be set as well e.g. `.mdc-elevation-overlay {--mdc-elevation-overlay-height: 50%; top: 50%;}` ).
## Additional references
2020-09-25 02:17:51 +03:00
- [Material Dark Theme - Properties ](https://material.io/design/color/dark-theme.html#properties )