- Accordion
- Attachment
- Avatar
- Badge
- Breadcrumb
- Button
- Button Group
- Card
- Checkbox
- Code Block
- Collapsible
- Dialog
- Dropdown Menu
- Empty
- Field
- Hover Card
- Input
- Input Group
- Input OTP
- Item
- Label
- Marker
- Message
- Number Flow
- Pagination
- Popover
- Progress
- Radio Group
- Select
- Slider
- Sonner
- Spinner
- Switch
- Tooltip
- Separator
- Sheet
- Tabs
- Textarea
- Toggle
- Toggle Group
- Trace
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:
$ bunx --bun frakment@latest init npx frakment@latest add button$ npx frakment@latest init npx frakment@latest add button$ pnpm dlx frakment@latest init npx frakment@latest add button$ yarn dlx 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.
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.
| Component | Prop 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) |
<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):
| Form | Example | Maps to |
|---|---|---|
| Named easing | easeInOut, easeOutExpo, easeSmoothOut, linear, backOut, anticipate | { type: "tween", ease } |
| Custom Bezier | cubic-bezier(0.4, 0, 0.2, 1) | { type: "tween", ease: [x1, y1, x2, y2] } |
| Spring | spring(stiffness, damping), e.g. spring(300, 25) | { type: "spring", stiffness, damping } |
Modifiers (any order, repeatable):
| Form | Example | Notes |
|---|---|---|
| Duration | 300ms, 0.3s, 0.3 | Tween only. Ignored on spring. |
| Delay | delay(100ms) | Any transition type. |
| Repeat | repeat(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
<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.
<Accordion animation="spring(abc, def)"> // warns, falls back to default
<Accordion animation="wobbleOut 300ms"> // warns, falls back to defaultPer-component behavior
- Accordion — animates
heightandopacitytogether. Default:heightusesdurationSlow+easeSmoothOut,opacityuses0.2s. Settinganimationreplaces both with a single shared transition. - Collapsible — animates
height. Default:durationSlow+easeSmoothOut. - Trace — animates
heightandopacity. Default:heightusesspringSoft,opacityuses0.3s+easeOutExpo. Ignored whenanimateHeight={false}. - Credit Card — animates
scale,opacity, andfilter: blurper character.staggersets the delay between characters. Default transition:durationSlow+easeInOutQuad. - Text Morph — passes the parsed transition to its internal
motion.spanforflipandslidevariants only. The other variants (fade,blur,scale,count,roll,shuffle,typewriter,wave) run their own animation paths (CSS, NumberFlow, or timers) and ignoreanimation. Priority:animationstring >transitionprop > internal default.
Limitations
- No per-property transitions. One transition object applies to every animated property. To control
heightandopacityseparately, leaveanimationunset and edit the source. springSoftcannot be referenced by name. The token is an object, not a string. Usespring(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 toease: "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.
Durations
Three duration tokens paired with any easing above.
| Name | Value |
|---|---|
fast | 0.2s |
normal | 0.3s |
slow | 0.45s |
Exported as durationFast, durationNormal, durationSlow from @/lib/animation.
Springs
Physics-based transitions that settle naturally without a fixed duration.
| Name | Config |
|---|---|
springSoft | stiffness 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:
| File | Purpose |
|---|---|
components.json | Registry URL, import aliases, Tailwind CSS path |
app/globals.css | Theme tokens injected between FRAKMENT THEME markers |
lib/utils.ts | cn() helper - merges Tailwind classes |
lib/animation.ts | Motion 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
motionnpm 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
| Component | Animation | Installed by CLI |
|---|---|---|
| Accordion | Motion height | motion |
| Collapsible | Motion height | motion |
| Trace | Motion height | motion |
| Attachment | Shimmer utility (CSS) | shimmer |
| Text Morph (flip, slide, fade, blur, scale) | Motion | motion |
| Text Morph (count, roll) | NumberFlow | @number-flow/react, motion |
| Text Morph (typewriter, wave, shuffle) | Timers / WAAPI | motion |
| Message Animated | Motion | motion |
| 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.
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.45seconds.delayTight-0.02seconds. 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
"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
"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
"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:
"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.
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.
On This Page
InstallationDefault motionCustom animation propSyntaxDisable per instanceReduced motionInvalid inputPer-component behaviorLimitationsEasing curvesCustom curveDurationsSpringsMotion vs CSSWhatinit createsTwo systems, one installWhat installs automaticallyShared helpersUsageEnterExpand heightSpring settleReduced motionShimmerCustomising