Loading…

Border Beam

beta

A short light that travels round the border of any button, card or field it sits in — always, or only on hover and focus.

Effects & motion
1 file
1 npm package
Accessibility notes

Playground

Installation

One command and the file is in your project, or copy it in by hand.

$pnpm dlx @dowel-ui/cli add border-beam

npm packages installed: class-variance-authority.

Usage

Imported from your own path — the file is yours, so this is an import like any other.

app/page.tsxTSX

import { BorderBeam } from "@/components/ui/border-beam";

Examples

Every example the tests run, live and operable, side by side.

Default
Generate Button
On Hover
Pair

API

Generated from the component's own types, so a prop cannot appear here without existing.

<BorderBeam>

Prop	Type	Default
`color` The colour of the beam's head, overriding `tone`. Any CSS colour; prefer a token.	`string`	—
`colorTo` The colour its tail fades through, overriding `tone`.	`string`	—
`delay` Wait before the first trip, in milliseconds. Negative starts part-way round. Default 0.	`number`	`0`
`duration` One full trip round the border, in milliseconds. Default 6000.	`number`	`6000`
`glow`	`boolean`	—
`length` How much of the border the beam covers, 0–1. Default 0.2.	`number`	`0.2`
`reverse` Travel anticlockwise.	`boolean`	`false`
`thickness` Width of the beam in pixels. Default 1 — the width of a hairline border.	`number`	`1`
`tone`	`"primary" \| "foreground" \| "info" \| "success" \| "warning" \| "destructive" \| "brand"`	`"primary"`
`trigger` `always` runs continuously; `hover` shows and runs it only while the parent is hovered or holds focus.	`"always" \| "hover"`	`"always"`

Plus every attribute of <span> except children, color.

Accessibility

Pure decoration: the beam is aria-hidden and takes no pointer events, so the element it decorates keeps its role, name, focus ring and hit area. It never carries meaning — do not use it as the only sign that something is selected, active or loading. Under reduced motion it rests at the start of its path instead of travelling; in forced-colours mode it is removed and the element's own border carries the shape. With trigger="hover" it also appears for keyboard focus, so pointer and keyboard users see the same thing.

Quality

Measured from the source and its tests at build time.

All scores

8/8

checks passed

Tested — passes
axe assertion — passes
Keyboard tested — does not apply
Storybook examples — passes
Accessibility documented — passes
Semantic tokens only — passes
Motion from tokens — passes
className merged — passes
Visible focus — does not apply
No fixed widths — passes

Prop

Type

Default

color

The colour of the beam's head, overriding tone. Any CSS colour; prefer a token.

string

—

colorTo

The colour its tail fades through, overriding tone.

string

—

delay

Wait before the first trip, in milliseconds. Negative starts part-way round. Default 0.

number

0

duration

One full trip round the border, in milliseconds. Default 6000.

number

6000

glow

boolean

—

length

How much of the border the beam covers, 0–1. Default 0.2.

number

0.2

reverse

Travel anticlockwise.

boolean

false

thickness

Width of the beam in pixels. Default 1 — the width of a hairline border.

number

1

tone

"primary"

trigger

always runs continuously; hover shows and runs it only while the parent is hovered or holds focus.

"always" | "hover"

"always"