Anything imported from an /animated subpath (for example ui/alert/animated, ui/accordion/animated, or ui/tabs/animated) depends on framer-motion. Install it in apps that use those entry points. If you only use static imports from the main UI path (no /animated), framer-motion is optional.
npm install framer-motion
Optional: react-icons
Install react-icons when you use icon sets from that package.
npm install react-icons
Step 3
Include library paths in globals.css
Add an @source entry so Tailwind scans class names inside @zentauri-ui/zentauri-components. The path is relative to this CSS file—adjust ../ if your file lives elsewhere.
Static building blocks live under the component path (for example ui/alert, ui/accordion). Motion-enabled variants live under a matching /animated entry (for example ui/alert/animated) and require framer-motion as described in Step 2.
<divclassName="rounded-3xl border border-white/10 bg-white/5 p-5 shadow-2xl shadow-slate-950/40 backdrop-blur-xl"><Modal><ModalTriggerappearance="default"className="rounded-lg px-3 py-1.5 text-sm"> Open (sm)
</ModalTrigger><ModalContentAnimatedsize="sm"animation="scale"><ModalClose /><ModalHeader><ModalTitle>Dialog</ModalTitle><ModalDescription>Supporting description.</ModalDescription></ModalHeader><ModalBody><pclassName="text-sm text-slate-300">Modal body copy.</p></ModalBody></ModalContentAnimated></Modal></div>
Preview
Alternative
CLI — copy source into your app
Instead of importing only from node_modules, you can vendor UI (and related hooks) with the same binary as the published package: zentauri-components or zentauri-ui. After the package name, pass that binary name (for example zentauri-components init) so npx runs the CLI instead of a missing shell command. UI tokens for add come from cli/registry.json (components, plus nameAliases such as button → buttons). For hook source only, use add hook … with names from the hooks array (generated from tsup.config.ts). Run init once, then add for each UI area; the CLI copies that folder from the package tree src/ui under the path from resolvedPaths.ui (one subfolder per component), rewrites imports to your aliases, pulls hook dependencies, and creates lib/utils if missing.
Initialize components.json
Creates components.json with default path aliases. The CLI walks up from the working directory to find this file for add.
npx @zentauri-ui/zentauri-components init
Add components (registry-driven)
Pass one or more names from the registry (folder names under src/ui, or a configured alias). Test files from the package are not copied.
To vendor hook source without adding a UI folder, use add hook plus hook names from the registry (for example useWindowSize). The CLI also copies transitive sibling-hook dependencies (for example useMediaQuery when you add usePrefersReducedMotion). Hooks that import UI types still expect you to add the matching component or adjust imports.
When you rely on copied files instead of the package under node_modules, point @source at those paths (adjust relative segments to match where your globals.css lives). You can keep both package and local @source lines during a migration.
@import"tailwindcss";
/* After add, scan copied sources (paths relative to this CSS file) */@source"../src/components/ui";
@source"../src/hooks";
Overriding theme colors
Override theme colors
You can override the theme colors by using the theme.colors object but be careful as it will override all the colors in your project if you are already using tailwind default colors like slate, red, yellow, amber, green, etc. Consider using a custom color palette for your brand theme.
You can add new themes colors by adding a new theme mapper, passing the required variants like 100, 200, 500, 900 and removing the appearance prop from the component.