# Integrate `MagneticDock` from Motion Garden

You are helping me add the **MagneticDock** component to an existing project.
Everything you need is below — full source, dependencies, props and the
behavioural contract. Read it all before writing anything.

- **Component:** MagneticDock
- **Category:** Micro-interactions
- **Summary:** A dock whose items swell under the pointer and carry their neighbours part of the way with them. One shared value drives the whole row, so nothing re-renders while you sweep across it — and focusing an item writes the same value, which is why the keyboard gets the identical effect rather than a substitute for it.
- **Reference:** https://motion-garden.netlify.app/components/magnetic-dock
- **Full catalog (for you, the agent):** https://motion-garden.netlify.app/llms.txt

## Stack this source assumes

- React 19 with the Next.js App Router (never the `pages/` directory)
- TypeScript, strict
- Tailwind CSS v4, CSS-first config (utilities are inline; no `tailwind.config` needed)

If my project differs, adapt the integration — but do not rewrite the animation math to suit a different stack. Ask me first.

## Dependencies

```bash
bun add motion clsx tailwind-merge
```

## Design tokens this source uses

Some classes in the source are Motion Garden theme tokens, not stock Tailwind (`text-ink`, `bg-panel`, `font-display` and the like). Without them, parts of the component render unstyled. Add this to my global CSS, after the Tailwind import:

```css
@theme {
  --font-display: "Space Mono", ui-monospace, "SFMono-Regular", monospace;
}

@theme inline {
  --color-panel: var(--sg-panel);
  --color-raised: var(--sg-raised);
  --color-hairline: var(--sg-hairline);
  --color-ink: var(--sg-ink);
  --color-ink-dim: var(--sg-ink-dim);
  --color-accent: var(--sg-accent);
}

:root {
  --sg-panel: #ffffff;
  --sg-raised: #eceaef;
  --sg-hairline: #dde2e7;
  --sg-ink: #16191d;
  --sg-ink-dim: #545b64;
  --sg-accent: #7e22ce;
}

.dark {
  --sg-panel: #101215;
  --sg-raised: #191d21;
  --sg-hairline: #2a2f36;
  --sg-ink: #e2e6e9;
  --sg-ink-dim: #bcc2c8;
  --sg-accent: #a855f7;
}
```

The values are Motion Garden's own light and dark themes. If my project already has tokens for these roles, point the `--sg-*` variables at mine instead and tell me which you mapped. `.dark` assumes class-based dark mode — adapt the selector to how my project switches themes.

`font-display` expects Space Mono, and this CSS only names it. Load the font (with `next/font/google`, for example) or put my own display face first in the stack; until then it falls back to the system monospace.

## Files to create

2 files — all of them are required. Paths are as shipped; the component may live anywhere in my project, but keep every peer file at the exact path shown so the import aliases resolve.

### 1. `components/registry/magnetic-dock/magnetic-dock.tsx`

