outline: deep

<Badges name="@shikijs/magic-move" />

Smoothly animated code blocks with Shiki. Useful for code-step animations in slide decks (e.g. [Slidev](https://sli.dev/guide/syntax#shiki-magic-move)) and tutorials.

`@shikijs/magic-move` is a low-level library: at its core is a framework-agnostic [diff/animation machine](https://github.com/shikijs/shiki/blob/main/packages/magic-move/src/core.ts) and [renderer](https://github.com/shikijs/shiki/blob/main/packages/magic-move/src/renderer.ts), with thin wrappers for Vue, React, Solid, Svelte, and a Web Component.

Each framework wrapper provides three components:

- **`ShikiMagicMove`** — the main component; wraps a code block and animates whenever `code` changes

- **`ShikiMagicMovePrecompiled`** — animations for compiled tokens, without the Shiki dependency at runtime

- **`ShikiMagicMoveRenderer`** — the low-level renderer component

`ShikiMagicMove` needs a Shiki highlighter instance plus the bundled stylesheet (`@shikijs/magic-move/style.css`). Whenever `code` changes, the component animates the diff.

::: code-group

```sh [npm]

npm i -D @shikijs/magic-move shiki

```sh [yarn]

yarn add -D @shikijs/magic-move shiki

```sh [pnpm]

pnpm add -D @shikijs/magic-move shiki

```sh [bun]

bun add -D @shikijs/magic-move shiki

```sh [deno]

deno add npm:@shikijs/magic-move npm:shiki

:::

Import `@shikijs/magic-move/vue` and pass the highlighter instance to the `ShikiMagicMove` component.

Import `@shikijs/magic-move/react` and pass the highlighter instance to the `ShikiMagicMove` component.

import type { HighlighterCore } from 'shiki'

import { ShikiMagicMove } from '@shikijs/magic-move/react'

import { useEffect, useState } from 'react'

import { createHighlighter } from 'shiki'

import '@shikijs/magic-move/style.css'

function App() {

const [code, setCode] = useState(`const hello = 'world'`)

const [highlighter, setHighlighter] = useState<HighlighterCore>()

useEffect(() => {

async function initializeHighlighter() {

const h = await createHighlighter({

themes: ['nord'],

langs: ['javascript', 'typescript'],

})

setHighlighter(h)

}

initializeHighlighter()

}, [])

function animate() {

setCode(`let hi = 'hello'`)

}

return (

<div>

{highlighter && (

<>

<ShikiMagicMove

lang="ts"

theme="nord"

highlighter={highlighter}

code={code}

options={{ duration: 800, stagger: 0.3, lineNumbers: true }}

/>

<button onClick={animate}>Animate</button>

</>

)}

</div>

)

}

Import `@shikijs/magic-move/solid` and pass the highlighter instance to the `ShikiMagicMove` component.

import { ShikiMagicMove } from '@shikijs/magic-move/solid'

import { bundledLanguages, bundledThemes, createHighlighter } from 'shiki'

import { createResource, createSignal, Show } from 'solid-js'

import '@shikijs/magic-move/style.css'

function App() {

const [code, setCode] = createSignal(`const hello = 'world'`)

const [highlighter] = createResource(async () => {

return await createHighlighter({

themes: Object.keys(bundledThemes),

langs: Object.keys(bundledLanguages),

})

})

function animate() {

setCode(`let hi = 'hello'`)

}

return (

<div>

<Show when={highlighter()}>

{h => (

<>

<ShikiMagicMove

lang="ts"

theme="nord"

highlighter={h()}

code={code()}

options={{ duration: 800, stagger: 0.3, lineNumbers: true }}

/>

<button onClick={animate}>Animate</button>

</>

)}

</Show>

</div>

)

}

Import `@shikijs/magic-move/svelte` and pass the highlighter instance to the `ShikiMagicMove` component.

`ShikiMagicMovePrecompiled` is a lighter variant of `ShikiMagicMove` that doesn't need Shiki at runtime — useful when you want to ship pre-tokenized step data (e.g. produced at build time) and animate between steps in the browser.

To produce the compiled tokens, run this somewhere with access to Shiki (build script, server, etc.) and serialize the result:

import { codeToKeyedTokens, createMagicMoveMachine } from '@shikijs/magic-move/core'

import { createHighlighter } from 'shiki'

const shiki = await createHighlighter({

themes: ['nord'],

langs: ['javascript', 'typescript'],

})

const codeSteps = [

`const hello = 'world'`,

`let hi = 'hello'`,

]

const machine = createMagicMoveMachine(

code => codeToKeyedTokens(shiki, code, {

lang: 'ts',

theme: 'nord',

}),

{

// options

},

)

const compiledSteps = codeSteps.map(code => machine.commit(code).current)

For a deep dive into the algorithm behind the animations, see Anthony's article [**The Magic In Shiki Magic Move**](https://antfu.me/posts/shiki-magic-move).