For the complete documentation index, see llms.txt. Markdown variants are available by appending .md to any URL or sending an Accept: text/markdown header. An agent skill is available at /.well-known/agent-skills/site-skill.md.
FrakmentFrakment

Animations

How motion works across Frakment, when to reach for it, and how to customise it.

Every animated Frakment component ships with its motion already wired. State transitions run on Motion. frakment init installs the motion package once; frakment add installs any additional npm package a specific component needs. You never install anything by hand.

Installation

Motion ships with Frakment through the CLI. Two commands are enough:

$ npx frakment@latest init
npx frakment@latest add button

init runs once per project. It verifies Tailwind v4 is configured, creates lib/animation.ts with the shared helper tokens, and installs motion along with the base dependencies. add runs once per component - it copies the component source into your project and installs whatever npm package that component animates with. No global config, no extra build step.

Default motion

These components animate out of the box - no prop required. A custom animation prop is also available on five Motion state-transition components. See Custom animation prop.

Accordion
0.45s · 0.32,0.72,0,1
Collapsible
0.45s · 0.32,0.72,0,1
Trace
200 / 30
Message Animated
0.2s · 0,0,0.58,1
Text Morph
0.3s
Credit Card (Masked)
0.45s · 0.45,0,0.55,1

Custom animation prop

Five Motion state-transition components accept an animation prop. Pass a string; the parser (parseAnimation in lib/animation.ts) converts it into a Motion transition. No need to import motion yourself.

ComponentProp location
Accordion<Accordion animation> (inherited) + <AccordionContent animation> (per-item)
Collapsible<Collapsible animation> + <CollapsibleContent animation>
Trace<TraceCollapsible animation> + <TraceCollapsibleContent animation>
Credit Card<CreditCardNumber animation> (per character; uses stagger as delay)
Text Morph<TextMorph animation> (overrides transition prop when set)
tsx
<Accordion animation="spring(300, 25)" collapsible type="single">
  <AccordionItem value="a">
    <AccordionTrigger>Shipping options</AccordionTrigger>
    <AccordionContent animation="easeOutExpo 400ms">...</AccordionContent>
  </AccordionItem>
</Accordion>

Syntax

One required primary token, then any number of modifiers. Tokens separated by spaces; parentheses and brackets preserved, so keyframes([0, 1, 0]) is one token.

Primary token (exactly one):

FormExampleMaps to
Named easingeaseInOut, easeOutExpo, easeSmoothOut, linear, backOut, anticipate{ type: "tween", ease }
Custom Beziercubic-bezier(0.4, 0, 0.2, 1){ type: "tween", ease: [x1, y1, x2, y2] }
Springspring(stiffness, damping), e.g. spring(300, 25){ type: "spring", stiffness, damping }

Modifiers (any order, repeatable):

FormExampleNotes
Duration300ms, 0.3s, 0.3Tween only. Ignored on spring.
Delaydelay(100ms)Any transition type.
Repeatrepeat(3), repeat(infinite)Any transition type.
spring(300, 25) delay(100ms) repeat(3)
easeOutExpo 400ms
cubic-bezier(0.4, 0, 0.2, 1) 300ms delay(50ms)

Disable per instance

tsx
<Accordion animation={false} collapsible type="single">...</Accordion>

false disables the animation for that instance. Omitting the prop keeps the internal default. false is not "use default" — it is "no animation".

Reduced motion

When the user has prefers-reduced-motion: reduce, all five components force { duration: 0 } regardless of the prop value.

Invalid input

If the string cannot be parsed, parseAnimation logs [motion-dsl] <reason> to the console and returns null. The component then falls back to its internal default. No crash, no broken UI.

tsx
<Accordion animation="spring(abc, def)">   // warns, falls back to default
<Accordion animation="wobbleOut 300ms">     // warns, falls back to default

