{/* everything in here, including the dialogs it opens, uses shadcn's own motion */}

… ``` For tabs, put `data-cut` on the `Tabs` root. The four components under **Animate your app** take a `cut` prop instead, for example ``, and they also respect `data-cut="none"` and `data-cut-pace` on their ancestors. ### Which setting wins [#which-setting-wins] From weakest to strongest: 1. Keyframery's default cut 2. the `` prop for that group 3. the element's own `data-cut` The order of your stylesheets doesn't matter. A named cut, such as `data-cut="fade"`, applies only to the element it's written on. Only `data-cut="none"` reaches the elements inside, including dialogs that render in a portal. See [Portals](/docs/how-it-works#portals). ## Turn it off [#turn-it-off] ```tsx ``` Every component plays shadcn's own motion. To turn it off in one area only, put `data-cut="none"` on it. ## Listen to cuts [#listen-to-cuts] Every cut fires a `keyframery:cut` event on `document`: ```ts document.addEventListener("keyframery:cut", (e) => { const { cut, component, phase, ms } = (e as CustomEvent).detail // e.g. { cut: "rack-focus", component: "dialog", phase: "enter", ms: 340 } }) ``` It's handy for analytics and in tests. See [Turning motion off in tests](/docs/guides/testing). ## Questions ### How do I slow down or speed up every animation? Set `--kf-pace` in your global CSS, for example `:root { --kf-pace: 1.2; }`. It multiplies every duration, so 2 is half speed. `` does the same. ### How do I turn the animation off for one dialog? Add `data-cut="none"` to its `DialogContent`, and that dialog keeps shadcn's own motion. On a section, `data-cut="none"` covers everything inside it, including the dialogs it opens. ### Can a dialog open from the centre instead of the button? Yes. Add `data-cut-origin="center"` to one dialog's content, or use `` for every dialog. # Loading data after a click (/docs/guides/data-loading) There are two moments to cover: the first load, when a skeleton becomes content, and every refetch after it, when values change in place. ## First load: LoadCut [#first-load-loadcut] Pass the library's loading flag straight to `loading`: ```tsx import { useQuery } from "@tanstack/react-query" import { LoadCut } from "@/components/keyframery/load-cut" import { Skeleton } from "@/components/ui/skeleton" export function Revenue() { const { data, isPending } = useQuery({ queryKey: ["revenue"], queryFn: fetchRevenue }) return ( }> {data && } ) } ``` With SWR, use `isLoading`. With `fetch` in an effect, use your own `loading` state. Make the skeleton roughly the size of the content. LoadCut morphs the height between them, but the closer they are, the calmer the change. ## Refetches: ValueCut [#refetches-valuecut] After the first load, don't show the skeleton again for a refetch. Keep the old values on screen and let them change in place: ```tsx ``` ## Changing a filter [#changing-a-filter] When a filter changes and the old content no longer applies (a different date range, say), set `loading` while the new data loads. If it comes back within 300 ms, the skeleton never shows. The [dashboard on the home page](/) does exactly this. # Detail pages on their own route (/docs/guides/detail-routes) [MatchCut](/docs/helpers/match-cut) works across a client-side route change, because it only needs the same `id` to leave and arrive within a second. ```tsx title="app/orders/page.tsx" import Link from "next/link" import { MatchCut } from "@/components/keyframery/match-cut" export default async function Orders() { const orders = await getOrders() return (

{o.customer}

) } ``` ```tsx title="app/orders/[id]/page.tsx" import { MatchCut } from "@/components/keyframery/match-cut" export default async function Order({ params }: { params: Promise<{ id: string }> }) { const { id } = await params const order = await getOrder(id) return ( ) } ``` `MatchCut` is a client component, and the pages around it can stay server components. ## Things to know [#things-to-know] * **Navigate on the client.** A `` or `router.push` keeps the page alive, so the match can play. A full page load starts fresh and plays nothing. * **Back works too.** Going back mounts the card again with the same `id`, so the detail shrinks into it. * **Slow routes.** If the detail page takes longer than a second to render, there's nothing left to match, and it simply appears. Add a `loading.tsx` that renders the same `MatchCut` with a skeleton inside, so the match plays at once and the content dissolves in. # Live data (/docs/guides/live-data) Live data changes without anyone pressing anything, so the cuts that need a press step aside on their own. ## Lists [#lists] Wrap the list in [ListCut](/docs/helpers/list-cut) and key items by their server id: ```tsx {events.map((e) => ( {e.title} ))} ``` * Items that arrive from the server rise in, because nobody pressed anything in the last 800 ms. * Items you add yourself fly from the button you pressed, even if the server echoes them back later, as long as the id is stable. * Reorders from the server glide. Don't give an optimistic item a temporary id that changes when the server answers. ListCut would see one item removed and another added. Generate the id on the client and send it to the server. ## Numbers [#numbers] Use [ValueCut](/docs/helpers/value-cut) for counters that tick. Add `announce` only for values someone is waiting on, like an order status. A ticking counter read aloud every second is noise. ## Toasts [#toasts] A toast fired from a websocket message has no press, so it plays the library's own entrance instead of flying from a button. # Performance (/docs/guides/performance) ## What runs [#what-runs] * **One** `MutationObserver` that watches for shadcn parts appearing and changing state * **Two** listeners in the capture phase, `pointerdown` and `keydown`, that remember the last press * Animations of `transform`, `opacity` and `filter` only, which the browser runs off the main thread where it can * Ghosts, the copies of leaving elements, which are removed as soon as their animation ends or is cancelled Nothing runs while nothing changes. ## Size [#size] The layer is about 7 KB gzipped once your bundler minifies it: `cuts.tsx`, its stylesheet and the engine. Each helper adds about 1.5–2.5 KB. ## Lists [#lists] ListCut measures its items once per render, in a layout effect. Only items in or near the viewport animate, so a list of thousands stays fast. Key items by a stable id, and avoid re-rendering the whole list on every keystroke elsewhere on the page. ## Slow devices [#slow-devices] Blur is the most expensive part of a rack focus. If you target low-end phones, turn it off: ```css :root { --kf-blur: 0px; } ``` # Turning motion off in tests (/docs/guides/testing) ## Turn Keyframery off [#turn-keyframery-off] The simplest way is `enabled={false}` while testing: ```tsx title="app/layout.tsx" ``` Then every component plays shadcn's own motion, exactly as before you added Keyframery. ## Or test with reduced motion [#or-test-with-reduced-motion] Playwright can ask for reduced motion, and then every cut is a fade of about 150 ms: ```ts title="playwright.config.ts" export default defineConfig({ use: { reducedMotion: "reduce" }, }) ``` Wait for the state you expect, such as a dialog being visible, never for a fixed time. ## Assert that a cut played [#assert-that-a-cut-played] Listen to `keyframery:cut` in the page: ```ts await page.addInitScript(() => { window.__cuts = [] document.addEventListener("keyframery:cut", (e) => window.__cuts.push(e.detail)) }) await page.getByRole("button", { name: "Edit profile" }).click() await expect.poll(() => page.evaluate(() => window.__cuts.map((c) => c.cut))).toContain("rack-focus") ``` ## Unit tests [#unit-tests] In jsdom or happy-dom, there are no real animations. Keyframery's parts catch the error and step aside, so components render and behave as stock shadcn. You don't need to mock anything. # List animations (/docs/helpers/list-cut) In a stock list, a new item appears from nowhere, a deleted one vanishes and everything below jumps up, and a reorder teleports every row. `ListCut` gives each of those changes a motion you can follow. ## Install [#install] ```bash npx shadcn add @keyframery/list-cut ``` If your project doesn't know `@keyframery` yet, do the [Quick start](/docs/installation) first. ## Use [#use] Replace your list and its items with `ListCut` and `ListCut.Item`, and give each item the same `id` you use as its `key`: ```tsx import { ListCut } from "@/components/keyframery/list-cut" {messages.map((m) => ( {m.text} ))} ``` It works with any data source, because it only compares ids between renders. For a table, use `ListCut as="tbody"` with `ListCut.Item as="tr"`. ## You should see [#you-should-see] * **Add an item** with a button: it flies out of that button into its place. * **Add an item** with no button involved, for example from the server: it rises in. * **Remove an item:** it folds away, and the items below slide up a moment later. * **Reorder:** every item glides to its new place. ## Options [#options] | Prop | Type | Default | Description | | --- | --- | --- | --- | | `as` | `React.ElementType` | `"div"` | The list element. | | `pace` | `number` | | Duration multiplier for this list. | | `cut` | `"none"` | | none renders changes without motion. | `ListCut.Item`: | Prop | Type | Default | Description | | --- | --- | --- | --- | | `id` | `string \| number` | required | The item's stable id. | | `as` | `React.ElementType` | `"div"` | The item element. | Both pass any other props, such as `className` or `aria-label`, to their element. ## Good to know [#good-to-know] * The first render never animates. * Only items in or near the viewport animate, so long lists stay fast. * Timing: an added item flies in over 480 ms; a removed one folds away and the items below follow 60 ms later; a moved one glides over 320 ms. * A removed table row folds inside a one-row table that keeps your column widths. In film, a new item flying from the button is a **cut on action**, and a removed item leaving before the rest move up is an **L-cut**. ## Questions ### How do I animate adding and removing items in a React list? Wrap the list in `ListCut` and each item in `ListCut.Item` with the same `id` you use as its `key`. Added items fly in from the button that added them, removed ones fold away, and moved ones glide. ### Does ListCut work with tables? Yes. Use `ListCut as="tbody"` with `ListCut.Item as="tr"`. A removed row folds inside a one-row table that keeps your column widths. ### Does it work with data from the server? Yes. ListCut only compares ids between renders, so any data source works. Items that arrive while nothing was pressed rise in. # Skeleton to content transitions (/docs/helpers/load-cut) A stock skeleton blinks on for a moment even when the data is fast, then snaps to content of a different height, and the page jumps. `LoadCut` fixes both. ## Install [#install] ```bash npx shadcn add @keyframery/load-cut ``` If your project doesn't know `@keyframery` yet, do the [Quick start](/docs/installation) first. ## Use [#use] Wrap the content, and pass your loading flag and skeleton: ```tsx import { LoadCut } from "@/components/keyframery/load-cut" import { Skeleton } from "@/components/ui/skeleton" }> ``` ## You should see [#you-should-see] * **Fast data:** no skeleton at all. The content just appears, and nothing on the page jumps. * **Slow data:** the skeleton shows, then dissolves into the content while the height eases from one to the other. ## Options [#options] | Prop | Type | Default | Description | | --- | --- | --- | --- | | `loading` | `boolean` | required | true while the data is loading. | | `skeleton` | `React.ReactNode` | required | What to show while loading. | | `hold` | `number` | `--kf-hold (300)` | How long to wait before showing the skeleton, in ms. | | `minShow` | `number` | `400` | Once shown, the skeleton stays at least this long, in ms. | | `pace` | `number` | | Duration multiplier. | | `cut` | `"dissolve" \| "none"` | `"dissolve"` | none swaps the skeleton and content without the dissolve. | | `className` | `string` | | Classes for the wrapper. | ## Good to know [#good-to-know] * LoadCut waits `--kf-hold` (300 ms) before it shows the skeleton. During the wait the space is reserved but empty, so nothing jumps. * Once shown, the skeleton stays at least 400 ms, so it never flashes, then dissolves over 240 ms. * LoadCut sets `aria-busy` while loading. In film, one shot fading into the next is a **dissolve**. ## Questions ### How do I stop a skeleton from flashing when data loads fast? Wrap the content in `LoadCut`. It waits 300 ms before showing the skeleton, so fast data never shows one, and once shown the skeleton stays at least 400 ms. ### Does it prevent layout shift? Yes. While it waits, LoadCut reserves the space, and the height eases from the skeleton to the content instead of jumping. # Cards that open into a page (/docs/helpers/match-cut) When a card opens into its detail view, a stock app swaps one screen for the other. With `MatchCut`, the detail grows out of the card, and going back shrinks it into the card again. ## Install [#install] ```bash npx shadcn add @keyframery/match-cut ``` If your project doesn't know `@keyframery` yet, do the [Quick start](/docs/installation) first. ## Use [#use] Wrap the small version and the big version in `MatchCut`, with the same `id`: ```tsx import { MatchCut } from "@/components/keyframery/match-cut" // app/orders/page.tsx // app/orders/[id]/page.tsx ``` It works for a conditional render on one page and for a client-side route change. See [Detail pages on their own route](/docs/guides/detail-routes). ## You should see [#you-should-see] Click a card: the detail grows out of the card's box, while a copy of the card fades out above it. Go back: the detail shrinks into the card. ## Options [#options] | Prop | Type | Default | Description | | --- | --- | --- | --- | | `id` | `string` | required | The same id on the small and the big version. | | `as` | `React.ElementType` | `"div"` | The element to render. | | `pace` | `number` | | Duration multiplier for this match. | | `cut` | `"match-cut" \| "none"` | `"match-cut"` | none renders without matching. | | `className` | `string` | | Classes for the element. | | `style` | `React.CSSProperties` | | Styles for the element. | ## Good to know [#good-to-know] * A MatchCut that mounts within a second of another one with the same `id` leaving grows out of it. * The new element animates from the old box to its own over 420 ms: position, scale and corner radius. The copy of the old one fades out by 40% of the way. * If the old and the new element sit at the same spot on the page, nothing plays. In film, this is a **match cut**: a shape in one shot becomes the same shape in the next. ## Questions ### What is a shared element transition? It's when one element on screen becomes another, such as a card growing into its detail view. MatchCut does it in React: give the small and the big version the same `id`. ### Does it work across Next.js routes? Yes. It works for a conditional render on one page and for a client-side route change in the Next.js App Router. Going back shrinks the detail into the card again. # Animated numbers and statuses (/docs/helpers/value-cut) When a stock number changes, it just changes, and nobody notices. `ValueCut` rolls only the digits that changed, in the direction of the change, and gives the value a small punch. Text, like an order status, crossfades instead. ## Install [#install] ```bash npx shadcn add @keyframery/value-cut ``` If your project doesn't know `@keyframery` yet, do the [Quick start](/docs/installation) first. ## Use [#use] Put `ValueCut` where the value is rendered: ```tsx import { ValueCut } from "@/components/keyframery/value-cut" ``` ## You should see [#you-should-see] When the value changes, only the digits that changed roll up or down, and the whole value briefly grows and settles. A status crossfades with a small slide. ## Options [#options] | Prop | Type | Default | Description | | --- | --- | --- | --- | | `value` | `number \| string` | required | The number or text to show. | | `format` | `Intl.NumberFormatOptions` | | Intl.NumberFormat options, for numbers. | | `locale` | `string` | `the browser's` | The locale for number formatting. | | `announce` | `boolean` | `false` | Read changes out to screen readers (aria-live="polite"). | | `pace` | `number` | | Duration multiplier. | | `cut` | `"punch-in" \| "none"` | `"punch-in"` | none swaps the value instantly. | | `className` | `string` | | Classes for the wrapper span. | ## Good to know [#good-to-know] * Numbers use tabular figures, so the digits don't shift sideways. * The punch scales the value to 1.06 and back over 300 ms. Text crossfades with a 6px slide. * The first render never animates, and with reduced motion the value swaps instantly. In film, a quick push toward the subject is a **punch-in**. ## Questions ### How do I animate a number counter in React? Render the number with ``. When it changes, only the digits that changed roll, in the direction of the change. ### Can it format currency and compact numbers? Yes. Pass `Intl.NumberFormat` options, for example `format={{ style: "currency", currency: "USD" }}` with `locale="en-US"`, or `format={{ notation: "compact" }}`. ### Do screen readers hear the change? With `announce`, yes: ValueCut reads changes out politely through `aria-live`. # How it works (/docs/how-it-works) ## The six kinds of change [#the-six-kinds-of-change] Every change on a screen is one of six kinds, and Keyframery has one cut for each. See them playing on [the Cuts page](/cuts). | Kind of change | Example | Cut | Where it comes from | | ---------------------------------- | ------------------------------------ | ------------------------------------- | ----------------------------------- | | Something opens on top | a dialog, a sheet, a menu, a toast | rack focus, slide-sink, cut on action | ``, automatic | | You switch to a neighbour | a tab | J-cut, whip | ``, automatic | | A thing opens into its bigger self | a card becomes its detail page | match cut | [MatchCut](/docs/helpers/match-cut) | | A list changes | a message is sent, a row is archived | cut on action, L-cut, glide | [ListCut](/docs/helpers/list-cut) | | A value changes in place | a price, a count, a status | punch-in | [ValueCut](/docs/helpers/value-cut) | | A placeholder becomes real | a skeleton turns into a chart | dissolve | [LoadCut](/docs/helpers/load-cut) | The first two need no code, because shadcn already has the parts and Keyframery finds them. The other four are changes shadcn has no component for, so each one is a small component you wrap around your own markup. ## What the layer does [#what-the-layer-does] `` renders nothing and never changes your components' props. When it mounts: 1. It sets `data-kf` on ``, which switches on the cut stylesheet. 2. **It remembers presses.** A listener in the capture phase records the element you last pressed with a pointer or key, with its box and the time. That's where the next cut starts: a dialog grows from it, and a toast flies from it. 3. **It watches for parts.** One `MutationObserver` notices when a shadcn part appears or changes state, by its `data-slot` name and its open state (`data-open` on Base UI, `data-state` on Radix). 4. **It plays the cut.** * *CSS cuts*, for dialogs, sheets and the eleven tuned components: a stylesheet, active only under `html[data-kf]`, replaces the library's keyframes. For a rack focus, Keyframery measures the opener and the dialog and writes the distance as `--kf-dx` and `--kf-dy`, so the dialog starts out toward the button. * *JS cuts*, for tabs, toasts and the page sinking behind a sheet: these use the Web Animations API, because they animate things the library doesn't, like the tab pill, the old panel leaving and the toast's flight path. 5. **It reads your settings at play time.** Every cut reads the `--kf-*` variables from the element it animates, so a variable set on a section applies to everything in it. Then it fires a `keyframery:cut` event. It's safe with server rendering: on the server it renders nothing, and the page looks exactly like stock shadcn until it mounts. ### When something goes wrong [#when-something-goes-wrong] Each part catches its own errors and falls back to doing nothing, so the library's stock motion plays and nothing else breaks. When `` unmounts, the page is stock shadcn again. ## Exits [#exits] Base UI and Radix both keep a closing part mounted until its exit animation ends. Keyframery's exit keyframes replace the stock ones and hold the last frame, so the part stays invisible until the library removes it. Nothing is removed early, and nothing flashes back. A rack focus closes back into the element that opened it, even if that element has scrolled since. ## Portals [#portals] Dialogs, sheets, menus and toasts render in a portal at the end of ``, outside the section they were opened from. So when you open one, Keyframery copies the opener's settings onto it: 1. If the opener is inside `data-cut="none"`, the portaled part gets `data-cut="none"` too, unless it has its own `data-cut`. 2. The opener's `data-cut-pace` and its `--kf-*` values are copied over. So `

