Ballmac UI home

Animated Beam

An SVG beam that connects two elements with a curved path and sends a glowing gradient pulse along it. Follows layout changes, pauses off-screen, static under reduced motion.

Database
Repository
Email
Calendar
Documents
Web search
Agent
agent
Your app
your app

Installation

$ pnpm dlx shadcn@latest add @ballmac/animated-beam

Usage

import { AnimatedBeam } from "@/components/ballmac/animated-beam"

The full example is in the Code tab above.

Examples

Two-way sync

API reference

PropTypeDefault
containerRef*

The positioned element both endpoints live in. The beam's SVG covers it.

React.RefObject<HTMLElement | null>—
fromRef*

Element the beam starts from (its center, plus the start offsets).

React.RefObject<HTMLElement | null>—
toRef*

Element the beam ends at (its center, plus the end offsets).

React.RefObject<HTMLElement | null>—
curvature

How far the curve bows, in pixels. Positive bends up, negative bends down, 0 is straight.

number0
reverse

Send the pulse from `toRef` to `fromRef`.

booleanfalse
duration

Seconds for the pulse to travel the path once.

number3.5
delay

Seconds before the first pulse. Stagger beams with different delays.

number0
repeatDelay

Seconds to wait between pulses.

number0.8
pulseLength

Length of the pulse as a fraction of the path (0–1).

number0.35
startXOffset

Horizontal offset of the start point in pixels.

number0
startYOffset

Vertical offset of the start point in pixels.

number0
endXOffset

Horizontal offset of the end point in pixels.

number0
endYOffset

Vertical offset of the end point in pixels.

number0
pathColor

Color of the resting path. Any CSS color or var().

string"var(--foreground)"
pathWidth

Stroke width of the path and pulse in pixels.

number2
pathOpacity

Opacity of the resting path (0–1).

number0.1
gradientStartColor

Color at the tail of the pulse.

string"var(--chart-1)"
gradientStopColor

Color at the head of the pulse.

string"var(--chart-4)"

Also accepts the standard attributes of its root element.

Quality scorecard

6/6

Every applicable check passes

Measured in Chromium 153.0.8010.12 on October 19, 2026, on version 1.0.0, across 2 examples.

How we measure
  • Passed: Accessibility scan

    No serious or critical issues in light and dark, on a phone and a desktop (axe-core 4.13.0, WCAG 2.1 AA and best-practice rules).

  • Passed: Small screens

    No sideways scrolling at 360, 390 or 1280 px wide.

  • Passed: Reduced motion

    No endless animation to begin with.

  • Passed: Right to left

    Mirrors correctly in Arabic, Hebrew, Persian and Urdu layouts (0% of elements off the mirror, limit 15%).

  • Passed: Clean console

    No console errors or React hydration errors while loading.

  • Not applicable: Keyboard

    Static content: nothing to focus.

  • Not applicable: Loading, empty and error

    Does not show data or take submissions.

  • Passed: Automated tests

    Covered by animated-beam.test.tsx.

  • For information: Footprint

    3.0 KB of source (gzip) in 1 file. Installs motion.

Automated checks find a subset of problems and do not replace testing with a screen reader and a keyboard in your own app. What they miss.

Use with AI

Give a relative container a ref, give each endpoint element a ref, and render <AnimatedBeam containerRef fromRef toRef /> inside the container once per connection. Put endpoint nodes above the beams with relative z-10. The SVG is aria-hidden and pointer-events-none. With the shadcn MCP server set up (guide), ask your agent:

Add the Ballmac UI Animated Beam (@ballmac/animated-beam) to this project with the shadcn MCP, then use it where it fits.

Use it for

  • Integration diagrams: tools or data sources flowing into an agent or product
  • Showing a request path between services on a landing page
  • Explaining a sync or pipeline visually in a feature section

Not for

  • Real, data-driven graphs with many nodes (use a graph library)
  • Conveying state on its own; label the nodes, the beam is decorative

Registry JSON: https://ui.ballmac.com/r/animated-beam.json

Credits

Based on Magic UI Animated Beam, adapted by Ballmac. Free to use in personal and commercial projects.

Registry
shadcn/utils

Ballmac UI Pro

Need the whole screen, not one piece?

311 premium blocks (dashboards, settings, calendars, mail, shops, onboarding), a private shadcn registry and Figma tokens. Blocks that show data come with loading, empty and error states built in.

Not ready? Try three Pro blocks free

Leave your email and the blocks appear right here, ready to copy. Yours to use in any project.