Shubham Tiwari

Posted on Apr 30

I built a React component library with Tailwind v4, Framer Motion & typed hooks

#javascript #webdev #tutorial #react

3 weeks ago I started building yet another component library.

I know, I know. The world doesn't need another one. But hear me out — I had a specific itch I couldn't scratch with what was already out there, and after shipping 25+ components, a set of headless hooks, and a full typography system, I think it was worth it.

This is the story of what I built, what tradeoffs I made, and what I'd do differently. Plus some code you can steal.

Why build one at all?

I kept running into the same problem on projects: I wanted Tailwind CSS v4 (not v3), Framer Motion for animated overlays and transitions, and headless browser hooks — all from the same package with consistent TypeScript APIs.

The options I found were:

shadcn/ui — great, but copy-paste model means no central updates, and you bring your own motion
Chakra UI — runtime theming, Emotion-based, not Tailwind-native
Radix — unstyled primitives; you build everything yourself

None of them gave me the combination I wanted out of the box. So I built Zentauri UI.

What's in the box

@zentauri-ui/zentauri-components

25+ UI components — buttons, modals, accordions, toasts, sliders, inputs, tables, tabs, progress bars, and more
Multiple appearance variants — glass, solid, outline, gradient (across buttons, inputs, overlays)
Framer Motion baked in for animated entry points on modals, tabs, and drawers
React hooks — useLocalStorage, useDebouncedValue, useClickOutside, useMediaQuery, and more
Typography components — Heading, Text, Blockquote, Inline, Code, List
Tailwind v4-first with CVA-backed variant APIs
TypeScript throughout — typed props, typed variants, typed hooks

Install:

npm install @zentauri-ui/zentauri-components

Or use the optional CLI to scaffold:

npx @zentauri-ui/zentauri-components init

Show me the code

Buttons with variants

import { Button } from '@zentauri-ui/zentauri-components/ui/button'

export default function Demo() {
  return (
    <div className="flex gap-3">
      <Button variant="sky">Get started</Button>
      <Button variant="gradient-purple">Upgrade</Button>
      <Button variant="outline">Learn more</Button>
    </div>
  )
}

Each variant is CVA-backed, so refactors stay safe as the design system grows.

Animated modal

import { Modal } from '@zentauri-ui/zentauri-components/ui/modal'
import { useState } from 'react'

export default function Demo() {
  const [open, setOpen] = useState(false)

  return (
    <>
      <Button onClick={() => setOpen(true)}>Open dialog</Button>
      <Modal open={open} onClose={() => setOpen(false)}>
        <Modal.Title>Confirm action</Modal.Title>
        <Modal.Body>Are you sure you want to proceed?</Modal.Body>
        <Modal.Footer>
          <Button variant="solid" onClick={() => setOpen(false)}>Confirm</Button>
        </Modal.Footer>
      </Modal>
    </>
  )
}

The entry/exit animation is Framer Motion under the hood — no extra setup needed.

Headless hooks

import { useDebounedValue } from '@zentauri-ui/zentauri-components/hooks'

function Search() {
  const [query, setQuery] = useState('')
  const debouncedQuery = useDebouncedValue(query, 400)

  useEffect(() => {
    if (debouncedQuery) fetchResults(debouncedQuery)
  }, [debouncedQuery])

  return <input value={query} onChange={e => setQuery(e.target.value)} />
}

All hooks ship from the same package alongside the UI components — no separate install.

Path-level imports for lean bundles

You don't have to import everything at once:

// Import only what you need
import { Button } from '@zentauri-ui/zentauri-components/ui/button'
import { Modal } from '@zentauri-ui/zentauri-components/ui/modal'
import { useLocalStorage } from '@zentauri-ui/zentauri-components/hooks'

The decisions that shaped the library

1. Tailwind v4 from day one

Most libraries are built on v3. I went all-in on v4, which means native CSS cascade layers, the new @source scanning, and a cleaner config. It's a bet — but v4 is the direction the ecosystem is heading, and building on it now means the library won't need a painful migration later.

2. Framer Motion as a first-class citizen

A lot of libraries treat animation as an afterthought: "add your own transitions." I wanted animated modals, tab switches, and toasts to work immediately without wiring anything up. Framer Motion backs those animated entry points out of the box.

No tradeoffs: bundle size. If you're not using animated variants, then you don't need to import the framer motion into the bundle

3. Hooks alongside UI in one package

Most UI libraries are UI-only. You reach for a separate hooks library for useClickOutside or useMediaQuery. In Zentauri, they live together because they're used together. Having them in the same package means consistent TypeScript types and one less dependency to manage.

4. Preview site that mirrors real imports

Every component has its own preview route at zentauri-ui.vercel.app/preview/components/[name]. The code you see in the preview is the exact import path you'd use in production — no divergence between docs and reality.

What the stack looks like

Layer	Choice	Why
Styles	Tailwind CSS v4 + CVA	Variant safety, v4-forward
Animation	Framer Motion	Mature, composable, performant
Icons	react-icons	Consistent iconography in examples
Types	TypeScript throughout	Refactor confidence
Docs	Next.js App Router	Drops straight into `app/` routes
Distribution	npm + optional CLI	Familiar tooling

Compared to the alternatives

I tried to be honest about this on the landing page, and I'll be honest here too:

Use Zentauri if:

You're building with Tailwind v4
You want motion-ready components without extra configuration
You want UI + hooks from one package
You care about TypeScript variant safety

Use shadcn/ui if:

You want full ownership and copy-paste into your repo
You're on Tailwind v3 and don't want to migrate
You don't need animated overlays

Use Radix if:

You're building a design system from scratch and want unstyled primitives

What's next

The library is live and published, but it's still early. The things I'm actively working on:

Accessibility audit and ARIA notes per component
More components: DatePicker, Combobox, DataTable, Skeleton
Storybook integration for isolated component docs
Theming / design token guide for teams who want to brand it

Try it

Preview site: zentauri-ui.vercel.app
npm: @zentauri-ui/zentauri-components
GitHub: ShubhamTiwari909/zentauri-ui

I'd love feedback — especially on the component API design and anything that feels inconsistent or missing. Drop a comment below or open an issue on GitHub.

If this helped or you find the library useful, a ⭐ on GitHub goes a long way for an indie open-source project.