# Code magic move

> A code block that animates between versions of a snippet: unchanged tokens glide to their new line and column, removed tokens fade and lift out, added tokens type in behind an accent caret. Step dots, arrow keys, and a sideways drag walk a tutorial or changelog through each change.

- Type: Component (special)
- Access: Arc Pro
- Page: https://uiarc.dev/components/code-magic-move
- Markdown: https://uiarc.dev/components/code-magic-move/markdown
- Source file: `registry/components/code-magic-move/code-magic-move.tsx`
- Dependencies: motion, lucide-react
- Keywords: special, code, motion, new, code magic move, magic move, code animation, code transition, animated code, code diff, tutorial, walkthrough, changelog, typing, keynote, shiki

## When to use

- A docs page or landing section that teaches an API by building a snippet up step by step.
- A changelog or upgrade guide that shows exactly what changed between versions of a config or call.

## When not to use

- Use code-block for a single snippet someone will copy.
- Use a proper diff view for large files or code review; this is for short snippets that fit on screen.

## Installation

Code magic move is part of Arc Pro. The live preview is public; the source and install command need Pro.

### CLI with a Pro token

1. Create a token in your account and set it in the environment (or `.env.local`). Never commit it.

```bash
export ARC_PRO_TOKEN=arc_pro_...
```

2. Add the Pro registry to `components.json`:

```json
{
  "registries": {
    "@uiarc": "https://uiarc.dev/r/{name}.json",
    "@uiarc-pro": {
      "url": "https://uiarc.dev/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ARC_PRO_TOKEN}"
      }
    }
  }
}
```

3. Install:

```bash
npx shadcn@latest add @uiarc-pro/code-magic-move
```

### Manual

Signed-in Pro members can copy the source from the Manual tab on the docs page.

- Plans: https://uiarc.dev/pricing
- Create a Pro token: https://uiarc.dev/account#pro-access
- Setup guide: https://uiarc.dev/docs/ai#pro-access

## Usage

```tsx
import { CodeMagicMove } from "@/components/arc/code-magic-move/code-magic-move";

const steps = [
  { title: "Create the client", code: `const client = new Client();` },
  { title: "Add your key", code: `const client = new Client({
  apiKey: process.env.API_KEY,
});` },
  { title: "Send a request", code: `const client = new Client({
  apiKey: process.env.API_KEY,
});

await client.orders.list();` },
];

export function QuickstartSection() {
  return <CodeMagicMove steps={steps} filename="index.ts" language="ts" label="Quickstart" />;
}
```

## API reference

### CodeMagicMove

A code block that moves between versions of a snippet. Words that stay glide to their new line and column, removed words lift away, and new code types in behind a caret while the block grows or shrinks to the new line count. Lines a step introduced carry a faint band with an accent hairline, the header counts lines added and removed, and step dots, arrow keys, or a sideways drag walk a tutorial or changelog through each change.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `steps` | `{ code: string; title: string; description?: string; filename?: string }[]` | `A four step save button tutorial` | The versions of the snippet in order. title and description caption the step under the code; filename overrides the header for that step. Tabs become two spaces. |
| `language` | `string` | `"tsx"` | Used for lightweight syntax highlighting in the same colors as code-block. |
| `filename` | `string` | `"save-button.tsx"` | File name in the header when a step has none. |
| `value` | `number` | – | Index of the shown step for controlled use. Changing it moves to that step. |
| `defaultValue` | `number` | `0` | Starting step when uncontrolled. |
| `onValueChange` | `(index: number) => void` | – | Called when a move starts toward a different step, or when a drag commits to one. |
| `autoPlay` | `boolean` | `true` | Walk through the steps on its own and loop from the last back to the first. The active dot fills while a step rests. It stops once someone steps, drags, or presses pause, and holds while a mouse hovers the block. |
| `interval` | `number` | `3.2` | Seconds each step rests before autoplay moves on. |
| `speed` | `number` | `1` | Multiplies the pace of every move. At 1 a typical move takes about a second, a little longer when tokens travel across the whole file. |
| `paused` | `boolean` | `false` | Holds autoplay where it is. Manual steps still animate. |
| `accent` | `string` | – | Color of the caret, the changed line bands, and the active step. Defaults to the accent token. |
| `label` | `string` | `"Code walkthrough"` | Accessible name for the walkthrough region. |
| `className` | `string` | – | Extra class on the root. |
| `style` | `CSSProperties` | – | Inline styles on the root. |

