# Beam

> A light that travels the border at a steady speed, around any proportions and any corner.

- Category: Effects (Gradient, glow and moving light, as more layers for a frame.)
- Registry item: `beam-frame`
- Live preview with controls: https://fancyborders.vercel.app/docs/components/beam

## Installation

```bash
npx shadcn@latest add https://fancyborders.vercel.app/r/beam-frame.json
```

With the registry namespace: `npx shadcn@latest add @fancyborders/beam-frame`.

The CLI also adds what `beam-frame` is built on: `frame`, `frame-effects`.

Files it adds: `components/ui/frame.tsx`, `components/ui/frame-effects.tsx`, `components/beam-frame.tsx`, and its CSS goes into the global stylesheet after the Tailwind import.

## Usage

The code for the preview at its default settings:

```tsx
import { BeamFrame } from "@/components/beam-frame";

<BeamFrame colors={["#679dd4", "#8673d9"]} radius={14} className="p-6">
  Your content
</BeamFrame>
```

## Examples

### On a shape

Inside a shape frame the beam follows the shape's outline.

```tsx
import { FrameBeam } from "@/components/ui/frame-effects";
import { ShapeFrame } from "@/components/ui/shape-frame";

export default function BeamShape() {
  return (
    <ShapeFrame corner="notch" size={10} className="w-full max-w-xs p-6">
      <FrameBeam />
      <p className="font-mono text-sm">Around a notched frame</p>
    </ShapeFrame>
  );
}
```

### Coloured by utilities

Leave out the colours and the beam reads frame-from-* and frame-to-* from the frame.

```tsx
import { BeamFrame } from "@/components/beam-frame";

export default function BeamUtilities() {
  return (
    <BeamFrame
      count={2}
      duration={5}
      className="w-full max-w-xs p-6 frame-from-slate-400 frame-to-indigo-400"
    >
      <p className="font-mono text-sm">frame-from-slate-400</p>
    </BeamFrame>
  );
}
```

## Good to know

- BeamFrame is a preset: a Frame with a FrameBorder and a FrameBeam. Use the FrameBeam layer directly, from frame-effects, to add a beam to any frame.
- The beam follows the outline with offset-path, which needs Chromium 116, Firefox 122 or Safari 18. Without it nothing is drawn and the plain border remains.

## API reference

### BeamFrame

```tsx
import { BeamFrame } from "@/components/beam-frame";
```

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `colors` | `string[]` | – | The beam's colours: the first for its head, the last for its tail. |
| `size` | `number \| string` | `120` | Length of the beam. |
| `duration` | `number \| string` | `6` | Time for one lap of the frame. Numbers are seconds. |
| `count` | `number` | `1` | Number of beams, spaced evenly around the frame. |
| `reverse` | `boolean` | `false` | Travel anticlockwise. |

Also accepts every Frame prop and every div attribute.

### FrameBeam

```tsx
import { FrameBeam } from "@/components/ui/frame-effects";
```

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `colors` | `string[]` | – | The beam's colours: the first for its head, the last for its tail. Without them it reads frame-from-* and frame-to-*. |
| `size` | `number \| string` | `120` | Length of the beam. |
| `duration` | `number \| string` | `6` | Time for one lap of the frame. Numbers are seconds. |
| `count` | `number` | `1` | Number of beams, spaced evenly around the frame. |
| `reverse` | `boolean` | `false` | Travel anticlockwise. |
| `bloom` | `number \| false` | `0.25` | Strength of the light the beam casts on either side of the line. false leaves only the line. |
| `thickness` | `number \| string` | – | Line width, when different from the frame's. |
| `offset` | `number \| string` | `0` | Distance from the frame's edge. Positive is outward, negative inward. |
| `radius` | `number \| string` | – | Overrides the frame's radius for this layer. |

Also accepts every div attribute, such as className and style.
