Installation

// with npm
npm install @ax-design/elevation

// with yarn
yarn add @ax-design/elevation

and import it:

//CommonJS
require('@ax-design/elevation').register();

//ESModule
import { register } from '@ax-design/elevation';
register();

If you don't use a bundler, load build/main.js (it exposes AxElevation) or import build/index.mjs.

Usage

Wrap the content that should float above the page in an ax-elevation component:

<ax-elevation>
  elevation!
</ax-elevation>

Style Controlling

--elevation-depth

Type: <number>

Default: 0

Description: How high the element floats. The shadow is two layers that grow with the depth: a large, soft one and a small, darker one under the element. 0 draws no shadow. Like the original, the property is inherited. The shadow follows WinUI's ThemeShadow: it is hidden in forced colors mode (Windows High Contrast), as box-shadow was, and when transparency effects are off (prefers-reduced-transparency: reduce). A page can also hide it with setAlwaysUseFallback(true) from @ax-design/surface, as Windows does on battery saver or slow hardware.

--elevation-color

Type: <color>

Default: rgb(0, 0, 0)

Description: The colour of the shadow. The alpha of each of the two shadows is multiplied by the colour's own alpha, so the default is the original black shadow, and a translucent colour makes a lighter one. Like the depth, the property is inherited.

With Surface

Elevation runs on Surface. The shadow follows the shape of the element, so the shape properties of Surface apply to ax-elevation too:

ax-elevation {
  --elevation-depth: 16;
  --ax-radius: 50%;
  --ax-corner-shape: scoop;
  --ax-corner-shoulder-radius: 8px;
}

You can also use it as a layer of ax-surface, together with the other layers:

import { register } from '@ax-design/surface';
import { registerElevationLayer } from '@ax-design/elevation';

registerElevationLayer();
register();

<ax-surface layers="elevation fill reveal">...</ax-surface>

Put elevation first, so the other layers paint on top of it. The shadow is cut out under the shape, so a translucent layer like acrylic does not darken. It fades with the opacity of motion(), and in Firefox during a 3D motion it follows the projected outline of the surface.

Changelog

See CHANGELOG.md.

Development

bun install
bun run build         # es/, build/index.mjs, build/main.js
bun run check         # type check
bun run test:browser  # browser tests