Per-component behavior

  • Accordion — animates height and opacity together. Default: height uses durationSlow + easeSmoothOut, opacity uses 0.2s. Setting animation replaces both with a single shared transition.
  • Collapsible — animates height. Default: durationSlow + easeSmoothOut.
  • Trace — animates height and opacity. Default: height uses springSoft, opacity uses 0.3s + easeOutExpo. Ignored when animateHeight={false}.
  • Credit Card — animates scale, opacity, and filter: blur per character. stagger sets the delay between characters. Default transition: durationSlow + easeInOutQuad.
  • Text Morph — passes the parsed transition to its internal motion.span for flip and slide variants only. The other variants (fade, blur, scale, count, roll, shuffle, typewriter, wave) run their own animation paths (CSS, NumberFlow, or timers) and ignore animation. Priority: animation string > transition prop > internal default.

Limitations

  • No per-property transitions. One transition object applies to every animated property. To control height and opacity separately, leave animation unset and edit the source.
  • springSoft cannot be referenced by name. The token is an object, not a string. Use spring(200, 30).
  • Duration is ignored on spring and inertia. Physics transitions derive duration from their parameters.
  • steps(...) is not a stepping easing. Parser accepts it but maps to ease: "linear".

Easing curves

The named cubic-bezier tokens Frakment uses across its motion system. Click any card to copy the name, then use it in your own animated components.

Custom curve

Build your own cubic-bezier when none of the tokens above fit. X must stay between 0 and 1; Y can overshoot for bounce-like effects. Click the value to copy the cubic-bezier(...) string.

cubic-bezier(0.4, 0, 0.2, 1)

Durations

Three duration tokens paired with any easing above.

NameValue
fast0.2s
normal0.3s
slow0.45s

Exported as durationFast, durationNormal, durationSlow from @/lib/animation.

Springs

Physics-based transitions that settle naturally without a fixed duration.

NameConfig
springSoftstiffness 200, damping 30

Reach for springSoft when an element should feel physical rather than timed. Trace uses it for height; Accordion and Collapsible use a tween (durationSlow + easeSmoothOut) by default.

Motion vs CSS

Every animation in Frakment picks the smallest tool that fits. Six components animate with Motion (JS-driven, per-frame control). Seven animate with pure CSS keyframes on Radix data-state attributes. Message Animated uses Motion for a single container fade, not per-character.

Motion (motion/react) - per-frame control, springs, per-character orchestration:

  • Accordion, Collapsible — height animation with tween (durationSlow + easeSmoothOut)
  • Trace — height animation with spring (springSoft)
  • Credit Card (Masked) - per-character stagger
  • Text Morph - layout transitions per variant

CSS (tw-animate-css + Radix data-state) - zero JS at runtime, runs on the compositor thread:

  • Dialog, Sheet, Dropdown Menu, Select, Tooltip, Hover Card, Tabs

npx frakment@latest init installs Motion. Radix primitives arrive with the components that need them. The split exists so that simple enter/exit transitions stay off the JS main thread, and only the animations that genuinely need per-frame calculations ship a Motion bundle.

What init creates

Running npx frakment@latest init adds these files to your project:

components.json
globals.css
utils.ts
animation.ts
FilePurpose
components.jsonRegistry URL, import aliases, Tailwind CSS path
app/globals.cssTheme tokens injected between FRAKMENT THEME markers
lib/utils.tscn() helper - merges Tailwind classes
lib/animation.tsMotion tokens + parseAnimation() parser for the animation prop

Plus six npm packages: class-variance-authority, clsx, tailwind-merge, radix-ui, lucide-react, motion.

Two systems, one install

Frakment uses two animation engines behind the scenes. You do not choose between them - the CLI installs whatever a component declares.

  • Motion - state transitions (accordion height, collapsible expand, trace collapse, text morph flip/slide, credit card per-character mask). Backed by the motion npm package.
  • NumberFlow - numeric roll and count variants in Text Morph. Backed by @number-flow/react.

A third-party layer fills the rest: Tailwind's animate-spin for loaders, and tw-animate-css for Radix enter/exit transitions. Those ship inside Tailwind and tw-animate-css, not Frakment, and require nothing extra from you.

What installs automatically