```tsx
"use client";

import { useRef, type CSSProperties, type ReactNode } from "react";
import {
  motion,
  useMotionValue,
  useSpring,
  useTransform,
  type MotionValue,
} from "motion/react";
import { cn } from "@/lib/utils";

export interface MagneticDockItem {
  key: string;
  label: string;
  icon?: ReactNode;
  active?: boolean;
  onSelect?: () => void;
}

export interface MagneticDockProps {
  items?: MagneticDockItem[];
  className?: string;
  magnification?: number;
  falloff?: number;
  baseSize?: number;
  gap?: number;
  stiffness?: number;
  damping?: number;
  labels?: boolean;
  orientation?: "horizontal" | "vertical";
  accent?: string;
  reducedMotion?: boolean;
}

const AWAY = Number.POSITIVE_INFINITY;

export default function MagneticDock({
  items = [],
  className,
  magnification = 2,
  falloff = 140,
  baseSize = 44,
  gap = 10,
  stiffness = 320,
  damping = 24,
  labels = true,
  orientation = "horizontal",
  accent = "#a855f7",
  reducedMotion = false,
}: MagneticDockProps) {
  const horizontal = orientation === "horizontal";
  const cursor = useMotionValue(AWAY);

  return (
    <div
      onPointerMove={(event) =>
        cursor.set(horizontal ? event.clientX : event.clientY)
      }
      onPointerLeave={() => cursor.set(AWAY)}
      onBlur={(event) => {
        if (!event.currentTarget.contains(event.relatedTarget as Node | null)) {
          cursor.set(AWAY);
        }
      }}
      className={cn(
        "flex w-fit rounded-2xl border border-hairline bg-panel/80 p-2 backdrop-blur-sm",
        horizontal ? "flex-row items-end" : "flex-col items-start",
        className,
      )}
      style={{ gap: `${gap}px`, "--dock-accent": accent } as CSSProperties}
    >
      {items.map((item) => (
        <DockItem
          key={item.key}
          item={item}
          cursor={cursor}
          horizontal={horizontal}
          magnification={magnification}
          falloff={falloff}
          baseSize={baseSize}
          stiffness={stiffness}
          damping={damping}
          labels={labels}
          accent={accent}
          reducedMotion={reducedMotion}
        />
      ))}
    </div>
  );
}

function DockItem({
  item,
  cursor,
  horizontal,
  magnification,
  falloff,
  baseSize,
  stiffness,
  damping,
  labels,
  accent,
  reducedMotion,
}: {
  item: MagneticDockItem;
  cursor: MotionValue<number>;
  horizontal: boolean;
  magnification: number;
  falloff: number;
  baseSize: number;
  stiffness: number;
  damping: number;
  labels: boolean;
  accent: string;
  reducedMotion: boolean;
}) {
  const ref = useRef<HTMLButtonElement>(null);

  const offset = useTransform(cursor, (value) => {
    const rect = ref.current?.getBoundingClientRect();
    if (!rect) return AWAY;
    return value - (horizontal ? rect.x + rect.width / 2 : rect.y + rect.height / 2);
  });

  const target = useTransform(
    offset,
    [-falloff, 0, falloff],
    [baseSize, baseSize * magnification, baseSize],
    { clamp: true },
  );
  const springed = useSpring(target, { stiffness, damping, mass: 0.1 });

  const size = reducedMotion ? target : springed;

  const glyph = useTransform(size, (value) => value * 0.46);

  const tooltip = useTransform(offset, [-falloff * 0.4, 0, falloff * 0.4], [0, 1, 0], {
    clamp: true,
  });

  return (
    <div className={cn("relative flex", horizontal ? "flex-col items-center" : "flex-row items-center")}>
      {labels ? (
        <motion.span
          style={{ opacity: tooltip }}
          aria-hidden
          className={cn(
            "pointer-events-none absolute z-10 whitespace-nowrap rounded-md border border-hairline bg-raised px-2 py-1 font-display text-[10px] tracking-[0.14em] text-ink uppercase",
            horizontal ? "bottom-full mb-2" : "left-full ml-2",
          )}
        >
          {item.label}
        </motion.span>
      ) : null}

      <motion.button
        ref={ref}
        type="button"
        onClick={item.onSelect}
        onFocus={() => {
          const rect = ref.current?.getBoundingClientRect();
          if (!rect) return;
          cursor.set(horizontal ? rect.x + rect.width / 2 : rect.y + rect.height / 2);
        }}
        aria-label={item.label}
        aria-current={item.active ? "true" : undefined}
        style={{ width: size, height: size, fontSize: glyph }}
        className={cn(
          "flex shrink-0 items-center justify-center rounded-xl border border-hairline bg-raised text-ink-dim outline-none transition-colors",
          "hover:text-ink focus-visible:text-ink",
          "focus-visible:ring-2 focus-visible:ring-(--dock-accent)",
          "[&_svg]:h-[1em] [&_svg]:w-[1em]",
        )}
      >
        {item.icon ?? (
          <span className="font-display leading-none">{item.label.charAt(0)}</span>
        )}
      </motion.button>

      <span
        aria-hidden
        className={cn(
          "absolute rounded-full",
          horizontal ? "-bottom-1.5 h-1 w-1" : "-right-1.5 h-1 w-1",
        )}
        style={{ backgroundColor: item.active ? accent : "transparent" }}
      />
    </div>
  );
}
```