` slows down the dialogs opened from inside it, even though they render somewhere else. Named cuts are never copied, because a tabs cut means nothing to a dialog. If code opens a dialog without a press, from a timer for example, the page's own settings apply and a rack focus starts from the centre. ## Questions ### Does Keyframery work with server rendering? Yes. On the server `` renders nothing, so the page looks exactly like stock shadcn until it mounts. ### What happens if something goes wrong? Each part catches its own errors and falls back to doing nothing, so the library's stock motion plays and nothing else breaks. # Introduction (/docs) Keyframery adds animations to the shadcn/ui components you already have. Render one `` in your root layout, and your dialogs, sheets, tabs and toasts start moving from the button you pressed, and back into it. Switch the preview to **Stock** to see shadcn's own motion, then back to **Keyframery**. ## What you get [#what-you-get] * **Motion with no code changes.** Dialogs, alert dialogs, sheets, drawers, tabs, toasts, the command menu and eleven more components animate as soon as `` is in your layout. Nothing in `components/ui` changes. See [what's automatic](/docs/automatic). * **Four small components** for the changes shadcn has no component for: [cards that open into a page](/docs/helpers/match-cut), [lists](/docs/helpers/list-cut), [numbers and statuses](/docs/helpers/value-cut) and [loading states](/docs/helpers/load-cut). * **Control like colours.** Speed, easing and the cut each component uses are CSS variables and props. See [Customize](/docs/customize). Like the rest of shadcn, it's code you own: the CLI copies it into your project. Remove `` and you have stock shadcn again. ## Start here [#start-here] 1. [Quick start](/docs/installation): three steps, about two minutes. 2. Using Claude Code or another AI tool? See [Use with AI tools](/docs/ai-tools). ## Why "cuts"? [#why-cuts] In film, a cut is how one shot becomes the next. A jump cut, where something suddenly appears in a new place, is jarring, and most interface changes are jump cuts. Keyframery replaces them with the cuts an editor would choose. [See each one](/cuts). # Quick start (/docs/installation) You need a project with shadcn/ui set up, so `components.json` exists. Base UI and Radix both work. ### Register Keyframery and install it [#register-keyframery-and-install-it] ```bash npx shadcn registry add "@keyframery=https://keyframery.com/r/{name}.json" npx shadcn add @keyframery/cuts ``` The first command adds Keyframery's registry to `components.json`, once per project. The second copies `components/keyframery/cuts.tsx`, its stylesheet and a small engine in `lib/keyframery/` into your project. No npm packages are added. **You should see** `"@keyframery"` under `registries` in `components.json`, and a new `components/keyframery/` folder. ### Render `` once, at the root [#render-cuts--once-at-the-root] **Next.js** ```tsx title="app/layout.tsx" import { Cuts } from "@/components/keyframery/cuts" export default function RootLayout({ children }: { children: React.ReactNode }) { return ( {children} ) } ``` **Vite** ```tsx title="src/main.tsx" import { StrictMode } from "react" import { createRoot } from "react-dom/client" import { Cuts } from "@/components/keyframery/cuts" import App from "./App" import "./index.css" createRoot(document.getElementById("root")!).render( , ) ``` **React Router** ```tsx title="app/root.tsx" import { Outlet } from "react-router" import { Cuts } from "@/components/keyframery/cuts" export default function App() { return ( <> ) } ``` **You should see** a `data-kf` attribute on the `` element in your browser's dev tools. `` sets it while it runs. ### Open a dialog [#open-a-dialog] Open any dialog in your app. **You should see** it grow out of the button you pressed, and close back into it. Tabs now slide, sheets push the page back, and toasts fly from the button that made them. ## If the dialog still pops into the middle [#if-the-dialog-still-pops-into-the-middle] * Make sure `` is rendered once, in the root layout or entry file. * Check that your dialog's content element has `data-slot="dialog-content"`. Components added by shadcn CLI 3 and later have it; older copies don't. Run `npx shadcn add dialog` again to update yours. * If the CLI answered `Unknown registry "@keyframery"`, run the first command of step 1 again, or add the registry to `components.json` by hand: ```json title="components.json" { "registries": { "@keyframery": "https://keyframery.com/r/{name}.json" } } ``` ## Next [#next] * See [what's automatic](/docs/automatic) now that `` is running. * Animate [lists](/docs/helpers/list-cut), [numbers and statuses](/docs/helpers/value-cut), [loading states](/docs/helpers/load-cut) and [cards that open into a page](/docs/helpers/match-cut). Each one installs by name, for example `npx shadcn add @keyframery/list-cut`. * To try the layer without registering first, `npx shadcn add https://keyframery.com/r/cuts.json` installs it by URL. That works for `cuts` only, because the other components depend on it. ## Questions ### Do I need Framer Motion or another animation library? No. Keyframery adds motion with CSS and the Web Animations API. The CLI copies ``, its stylesheet and a small engine into your project, and adds no npm packages. ### Why does the CLI say Unknown registry "@keyframery"? Your project hasn't registered Keyframery yet. Run `npx shadcn registry add "@keyframery=https://keyframery.com/r/{name}.json"` once, then install again. ### Does it work with Vite and React Router? Yes. Render `` once in `src/main.tsx` for Vite or `app/root.tsx` for React Router, the same way as in a Next.js root layout.