Underlay

Render a backdrop-blurred surface with a dotted grid or gradient fill and an optional fade-out mask.

Underlay renders a Box with backdrop-filter: blur(), a background pattern, and an optional linear-gradient mask. It is typically placed behind sticky headers or toolbars so content scrolling underneath is blurred. It has no intrinsic size or position. Scroll the list in the demo to see the effect.

Today

Review pull requests

Update roadmap

Plan sprint

Write release notes

Reply to support

Book design review

Import#

typescript

import { Underlay } from "@reactberry/system/blocks";

Usage#

typescript

import { Underlay } from "@reactberry/system/blocks";
import { Box, Text } from "@reactberry/system/elements";

export default function StickyHeader() {
  return (
    <Box position="sticky" top="0" zIndex={10}>
      <Underlay position="absolute" top="0" left="0" right="0" height="6rem" color="base" dotColor="transparent" />
      <Box position="relative" p="m">
        <Text as="h1" fontSize="l">Dashboard</Text>
      </Box>
    </Box>
  );
}

Examples#

Gradient fill#

Set both stop1 and stop2 to replace the dot pattern with a gradient. hasMask={false} turns off the fade-out mask.

Frosted panel

Dot grid#

dotColor, backgroundColor, dotSize and gridSize shape the dot pattern; blurAmount sets the blur radius.

API#

Underlay#

Prop	Type	Default	Description
`backgroundColor`	`string`	—	Colour between the dots. Falls back to `currentColor`. It is not applied as the CSS `background-color`.
`dotColor`	`string`	—	Colour of the dots. Falls back to `transparent`.
`dotSize`	`number`	`1`	Pixel position where the dot fades to `backgroundColor`.
`gridSize`	`number`	`4`	Size in pixels of each repeating tile of the dot pattern.
`blurAmount`	`number`	`12`	Backdrop blur radius in pixels.
`maskGradient`	`string`	—	Contents of the mask's `linear-gradient()`. Falls back to `"rgb(0, 0, 0) 33%, rgba(0, 0, 0, 0) 100%"`.
`hasMask`	`boolean`	`true`	Applies a CSS `mask` with a linear gradient.
`stop1`	`string`	—	First colour of a gradient fill. Needs `stop2`.
`stop2`	`string`	—	Second colour of a gradient fill. With `stop1`, replaces the dot pattern with `linear-gradient(to bottom right, stop1, stop2)`.

All remaining props are spread onto the root Box after its defaults (bg="transparent", backgroundImage, backgroundSize), so they can override them.

Accessibility#

The element is purely decorative and sets no ARIA attributes. Add aria-hidden through the spread props if needed.

Notes#

With the defaults (dotColor unset), the pattern is a radial gradient from transparent to currentColor, so the inherited or color prop value sets the visible fill.
With a gradient fill, gridSize is ignored.
After mount, and whenever blurAmount, width, height, or expanded change, an effect clears and re-applies the inline backdropFilter to force the browser to repaint the blur. expanded is not declared in the props type but is read from the spread props and forwarded to the Box.
No animation is involved, so there is no reduced-motion handling.
UnderlayProps is not exported.