### 2. `lib/utils.ts` — peer util, required

```tsx
import { clsx, type ClassValue } from "clsx";
import { twMerge } from "tailwind-merge";

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}
```


## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `magnification` | `number` | `2` | How far the item directly under the pointer grows past its resting size. Past about 2.5 the peak stops looking like the row lifting and starts looking like one icon detaching from it. Range 1–3.5 ×. |
| `falloff` | `number` | `140` | Distance at which an item stops responding at all. This is the real character knob: a narrow falloff magnifies one item and reads as a hover state, while a wide one pulls four or five along and reads as a surface being pushed from underneath. Range 40–320 px. |
| `baseSize` | `number` | `44` | Resting edge length of an item. The icon is sized in `em` off this, so any node scales with it without knowing the dock exists. Range 28–72 px. |
| `gap` | `number` | `10` | Space between items at rest. Items grow into this gap rather than pushing each other along, so a tight dock has the peak crowding its neighbours and a loose one lets each swell finish. Range 0–28 px. |
| `stiffness` | `number` | `320` | How hard an item springs toward its target size. Low values put the largest item visibly behind the pointer on a fast sweep, which breaks the illusion that you are pushing the surface yourself. Range 80–800. |
| `damping` | `number` | `24` | How fast that spring settles. Under about 15 the icons keep bobbing after the pointer has left, which is charming once and irritating thereafter. Range 6–60. |
| `labels` | `boolean` | `true` | Fade the item's label in over the magnified item. Its opacity is driven by the same distance the size is, so it arrives with the swell instead of on a separate hover timer. |
| `orientation` | `"horizontal" | "vertical"` | `"horizontal"` | Which axis the dock runs along, and therefore which pointer coordinate drives it. Items always grow away from the dock's own edge, so a vertical rail expands sideways rather than upward. |
| `accent` | `string (hex)` | `"#a855f7"` | Running indicator and focus ring. The ring is a shadow rather than an outline — an outline paints outside the border box and visibly lags the spring while the button is still resizing. |

## Usage

```tsx
import MagneticDock from "@/components/registry/magnetic-dock/magnetic-dock";

<MagneticDock
  magnification={2}
  falloff={140}
  baseSize={44}
  gap={10}
  stiffness={320}
  damping={24}
  labels={true}
  orientation="horizontal"
  accent="#a855f7"
/>
```

The import path matches the file path above; change it if you move the component. Every value shown is the documented default — pass only what you actually want to change. The snippet lists the tunable props only: if the component's props type in the source requires others (content, handlers, data), pass those too.

## Integration rules

- Keep the `"use client"` directive. This is a client component and will not render as a Server Component.
- It fills its parent. Give the wrapper an explicit height (or a definite grid area) — against a height-auto parent it collapses to nothing.
- It takes a `reducedMotion` prop and quiesces when true. Wire it to a `prefers-reduced-motion` listener rather than hardcoding `false`.
- `lib/utils.ts` is required, not optional. It exports the `cn` helper the component imports from `@/lib/utils` — keep it at that path, or rewrite every `cn` import to wherever you already keep yours. If your project is shadcn-based you almost certainly have this file already; keep yours and drop mine.

## Your task

1. Tell me where in my project this should live and why.
2. Create the files above verbatim.
3. Add the design tokens to my global CSS, or map them to tokens I already have.
4. Wire the component into the place I point you at, with sensible props for that context.
5. Flag anything in my setup that conflicts with the stack assumptions above.

Do not restyle the component or alter the animation math unless I ask.
