Every React project I start hits the same fork in the road.
On one side are the big component libraries: polished, but they bring their own styling engine, a pile of dependencies, and a fight every time you try to make a button look like your button. On the other side is building everything from scratch with Tailwind: total control, but you end up rewriting tabs, modals, dropdowns and date pickers for the fifth time.
Kivu UI is my attempt at the middle path. It's a lightweight React component library with real, accessible components that gets out of Tailwind's way instead of competing with it.
npm install kivu-ui
What makes it different
- Zero runtime dependencies. React and React DOM are peer dependencies, and that's it.
-
No CSS-in-JS. Styles are plain CSS driven by CSS variables. Components ship as
"use client", so they drop straight into the Next.js App Router. -
Your
classNamealways wins. Component styles live in@layer components, so any Tailwind utility you pass overrides them. Notailwind-merge, no!important. -
Accessible by default. Keyboard-navigable tabs, ARIA-wired accordions and form fields, and a modal built on the native
<dialog>element. -
Themeable with CSS variables. Change
--kivu-*variables to rebrand everything. Dark mode is a class or attribute away. - React 18 and 19, with full TypeScript types.
Setup in two lines
If you use Tailwind CSS v4, import the styles after Tailwind:
/* app.css */
@import "tailwindcss";
@import "kivu-ui/styles.css";
@import "kivu-ui/tailwind.css"; /* optional */
The optional tailwind.css preset exposes Kivu UI's design tokens as Tailwind utilities, like bg-primary-600, text-fg-muted, border-line, rounded-kivu-lg and shadow-kivu-md. These follow your theme, so they stay in sync with the components, including in dark mode.
Not using Tailwind? That works too:
import "kivu-ui/styles.css";
The part I care about most: overriding styles
This is the problem that pushed me to build the library. With most component kits, customising a button means fighting specificity. With Kivu UI, you just write Tailwind:
import { Button } from "kivu-ui";
export function Actions() {
return (
<>
<Button>Default</Button>
<Button variant="soft" tone="accent">Soft accent</Button>
{/* Utilities override the component styles, no merging needed */}
<Button className="rounded-full bg-emerald-600 px-10 hover:bg-emerald-700">
Custom
</Button>
</>
);
}
It works because of CSS cascade layers. Everything in Kivu UI sits in @layer components, and Tailwind utilities come later, in the utilities layer. The cascade does the job that tailwind-merge usually does at runtime.
Need a button that's actually a link from your router? Use asChild:
<Button asChild variant="outline">
<a href="/projects/new">New project</a>
</Button>
What's in the box
The first release covers most of what a real app needs:
-
Forms:
Input,Textarea,Select,Checkbox,Switch,RadioGroup,SegmentedControl,Combobox -
Dates:
Calendar,DatePicker,DateRangePicker -
Overlays:
Modal,Drawer,Tooltip,Popover,DropdownMenu -
Navigation and layout:
AppShell,Sidebar,Topbar,Tabs,Accordion,PageHeader,Breadcrumbs,Pagination,Container -
Data display:
Table,DataTable,StatCard,Sparkline,Card,Badge,Avatar -
Feedback:
Toaster+toast,Progress,Skeleton,Spinner,EmptyState,Banner
A few examples follow.
Forms with labels, hints and errors built in
import { Input, Checkbox } from "kivu-ui";
<Input label="Hourly rate" rightSection="USD/h" />
<Input label="Email" error="Please enter a valid email" />
<Checkbox label="Send me product updates" description="About once a month." />
A modal without a portal library
Modal uses the browser's native <dialog>, so focus trapping, Escape-to-close and backdrop clicks come for free:
import { useState } from "react";
import { Button, Modal } from "kivu-ui";
export function DeleteProject() {
const [open, setOpen] = useState(false);
return (
<>
<Button tone="danger" onClick={() => setOpen(true)}>Delete project</Button>
<Modal
open={open}
onClose={() => setOpen(false)}
title="Delete this project?"
description="This can't be undone."
footer={<Button tone="danger" onClick={() => setOpen(false)}>Delete</Button>}
/>
</>
);
}
Toasts you can call from anywhere
Render <Toaster /> once, then call toast from any event handler:
import { Toaster, toast } from "kivu-ui";
// once, near the root
<Toaster />
// anywhere
toast.success("Project saved");
toast.error("Couldn't reach the server");
A sortable data table
import { DataTable, type DataTableColumn } from "kivu-ui";
type Project = { id: string; name: string; status: string; budget: number };
const columns: DataTableColumn<Project>[] = [
{ id: "name", header: "Name", accessor: "name", sortable: true },
{ id: "status", header: "Status", accessor: "status" },
{ id: "budget", header: "Budget", accessor: "budget", sortable: true, align: "end" },
];
<DataTable columns={columns} data={projects} selectable />
Theming in a few lines
Every colour, radius, shadow and font is a CSS variable. Rebrand by overriding them in your own CSS:
:root {
--kivu-primary-600: #7c3aed;
--kivu-primary: var(--kivu-primary-600);
--kivu-radius-md: 10px;
}
For dark mode, add class="dark" or data-theme="dark" to <html>, or to any wrapper if you only want part of the page dark.
Where it's headed
Kivu UI is in its 0.x series, so the API may still get refined between minor versions. Breaking changes are documented in the changelog. Releases are published straight from GitHub Actions with npm provenance, so you can verify that each version was built from the public source.
Coming up next:
- More documentation and live examples
- Gathering feedback on the component APIs before a 1.0
- Filling the gaps you tell me about
Try it
- npm: kivu-ui
- GitHub: EDMONDGIHOZO/kivu-ui
- 📖 Docs: kivu-ui.vercel.app
Top comments (0)