ComponentAnimationInstalled by CLI
AccordionMotion heightmotion
CollapsibleMotion heightmotion
TraceMotion heightmotion
AttachmentShimmer utility (CSS)shimmer
Text Morph (flip, slide, fade, blur, scale)Motionmotion
Text Morph (count, roll)NumberFlow@number-flow/react, motion
Text Morph (typewriter, wave, shuffle)Timers / WAAPImotion
Message AnimatedMotionmotion
Credit Card (Masked)Motion (per-character morph)motion

Run npx frakment add <name> once and every dependency in that row is installed for you.

Shared helpers

lib/animation.ts is created by npx frakment init. Import from it when you build your own animated components so timing matches the rest of the library.

ts
import { springSoft, easeInOutQuad, easeOutExpo, easeSmoothOut, durationSlow } from "@/lib/animation";
  • springSoft - { stiffness: 200, damping: 30 }. Expand and collapse that should settle without bounce.
  • easeInOutQuad - [0.45, 0, 0.55, 1]. Default for per-character morph (Credit Card mask).
  • easeOutExpo - [0.16, 1, 0.3, 1]. Entrances that decelerate.
  • easeSmoothOut - [0.32, 0.72, 0, 1]. Default for Frakment height transitions.
  • durationFast / durationNormal / durationSlow - 0.2 / 0.3 / 0.45 seconds.
  • delayTight - 0.02 seconds. Per-character stagger delay.

Usage

Every Frakment animated component imports Motion and its tokens from @/lib/animation. Follow the same pattern when you build your own.

Enter

tsx
"use client";
 
import { motion } from "motion/react";
import { durationNormal, easeOutExpo } from "@/lib/animation";
 
export function FadeIn({ children }: { children: React.ReactNode }) {
  return (
    <motion.div
      animate={{ opacity: 1, y: 0 }}
      initial={{ opacity: 0, y: 8 }}
      transition={{ duration: durationNormal, ease: easeOutExpo }}
    >
      {children}
    </motion.div>
  );
}

Expand height

tsx
"use client";
 
import { motion } from "motion/react";
import { durationSlow, easeSmoothOut } from "@/lib/animation";
 
export function CollapsibleBody({ open, children }: { open: boolean; children: React.ReactNode }) {
  return (
    <motion.div
      animate={{ height: open ? "auto" : 0 }}
      initial={false}
      style={{ overflow: "hidden" }}
      transition={{ duration: durationSlow, ease: easeSmoothOut }}
    >
      {children}
    </motion.div>
  );
}

Spring settle

tsx
"use client";
 
import { motion } from "motion/react";
import { springSoft } from "@/lib/animation";
 
export function SpringPanel({ open, children }: { open: boolean; children: React.ReactNode }) {
  return (
    <motion.div
      animate={{ height: open ? "auto" : 0 }}
      initial={false}
      style={{ overflow: "hidden" }}
      transition={springSoft}
    >
      {children}
    </motion.div>
  );
}

Reduced motion

Always respect the user's system preference. Use useReducedMotion from Motion:

tsx
"use client";
 
import { motion, useReducedMotion } from "motion/react";
import { durationSlow, easeSmoothOut } from "@/lib/animation";
 
export function Safe({ open }: { open: boolean }) {
  const reduce = useReducedMotion();
  return (
    <motion.div
      animate={{ opacity: open ? 1 : 0 }}
      transition={reduce ? { duration: 0 } : { duration: durationSlow, ease: easeSmoothOut }}
    />
  );
}

Shimmer

Shimmer is a CSS-animated component that renders a gradient over text. Trace and Attachment use it internally when their state is running, processing, or uploading, but it works anywhere. No Motion dependency.

tsx
import { Shimmer } from "@/components/ui/shimmer";
 
<Shimmer>Loading registry...</Shimmer>

Run npx frakment add shimmer to install it on its own, or let another component pull it in.

Customising

Every animated component accepts a className and works with Motion's transition overrides where it exposes them. CreditCardNumber accepts masked, animation, duration, and stagger directly. Trace and Collapsible expose animateHeight to opt out of the built-in height animation when you provide your own. See each component page for props.