GETTING STARTED

Introduction

Kinetic UI is a set of motion-first, accessible React components for Next.js and Tailwind CSS v4. Every component ships two ways from the same source:

npm packages

Install once, import anywhere, get fixes with npm update.

Copy with the CLI

The source lands in your repo. Edit every line — it’s yours.

Installation

Start with a Next.js app that uses Tailwind CSS v4 (npx create-next-app@latest sets this up).

Option A — Kinetic CLI (copy the code)

$ npx @kineticui/cli init

This adds the design tokens to your global CSS and creates kinetic.json. Then add components:

$ npx @kineticui/cli add button dialog dock

Files are written to components/kinetic/ and any npm dependencies are installed for you.

Option B — npm packages

$ npm i @kineticui/ui @kineticui/core @kineticui/motion @kineticui/icons

Add the tokens and tell Tailwind to scan the packages, in your global CSS:

@import "tailwindcss";
@import "@kineticui/core/styles.css";
@source "../node_modules/@kineticui";

Then import and use:

import { Button } from "@kineticui/ui";
import { SpotlightCard } from "@kineticui/motion";
import { BoltIcon } from "@kineticui/icons";

export default function Page() {
  return (
    <SpotlightCard>
      <BoltIcon />
      <Button>Get started</Button>
    </SpotlightCard>
  );
}

Using shadcn/ui already?The registry is shadcn-compatible: npx shadcn add https://your-site/r/dock.json.

Theming

Dark is the default. Wrap your app in ThemeProvider to switch modes and brand colours at runtime — every component reads from the same CSS variables.

// app/providers.tsx
"use client";
import { ThemeProvider } from "@kineticui/core/theme";
import { Toaster } from "@kineticui/ui";

export function Providers({ children }) {
  return (
    <ThemeProvider defaultMode="dark" defaultAccent="lime">
      {children}
      <Toaster />
    </ThemeProvider>
  );
}

Or override any token directly in CSS:

:root {
  --kn-accent: #ff5a1f;
  --kn-accent-foreground: #ffffff;
}

Presets: lime, blue, orange, rose, mint — try them from the colour dot in the header.

Full themes change every surface, not just the accent: midnight, sunset, paper, mono, forest and ocean. Set defaultTheme on the provider or data-theme on any element, or build your own in the theme editor.

<ThemeProvider defaultTheme="midnight">…</ThemeProvider>

// or scope a theme to one section
<section data-theme="paper">…</section>

// or generate one in code
import { createTheme, themeToCss } from "@kineticui/core";
const css = themeToCss(createTheme({ mode: "dark", background: "#0b1020", foreground: "#e6ebff", accent: "#ff5a1f" }));

Motion & accessibility

Animations use spring physics and respect prefers-reduced-motion. Interactive pieces are built on Radix primitives, so keyboard navigation, focus management and ARIA come for free.

Next: browse all components →