DEV Community

EDMOND
EDMOND

Posted on Edited on

Introducing KIVU-UI - a lightweight React component library that plays nicely with Tailwind

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
Enter fullscreen mode Exit fullscreen mode

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 className always wins. Component styles live in @layer components, so any Tailwind utility you pass overrides them. No tailwind-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 */
Enter fullscreen mode Exit fullscreen mode

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";
Enter fullscreen mode Exit fullscreen mode

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>
    </>
  );
}
Enter fullscreen mode Exit fullscreen mode

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>
Enter fullscreen mode Exit fullscreen mode

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." />
Enter fullscreen mode Exit fullscreen mode

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>}
      />
    </>
  );
}
Enter fullscreen mode Exit fullscreen mode

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");
Enter fullscreen mode Exit fullscreen mode

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 />
Enter fullscreen mode Exit fullscreen mode

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;
}
Enter fullscreen mode Exit fullscreen mode

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

Top comments (0)