Connection Beam

Installation

Copy the source into your project, or keep it behind a package.

npx shadcn@latest add Tinkerers-Labs/mischief-ui/connection-beam

import { ConnectionBeam } from "mischief-ui/connection-beam"

1"use client"2 3import * as React from "react"4 5import { cn } from "@/lib/utils"6 7export type ConnectionBeamProps = Omit<8  React.SVGAttributes<SVGSVGElement>,9  "children"10> & {11  /** The positioned box both endpoints live inside. */12  containerRef: React.RefObject<HTMLElement | null>13  fromRef: React.RefObject<HTMLElement | null>14  toRef: React.RefObject<HTMLElement | null>

Usage

export function Architecture() {
  const container = useRef(null)
  const retriever = useRef(null)
  const model = useRef(null)

  return (
    <div ref={container} className="relative">
      <Node ref={retriever} />
      <Node ref={model} />
      <ConnectionBeam
        containerRef={container}
        fromRef={retriever}
        toRef={model}
      />
    </div>
  )
}

It reads the elements, not a list of points

A diagram drawn from coordinates is right once, on the screen it was drawn for. Give this the two elements instead and the geometry comes from where they actually are, so the beam survives a reflow: resize the window, wrap the boxes onto another line, put the whole thing in a panel that opens, and the line follows.

Both endpoints and the box around them are watched, which covers layout changes that no resize event would report.

The container has to be a positioned element, since the beam is laid over it. Everything else is measured relative to that box, so page scrolling never enters into it.

Where it attaches

Beams are drawn between the facing edges rather than the centres, so the line meets a box instead of disappearing under it. Which pair of edges depends on how the two are arranged: side by side, it leaves the right and arrives at the left, and stacked, it leaves the bottom and arrives at the top. anchor overrides that when the automatic choice is not the one you meant.

The bow is square to the run, so two elements connected either way round curve the same amount rather than one of them bending the wrong way. A curvature of nought is a straight line, and a negative one bends the other way, which is what separates several beams landing on the same element.

The part that moves

The line and the travelling part are the same path drawn twice. The moving one is a dash, and the dashes are measured against a normalised path length, so extent is a share of the line rather than a number of pixels that would mean something different on every screen.

Stagger several beams with delay rather than giving them different durations. Different durations drift apart and eventually all arrive at once, which reads as a coincidence rather than a sequence.

{sources.map((source, index) => (
  <ConnectionBeam
    key={source.id}
    containerRef={container}
    fromRef={source.ref}
    toRef={model}
    curvature={(index - 1) * 24}
    delay={index * 0.6}
  />
))}

API

Accessibility

The beam is decoration and carries aria-hidden: it illustrates a relationship that the elements it joins should already state, so nothing is lost when it is not rendered. Under prefers-reduced-motion the travelling part is not drawn at all rather than parked mid-path, where it would read as a stray dash nobody put there, and the line it runs along stays exactly as it was. Because the geometry is measured rather than fixed, a page zoomed or reflowed to a narrow width redraws correctly instead of leaving the line pointing somewhere the boxes no longer are.