## Accessibility

- The root is a labelled section. The code area is a focusable group named with the step position, and its full source for the current step sits in a visually hidden pre, so screen readers read real code rather than the animated layer, which is aria-hidden.
- Left and right (or up and down) arrows step through the versions, Home and End jump to the first and last. Previous, next, every step dot, and play or pause are real buttons with specific names; the current dot carries aria-current="step".
- A polite live region announces each step you choose with its title and how many lines it added and removed. Autoplay is not announced, and a pause button stops it.
- Change is never shown by color alone: the header writes the line counts, the caption names the step, and changed lines carry a hairline mark as well as a tint.
- Pointer focus draws no ring; keyboard focus shows Arc's shared focus ring. Keyboard position shows through hover fills on the buttons.

## Motion

- One rAF loop writes transform, opacity, and clip-path straight to each token, only when a value changed; React renders only when the step changes.
- Tokens are paired across versions with a longest common subsequence, then leftover words pair by distance, so a line that moved as a whole glides rather than retyping.
- Positions are written in ch and em, so the moves follow the fitted font size at any width without measuring.
- Removed words fade and lift first. Kept words glide on the shared in-out curve, a beat later on lower lines. New code types in one character at a time behind an accent caret, which fades once the step is written. The block height and line numbers follow the line count on the same curve.
- Every move is a pure function of its progress, so it is fully interruptible: dragging sideways scrubs it under the finger and commits past about a third or on a flick, otherwise it rewinds. Stepping back mid move reverses on the same timeline, and a new step mid move starts from where every token is.
- At either end the text rubber-bands and settles back on a critically damped spring.
- The loop stops off screen, in hidden tabs, and once a move lands. With reduced motion, autoplay stays off and steps change in one frame, with the changed line bands and counts still shown.

## Responsive behavior

- The root is a container. The code font fits the widest step to the available width, from 14px down to 10.5px, so lines never wrap and tokens never collide.
- Below 520px the caption takes its own row and the step controls spread across the width, with 44px tall dots.
- Dragging is horizontal only, so vertical page scrolling on touch keeps working.

## Performance

- About one span per token (under a hundred for the default snippet), each on its own compositor layer, with written values cached.
- Token pairing runs once per move on small arrays; nothing is measured per frame.

## Notes for AI

- Use it for tutorials, quickstarts, migration guides, and changelog entries where the reader should see how code changes from one version to the next.
- Keep each step a small, meaningful change and give it a short title. Lines over about 50 characters shrink the font on phones, so wrap long calls.
- Pass value and onValueChange to sync it with prose beside it, such as a list of steps that highlights as the code moves.

## Related

- [Code block](https://uiarc.dev/components/code-block/markdown): Present code with legible hierarchy and copy access.
- [Text morph](https://uiarc.dev/components/text-morph/markdown): Morph a label into its next state, letter by letter.
- [Stepper](https://uiarc.dev/components/stepper/markdown): Show where a person is in a multi-step flow and what is done.

## Also in type

- [Keycap keyboard](https://uiarc.dev/components/keycap-keyboard/markdown): Mechanical keycaps that sink and light up as you type, with the text above the board.
- [Slot text](https://uiarc.dev/components/slot-text/markdown): Text and numbers that spin into their new value on staggered slot machine reels.
- [Sand text](https://uiarc.dev/components/sand-text/markdown): A headline made of sand that pours into the letters, crumbles where the cursor digs, and heals itself.
- [Typewriter terminal](https://uiarc.dev/components/typewriter-terminal/markdown): A terminal that types a scripted CLI session with a seeded human cadence, colors the shell syntax, and streams output lines, progress bars and spinners, with a scrubber, play/pause and replay controls.

## Guidance for AI tools

Code magic move: A code block that animates between versions of a snippet: unchanged tokens glide to their new line and column, removed tokens fade and lift out, added tokens type in behind an accent caret. Step dots, arrow keys, and a sideways drag walk a tutorial or changelog through each change. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://uiarc.dev/llms.txt
