Border Beam

A comet of light that laps the border of your content.

Deploying to production

Usage

import { BorderBeam } from '@appica/ui-react/border-beam'

<BorderBeam>
  <YourContent />
</BorderBeam>

BorderBeam is a <div> wrapper that traces a single comet of light around its own border: a bright head with a tail fading to transparent, looping forever. The beam is painted as a conic sweep clipped to a hairline ring, so it follows the wrapper's own border-radius exactly, from a subtle rounded-xl card to a fully rounded pill, with no radius prop to keep in sync.

Give the wrapper the same size and radius as the content it wraps (that's what the beam traces) and tune the look with color, length (how much of the lap the comet spans), thickness, and speed. The beam layer is aria-hidden and pointer-events-none, so it never reaches assistive tech or intercepts clicks, and the wrapper forwards className, style, and any native <div> attributes.

Examples

Basic beam

The default beam is a 1px comet in the --primary color, spanning 10% of the border and taking 5 seconds per lap. Match the wrapper's radius to your content's (rounded-2xl here) so the beam hugs the corners.

Syncing your workspace

import { BorderBeam } from '@appica/ui-react/border-beam'

export default function BorderBeamBasic() {
  return (
    <BorderBeam className="w-full max-w-70 rounded-2xl">
      <div className="bg-background border-border text-foreground-intense flex min-h-32 items-center justify-center rounded-2xl border px-6 text-center text-sm font-medium">
        Syncing your workspace
      </div>
    </BorderBeam>
  )
}

Color

color takes any CSS color - a hex, rgb(), oklch(), or a design token - and becomes the bright head of the gradient, which always fades to transparent along the tail. The default, var(--primary), is near-black in light mode and white in dark mode, so it reads on either surface. For an accent, reach for a token's -emphasis step (var(--success-emphasis)): those hold up against both a light and a dark background, which the base step doesn't. Over a colored or dark child surface, pick a color with contrast against that surface rather than against the page.

Primary

Secondary

Success

Custom

import { BorderBeam } from '@appica/ui-react/border-beam'

const CARD =
  'bg-background border-border text-foreground flex min-h-24 items-center justify-center rounded-2xl border px-5 text-center text-sm'

export default function BorderBeamColor() {
  return (
    <div className="flex flex-wrap items-center justify-center gap-6">
      <BorderBeam className="w-40 rounded-2xl" length={20}>
        <div className={CARD}>Primary</div>
      </BorderBeam>
      <BorderBeam className="w-40 rounded-2xl" color="var(--secondary-emphasis)" length={20}>
        <div className={CARD}>Secondary</div>
      </BorderBeam>
      <BorderBeam className="w-40 rounded-2xl" color="var(--success-emphasis)" length={20}>
        <div className={CARD}>Success</div>
      </BorderBeam>
      <BorderBeam className="w-40 rounded-2xl" color="#A78BFA" length={20}>
        <div className={CARD}>Custom</div>
      </BorderBeam>
    </div>
  )
}

Length, thickness, and speed

length is a percentage of one lap rather than a pixel value, so a comet keeps its proportions whatever the element's size: a small value reads as a traveling spark, a large one as a long sweeping streak. thickness is in px, and speed is the seconds one lap takes.

Short and quick

Long and slow

3px thick

import { BorderBeam } from '@appica/ui-react/border-beam'

const CARD =
  'bg-background border-border text-foreground flex min-h-24 items-center justify-center rounded-2xl border px-5 text-center text-sm'

export default function BorderBeamSizeAndSpeed() {
  return (
    <div className="flex flex-wrap items-center justify-center gap-6">
      <BorderBeam className="w-44 rounded-2xl" length={3} speed={3}>
        <div className={CARD}>Short and quick</div>
      </BorderBeam>
      <BorderBeam className="w-44 rounded-2xl" length={30} speed={10}>
        <div className={CARD}>Long and slow</div>
      </BorderBeam>
      <BorderBeam className="w-44 rounded-2xl" thickness={3}>
        <div className={CARD}>3px thick</div>
      </BorderBeam>
    </div>
  )
}

Staggering a group

A row of beams starting together looks mechanical. Pass a negative delay to start a beam mid-lap, which spreads a group out around its own cycle.

delay=0

delay=-2

delay=-4

import { BorderBeam } from '@appica/ui-react/border-beam'

const CARD =
  'bg-background border-border text-foreground flex min-h-28 items-center justify-center rounded-2xl border px-5 text-center text-sm'

const DELAYS = [0, -2, -4]

export default function BorderBeamStagger() {
  return (
    <div className="flex flex-wrap items-center justify-center gap-6">
      {DELAYS.map((delay) => (
        <BorderBeam key={delay} className="w-40 rounded-2xl" delay={delay}>
          <div className={CARD}>delay={delay}</div>
        </BorderBeam>
      ))}
    </div>
  )
}

Reveal on interaction

Set revealOn to keep the beam hidden until an interaction, then fade it in (the beam resumes from paused, so it always starts its lap from the top). Accepts 'hover' (pointer-only, like Tailwind's hover: variant) and 'press' (works on touch), or an array to combine them. Since 'hover' can't fire on touch, opt into showOnTouch to keep the beam persistently visible there instead of hidden. Add pressScale so the beam shrinks with a button's own active-press scale.

import { BorderBeam } from '@appica/ui-react/border-beam'
import { buttonVariants } from '@appica/ui-react/button'
import { cn } from '@/lib/utils'

export default function BorderBeamRevealOnInteraction() {
  return (
    <div className="flex flex-wrap items-center justify-center gap-8">
      <BorderBeam revealOn="hover" showOnTouch pressScale className="rounded-full">
        <button type="button" className={cn(buttonVariants({ variant: 'outline', size: 'lg' }), 'rounded-full')}>
          Hover me
        </button>
      </BorderBeam>
      <BorderBeam revealOn="press" pressScale className="rounded-full">
        <button type="button" className={cn(buttonVariants({ variant: 'outline', size: 'lg' }), 'rounded-full')}>
          Press me
        </button>
      </BorderBeam>
    </div>
  )
}

Controlled (loading state)

For event-driven states (a request in flight, a deploy running) drive the beam with the controlled reveal boolean instead. It's OR-ed with any revealOn interaction, so you can combine "beam on hover" with "beam while loading". Click the button to kick off a mock request.

'use client'

import { useRef, useState } from 'react'
import { BorderBeam } from '@appica/ui-react/border-beam'
import { buttonVariants } from '@appica/ui-react/button'
import { Spinner } from '@appica/ui-react/spinner'
import { Sparkle } from '@appica/icons-react'
import { cn } from '@/lib/utils'

export default function BorderBeamLoading() {
  const [loading, setLoading] = useState(false)
  const timer = useRef<ReturnType<typeof setTimeout> | null>(null)

  function run() {
    if (timer.current) clearTimeout(timer.current)
    setLoading(true)
    timer.current = setTimeout(() => setLoading(false), 5000)
  }

  return (
    <BorderBeam reveal={loading} color="#A78BFA" length={15} thickness={1.5} speed={2} className="rounded-full">
      <button
        type="button"
        onClick={run}
        className={cn(buttonVariants({ variant: 'outline', size: 'lg' }), 'rounded-full')}
      >
        {loading ? (
          <Spinner variant="sparkle" currentColor data-icon="start" className="text-xl" />
        ) : (
          <Sparkle data-icon="start" />
        )}
        {loading ? 'Thinking…' : 'Ask AI'}
      </button>
    </BorderBeam>
  )
}

RTL

Every Appica UI component supports right-to-left layouts out of the box. Set the dir attribute on a container (commonly your <html> element) so CSS logical properties resolve correctly, and wrap your tree in DirectionProvider so direction-aware behavior follows the same direction.

import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}

The beam is mirrored under dir="rtl", so it laps counterclockwise and still leads with its bright head, matching the reading direction. No prop is involved; the layer follows the dir attribute. For setup details and caveats, see the RTL guide.

جارٍ تحليل بياناتك

يمسح الشعاع حدود البطاقة عكس عقارب الساعة في التخطيط من اليمين إلى اليسار.

API reference

Prop	Type	Default	Description
`color`	`string`	`'var(--primary)'`	Beam color. It lights the head of the comet and fades to transparent along the tail, so pass a solid color rather than a gradient.
`length`	`number`	`10`	How much of the border the comet spans, in percent of one lap.
`thickness`	`number`	`1`	Beam thickness in px.
`speed`	`number`	`5`	Seconds for one full lap around the border.
`delay`	`number`	`0`	Seconds before the first lap starts. Negative values start the beam mid-lap, which is how you desynchronize a group of cards.
`revealOn`	`'hover' \| 'press' \| Array`	-	Reveal only on interaction. `'hover'` is pointer-only; `'press'` works on touch. Combine via an array. Omit for always-on.
`reveal`	`boolean`	-	Controlled visibility for programmatic states (loading, etc.); OR-ed with `revealOn`.
`showOnTouch`	`boolean`	`false`	With `revealOn="hover"`, keep the beam visible on touch devices (which have no hover) instead of hidden.
`pressScale`	`boolean`	`false`	Scale the beam down while pressed, to track a child `Button`'s own active-press scale.
`className`	`string`	-	Extra classes, merged via `tailwind-merge`. Set the size and radius here - the beam traces the wrapper.
`style`	`CSSProperties`	-	Inline styles on the wrapper.

BorderBeam renders a <div> and forwards every remaining native <div> attribute. The beam layer is aria-hidden and pointer-events-none.

Accessibility

The beam layer is aria-hidden and pointer-events-none, so it's skipped by assistive tech and never intercepts clicks.
Content is wrapped, not replaced - your children stay in the normal flow and fully accessible.
The motion honors prefers-reduced-motion: a looping beam has no static resting state to fall back to, so the layer is hidden entirely for reduced-motion users rather than parked at one corner. Never make the beam the only signal for a state (loading, recording); pair it with text, a spinner, or a status message.
The beam is purely decorative - keep your content's own border and text contrast intact so nothing depends on it.

Actions & Inputs

Data Display

Decoration & Effects

Layout

Menus

Navigation

Overlays

Status & Feedback