- 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
Frakment is a set of components you install into your own project. There are two paths: use the CLI to fetch components from the registry, or copy the source files manually.
What you'll get from this guide:
- A working
components.jsonwith registry URL and import aliases - Theme CSS variables injected into your globals
lib/utils.ts,lib/motion.ts, andlib/animation.ts- Six dependencies installed:
clsx,tailwind-merge,class-variance-authority,radix-ui,lucide-react,motion - Your first component installed and rendering
Prerequisites
- Node.js 18 or newer
- React 19
- Tailwind CSS v4
- TypeScript (recommended)
Components target React 19 and Tailwind v4. For React 18, some components need forwardRef adjustments. For Tailwind v3, port the tokens from Theming manually.
Use the CLI
For all commands, flags, and registry format, see the CLI Reference.
Run init
$ bunx --bun frakment@latest init$ npx frakment@latest init$ pnpm dlx frakment@latest init$ yarn dlx frakment@latest init
Creates components.json, injects the theme block (tokens + dark mode + 9 utilities) into globals.css between /* ==== FRAKMENT THEME START/END ==== */ markers, adds lib/utils.ts, and installs 6 dependencies: class-variance-authority, clsx, tailwind-merge, radix-ui, lucide-react, motion.
Add components
$ bunx --bun frakment@latest add bubble$ npx frakment@latest add bubble$ pnpm dlx frakment@latest add bubble$ yarn dlx frakment@latest add bubble
Fetches bubble.json, resolves registry dependencies, resolves npm dependencies, writes source into components/ui/.
Import and use
import { Bubble, BubbleContent } from "@/components/ui/message";
export default function Page() {
return (
<Bubble>
<BubbleContent>Hello, Frakment.</BubbleContent>
</Bubble>
);
}The avatar component ships with five AVIF avatars, embedded as base64 in avatar.json and written to public/avatars/ on install.
What you get
After frakment init, your project will have:
components.json- registry URL, import aliases, Tailwind CSS path. Read by the CLI on everyadd.app/globals.css- theme tokens (colors, radii, spacing) injected between/* ==== FRAKMENT THEME START/END ==== */markers, plus.darkvariant and 9 utility classes.lib/utils.ts-cn()helper for merging Tailwind classes.lib/motion.ts- The per-component motion API.parseMotion()parses themotion?: stringprop into duration and easing.getTransition()turns that into a CSS transition.useReducedMotion()anduseMotionGuard()handle reduced motion and style overrides.lib/animation.ts- Motion tokens (easeInOut,easeInOutQuad,easeOutExpo,easeSmoothOut,springSoft,durationFast,durationNormal,durationSlow,delayTight) and theparseAnimation()parser. Still used by components that have not yet migrated tolib/motion.ts.
Dependencies
frakment init checks your package.json and installs any missing package:
clsxtailwind-mergeclass-variance-authorityradix-uilucide-reactmotion
These are the current runtime dependencies. radix-ui and motion are being removed incrementally as components move to Frakment-owned primitives and lib/motion.ts.
The theme block includes .dark and @custom-variant dark. As soon as your app toggles .dark on <html> (via next-themes, a custom button, or anything else), components switch automatically - no extra config needed. See Theming for the full wiring.
Existing Project
Each framework guide includes an Existing Project section with the manual setup steps for that framework.
Pick your framework and follow that path.
Choose Your Framework
Verify
Check the file exists
ls components/ui/bubble.tsxImport and render it
import { Bubble, BubbleContent } from "@/components/ui/message";
export default function Page() {
return (
<Bubble>
<BubbleContent>It works.</BubbleContent>
</Bubble>
);
}Confirm no errors
If you see Cannot find module '@/lib/utils', run npx frakment@latest init again.
Troubleshooting
Make sure your globals.css includes the theme tokens from Theming.
Partially. Some components use React 19 features. For React 18, wrap with forwardRef manually.
Yes. components.json accepts any registry URL. Point it at https://your-domain.com/r and the CLI will fetch from there.
Next
- Theming - customize tokens and dark mode
- Components - browse the catalog
- Introduction - principles and quick example