Border Beam
Draw attention to a card, panel, or CTA with Border Beam, a React overlay that animates a glowing gradient beam around its border. Install via the shadcn CLI.
What it is & when to use
Border Beam is a decorative overlay that animates a glowing gradient beam traveling around an element's border. Drop it inside a relatively positioned container and it fills the border with a conic-gradient beam masked to the edge, looping continuously. Props control borderWidth, duration, delay, the from and to colors, and a reverse direction. It is aria-hidden and pointer-events-none, so use it to highlight cards, buttons, or panels without affecting interaction.
Browse all UtilityPreview
Switch between light and dark to inspect the embedded Storybook preview.
Installation
pnpm dlx shadcn@latest add https://ui.vllnt.com/r/border-beam.jsonStorybook
Explore all variants, controls, and accessibility checks in the interactive Storybook playground.
View in StorybookCode
import * as React from "react";
import { cn } from "../../lib/utils";
export type BorderBeamProps = React.ComponentPropsWithoutRef<"span"> & {
borderWidth?: number;
colorFrom?: string;
colorTo?: string;
delay?: number;
duration?: number;
reverse?: boolean;
};
export const BorderBeam = ({
borderWidth = 1,
className,
colorFrom = "oklch(var(--primary) / 0.85)",
colorTo = "oklch(var(--ring) / 0.25)",
delay = 0,
duration = 6,
ref,
reverse = false,
style,
...props
}: BorderBeamProps & { ref?: React.Ref<HTMLSpanElement> }) => {
const beamStyle: React.CSSProperties = {
animationDelay: `${delay}s`,
animationDirection: reverse ? "reverse" : "normal",
animationDuration: `${duration}s`,
animationIterationCount: "infinite",
animationName: "vllnt-border-beam-angle",
animationTimingFunction: "linear",
background: `conic-gradient(from var(--vllnt-border-beam-angle, 90deg), transparent 0deg, transparent 220deg, ${colorFrom} 280deg, ${colorTo} 335deg, transparent 360deg)`,
borderRadius: "inherit",
boxSizing: "border-box",
mask: "linear-gradient(#fff 0 0) content-box, linear-gradient(#fff 0 0)",
maskComposite: "exclude",
padding: `${borderWidth}px`,
WebkitMask:
"linear-gradient(#fff 0 0) content-box, linear-gradient(#fff 0 0)",
WebkitMaskComposite: "xor",
...style,
};
return (
<span
aria-hidden="true"
className={cn(
"pointer-events-none absolute inset-0 rounded-[inherit]",
className,
)}
ref={ref}
style={beamStyle}
{...props}
/>
);
};
BorderBeam.displayName = "BorderBeam";
Frequently asked questions
- What is Border Beam?
- Border Beam is a React decorative component from VLLNT UI that animates a glowing gradient beam around the border of a highlighted surface. It renders an aria-hidden overlay and does not capture pointer events.
- How do I add Border Beam?
- Run `pnpm dlx shadcn@latest add https://ui.vllnt.com/r/border-beam.json` to install Border Beam via the shadcn CLI. Place it inside a relatively positioned element to draw the animated border.
- How do I customize Border Beam's animation?
- Adjust the duration and delay props to time the loop, set reverse to flip its direction, tune borderWidth, and pass colorFrom and colorTo to change the gradient. Defaults derive from the primary and ring theme colors.