# BorderBeam

> Gradient beam that races around a container's border using a CSS offset-path animation, masked so only the border ring is painted, with configurable size, speed, anchor position, and gradient colors.

- Package: `fancy-ui-svelte` (Svelte 5 + Tailwind CSS v4)
- Category: Effects
- Tags: animation, border, gradient, beam
- Docs: https://fancy-ui.rama.app/docs/components/border-beam
- Source: https://github.com/RamaHerbin/fancy-ui/tree/main/src/lib/fancy-ui/border-beam

## Import

```svelte
<script lang="ts">
  import { BorderBeam } from 'fancy-ui-svelte';
</script>
```

Setup (once per project): `npm install fancy-ui-svelte`, then add `@import "fancy-ui-svelte/tailwind.css";` after `@import "tailwindcss";` in your main CSS file. Full guide: https://fancy-ui.rama.app/llms.txt

React: `import { BorderBeam } from 'fancy-ui-react';` (same prop names; `class` becomes `className`, snippets become `ReactNode`).

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `number` | `200` | Size of the beam in pixels |
| `duration` | `number` | `15` | Animation duration in seconds |
| `borderWidth` | `number` | `1.5` | Border width in pixels |
| `anchor` | `number` | `90` | Anchor position (0-100) |
| `colorFrom` | `string` | `"#ffaa40"` | Gradient start color |
| `colorTo` | `string` | `"#9c40ff"` | Gradient end color |
| `delay` | `number` | `0` | Animation delay in seconds |

## Examples

### Basic Usage

```svelte
<script lang="ts">
	import { BorderBeam } from "fancy-ui-svelte";
</script>

<div
	class="bg-background relative mx-auto h-40 w-full max-w-md overflow-hidden rounded-xl border p-6"
>
	<p class="text-muted-foreground text-center">Content goes here</p>
	<BorderBeam />
</div>
```

### Custom Colors

Change beam gradient colors.

```svelte
<script lang="ts">
	import { BorderBeam } from "fancy-ui-svelte";
</script>

<div class="flex flex-wrap justify-center gap-6">
	<div class="bg-background relative h-32 w-48 overflow-hidden rounded-xl border p-4">
		<p class="text-muted-foreground text-center text-xs">Orange → Purple</p>
		<BorderBeam colorFrom="#ffaa40" colorTo="#9c40ff" />
	</div>
	<div class="bg-background relative h-32 w-48 overflow-hidden rounded-xl border p-4">
		<p class="text-muted-foreground text-center text-xs">Cyan → Blue</p>
		<BorderBeam colorFrom="#00ffff" colorTo="#0066ff" />
	</div>
	<div class="bg-background relative h-32 w-48 overflow-hidden rounded-xl border p-4">
		<p class="text-muted-foreground text-center text-xs">Pink → Yellow</p>
		<BorderBeam colorFrom="#ff00ff" colorTo="#ffff00" />
	</div>
</div>
```

### Animation Speed

Control beam speed.

```svelte
<script lang="ts">
	import { BorderBeam } from "fancy-ui-svelte";
</script>

<div class="flex flex-wrap justify-center gap-6">
	<div class="bg-background relative h-32 w-48 overflow-hidden rounded-xl border p-4">
		<p class="text-muted-foreground text-center text-xs">Fast (5s)</p>
		<BorderBeam duration={5} />
	</div>
	<div class="bg-background relative h-32 w-48 overflow-hidden rounded-xl border p-4">
		<p class="text-muted-foreground text-center text-xs">Default (15s)</p>
		<BorderBeam />
	</div>
	<div class="bg-background relative h-32 w-48 overflow-hidden rounded-xl border p-4">
		<p class="text-muted-foreground text-center text-xs">Slow (30s)</p>
		<BorderBeam duration={30} />
	</div>
</div>
```

### Size & Width

Adjust beam dimensions.

```svelte
<script lang="ts">
	import { BorderBeam } from "fancy-ui-svelte";
</script>

<div class="flex flex-wrap justify-center gap-6">
	<div class="bg-background relative h-32 w-48 overflow-hidden rounded-xl border p-4">
		<p class="text-muted-foreground text-center text-xs">Small beam</p>
		<BorderBeam size={100} />
	</div>
	<div class="bg-background relative h-32 w-48 overflow-hidden rounded-xl border p-4">
		<p class="text-muted-foreground text-center text-xs">Large beam</p>
		<BorderBeam size={300} />
	</div>
	<div class="bg-background relative h-32 w-48 overflow-hidden rounded-xl border p-4">
		<p class="text-muted-foreground text-center text-xs">Thick border</p>
		<BorderBeam borderWidth={3} />
	</div>
</div>
```

### Multiple Beams

Stack multiple beams.

```svelte
<script lang="ts">
	import { BorderBeam } from "fancy-ui-svelte";
</script>

<div
	class="bg-background relative mx-auto h-40 w-full max-w-md overflow-hidden rounded-xl border p-6"
>
	<p class="text-muted-foreground text-center">Dual beam effect</p>
	<BorderBeam colorFrom="#ffaa40" colorTo="#9c40ff" />
	<BorderBeam colorFrom="#00ffff" colorTo="#0066ff" delay={7.5} />
</div>
```

### Interactive Playground

```svelte
<script lang="ts">
	import { BorderBeam, type BorderBeamProps } from "fancy-ui-svelte";
	import PropsPlayground from "$lib/components/PropsPlayground.svelte";
</script>

<PropsPlayground
	controls={[
		{ key: "size", type: "range", label: "Size", min: 50, max: 500, step: 10 },
		{ key: "duration", type: "range", label: "Duration (s)", min: 1, max: 60 },
		{ key: "borderWidth", type: "range", label: "Border Width", min: 0.5, max: 8, step: 0.5 },
		{ key: "anchor", type: "range", label: "Anchor", min: 0, max: 100 },
		{ key: "colorFrom", type: "color", label: "Color From" },
		{ key: "colorTo", type: "color", label: "Color To" },
		{ key: "delay", type: "number", label: "Delay (s)", min: 0 },
	]}
	initialValues={{
		size: 200,
		duration: 15,
		borderWidth: 1.5,
		anchor: 90,
		colorFrom: "#ffaa40",
		colorTo: "#9c40ff",
		delay: 0,
	}}
>
	{#snippet preview(values)}
		<div class="bg-background relative h-40 w-full max-w-md overflow-hidden rounded-xl border p-6">
			<p class="text-muted-foreground text-center">Preview</p>
			<BorderBeam {...values as BorderBeamProps} />
		</div>
	{/snippet}
</PropsPlayground>
```