Getting Started

Installation

bun add chunks-ui motion

Peer dependencies:

Node 22 or newer. The install command does not add tailwindcss: the app is expected to have Tailwind v4 set up already.

The examples use icons from lucide-react, which you install yourself (bun add lucide-react); any icon library works.

Installing motion in any dependency field turns the animations on. The types do not need Motion. For Motion’s full types, cast in your own code: useMotion() as typeof import("motion/react") | null.

useReducedMotion() returns true when the user has asked for reduced motion (prefers-reduced-motion: reduce) and false otherwise. It follows the setting if the user changes it while the page is open. Use it to skip an animation that you start from JavaScript, or to show a static fallback:

import { Button, useReducedMotion } from "chunks-ui";
 
export function BackToTop() {
  const reduced = useReducedMotion();
 
  return (
    <Button onClick={() => window.scrollTo({ top: 0, behavior: reduced ? "instant" : "smooth" })}>
      Back to top
    </Button>
  );
}

On the server and while hydrating, the hook returns false, so the client markup matches what the server sent. For a user who asks for reduced motion, it switches to true right after hydration. A component that mounts after hydration, such as a popup that opens later, reads the real value on its first render. An animation that must be off from the first paint belongs in CSS (the motion-reduce: variant), not in the hook.

Setup

Add the theme to the CSS file that imports Tailwind (e.g. app/globals.css):

@import "tailwindcss";
@import "chunks-ui/theme.css";

Then import components as needed:

import { Button, Input, Tabs } from "chunks-ui";

The theme CSS exposes OKLCH color tokens as CSS variables and registers them with Tailwind CSS v4 through @theme. Its @source tells Tailwind to scan the package for the classes the components use — no plugin needed.

Importing the theme sets the page’s default font to Manrope through Tailwind’s preflight (--font-sans), or to the browser’s generic sans-serif when your app does not load Manrope (the font files are not included). To keep your app’s font, set the token after the import:

@import "tailwindcss";
@import "chunks-ui/theme.css";
 
@theme {
  --font-sans: "Inter", ui-sans-serif, system-ui, sans-serif;
}

Dark mode is the .dark class on <html>: with it, every component uses the dark values of the tokens. See Theme › Dark Mode.

A React Server Component imports cn, cnState and the *Variants functions from chunks-ui/utils, which has no "use client". See Utilities › Server components.

Architecture

• Headless layer: @base-ui/react v1.9+ (includes Floating UI for positioning)
• Styling: Tailwind CSS v4 + CVA + clsx + tailwind-merge
• Animation: Motion 12.8+ (optional peer dependency)
• Build: tsup (ESM + CJS + .d.ts)
• Compound pattern: Components use <X.Root>, <X.Trigger>, <X.Content> patterns
• Composition: Base UI render prop, not asChild