Skip to content
Components

BorderBeam

A soft rotating "border beam" shimmer used to draw attention to an element before the user interacts with it. Two usage shapes: 1. Wrapper - pass children and the beam wraps them in a relative box. 2. Overlay - render without children inside an existing relative parent. Honours prefers-reduced-motion (renders nothing - a static ring would be louder than the animated sweep it's meant to replace). When visible flips to false, the beam fades out then unmounts so its rAF loop stops.

Terracotta Hex

Hand-glazed field tile, just added to the library.

New arrival

Usage

@instruments/materia-ui/components/border-beam

<BorderBeam radius={24}>
  <Card className="w-72">
    <CardHeader>
      <CardTitle>Terracotta Hex</CardTitle>
    </CardHeader>
    <CardContent>
      <Text size="paragraph-sm" variant="muted">
        Hand-glazed field tile, just added to the library.
      </Text>
    </CardContent>
    <CardFooter>
      <Badge emphasis="soft" tone="brand">
        New arrival
      </Badge>
    </CardFooter>
  </Card>
</BorderBeam>

Best practices

  • Animate the --border-beam-angle custom property (as the source does), never rotate the masked ring - a rotated box swings its mask outside a wide pill's bounds and renders as a stray streak, not a border orbit.

  • Requires ReducedMotionProvider; under reduced motion it renders nothing (a static ring would read louder than the sweep it replaces), so don't add your own fallback border.

  • Use it as an attention / "try me" cue on an idle surface, not a loading state - content placeholders want Skeleton, and a periodic liveness flick wants Shine.

Props

PropTypeDefaultDescription
visibleboolean | undefined

Drives fade in/out of the beam

strengthnumber | undefined

Multiplier on peak alpha (0–1)

colorstring | undefined

Beam peak colour (any CSS colour). Defaults to the theme foreground so the sweep reads on light and dark surfaces alike - pass a hue to tint it, e.g. a detected colour inviting interaction.

durationnumber | undefined

Full rotation period in seconds

radiusstring | number | undefined

Ring border-radius (defaults to fully round)

thicknessnumber | undefined

Ring stroke thickness in px

shadowSize"none" | "xs" | "sm" | "lg" | "xl" | "2xl" | "md" | undefined

Drop-shadow token applied to the ring, or "none" to disable

classNamestring | undefined

Positional overrides forwarded to the ring

childrenReactNode

When provided, the beam wraps children in a relative container. When omitted, the beam assumes the nearest ancestor is already position: relative.

Also exports

  • interfaceBorderBeamProps

Composition

Builds on

FadeOverlay