Installation

Add UI Lab to any Tailwind v4 project in under one minute.

Choose your path

Fastest: Start from a template. Browse pre-built Starters—Next.js, Vite, Astro, Tauri, and more. Clone, install, build. Everything's configured.

Quick: Use the CLI. One command sets up UI Lab in an existing project:

npx ui-lab init

Manual: Full control. Follow the steps below for custom setups.

Interactive Installation

Step-by-step guidance for your framework:

Target framework

Next.js
Vite
Coming soon
Remix
Coming soon
Tauri
Coming soon

Installation Steps

1. Install core package

npm i ui-lab-components

2. Define your app theme

app/theme.css
:root {
  color-scheme: light;
 
  --background-500: oklch(60% 0.008 51.4);
  --background-900: oklch(96% 0.005 51.4);
  --background-950: oklch(98% 0.004 51.4);
 
  --foreground-50: oklch(16% 0.01 51.4);
  --foreground-200: oklch(31% 0.016 51.4);
  --foreground-400: oklch(55% 0.023 51.4);
 
  --accent-100: oklch(97% 0 0);
  --accent-500: oklch(32% 0 0);
  --accent-600: oklch(28% 0 0);
}
 
@theme inline {
  --color-background-500: var(--background-500);
  --color-background-900: var(--background-900);
  --color-background-950: var(--background-950);
  --color-foreground-50: var(--foreground-50);
  --color-foreground-200: var(--foreground-200);
  --color-foreground-400: var(--foreground-400);
  --color-accent-100: var(--accent-100);
  --color-accent-500: var(--accent-500);
  --color-accent-600: var(--accent-600);
}

3. Import styles in your app stylesheet

app/globals.css
@import "tailwindcss";
@import "./theme.css";
@import "ui-lab-components/styles.css";

4. Load that stylesheet from your root entry

import "./globals.css";

Verification

Start your dev server and render a test component:

import { Button } from "ui-lab-components";
 
export default function Home() {
  return <Button>UI Lab ready</Button>;
}

Tailwind v4 does not need `tailwind.config.ts` for this setup. If the component renders with the expected tokens and spacing, the install is working.

Manual Installation

Prefer the manual path if you need a minimal setup or want to wire things in yourself.

Install the package

pnpm add ui-lab-components ui-lab-theme-onyx

Important: Components are unstyled by default

UI Lab components provide semantic structure and accessibility but no visual styles out of the box. You must pair them with a theme package to render them visually.

The easiest way is to use ui-lab-theme-onyx, which provides:

  • Complete color palette (8 colors × 9 shades each)
  • Typography scale
  • Spacing and radius tokens
  • Light/dark mode support

Import styles in the right order

@import "tailwindcss";
@import "ui-lab-theme-onyx/styles.css";
@import "ui-lab-components/styles.css";

Add this to your app stylesheet (app/globals.css in Next.js, src/index.css or src/main.css in Vite).

The order matters:

  1. tailwindcss establishes the layers.
  2. ui-lab-theme-onyx/styles.css defines the design tokens (colors, typography, spacing).
  3. ui-lab-components/styles.css consumes those tokens to render components.

Using a custom theme instead

If you prefer to define your own token layer instead of using ui-lab-theme-onyx:

@import "tailwindcss";
@import "./my-theme.css";           /* Your custom token definitions */
@import "ui-lab-components/styles.css";

Your my-theme.css must define all required tokens:

  • --accent-{50,100,200,...,900}, --background-*, --foreground-*, --success-*, --danger-*, --warning-*, --info-*
  • --text-sm, --text-md, --text-lg, --text-xl
  • --radius-sm, --radius-md, --radius-lg

See ui-lab-theme-onyx for the complete token structure.

Optional: wire up theme switching

If you want light/dark mode, keep the token definitions in your own theme.css and let prefers-color-scheme handle the unstamped system case.

For Next.js, the preferred setup is:

  1. Persist explicit "light" or "dark" overrides in the ui-lab-theme cookie.
  2. Read that cookie in the server app/layout.tsx.
  3. Apply className, data-theme, and style.colorScheme on <html> with parseThemeCookie() and resolveThemeRootState() from ui-lab-components/theme-server.
import { cookies } from "next/headers";
import { parseThemeCookie, resolveThemeRootState } from "ui-lab-components/theme-server";

export default async function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  const cookieStore = await cookies();
  const theme = parseThemeCookie(cookieStore.get("ui-lab-theme")?.value);
  const rootTheme = resolveThemeRootState(theme);

  return (
    <html
      lang="en"
      className={rootTheme.className}
      data-theme={rootTheme.dataTheme}
      style={rootTheme.colorScheme ? { colorScheme: rootTheme.colorScheme } : undefined}
    >
      <body>{children}</body>
    </html>
  );
}

Leave system mode unstamped so CSS can handle first paint without an inline bootstrap script.

If you cannot use a cookie-backed server layout, ui-lab-components/theme-script is still available as a fallback. The full setup is documented in Theme Switching.

Render a component

import { Button, Card, Input } from 'ui-lab-components';

export default function Home() {
  return (
    <Card>
      <Card.Header>
        <Card.Title>Welcome</Card.Title>
      </Card.Header>
      <Card.Content>
        <Input placeholder="your@email.com" />
      </Card.Content>
      <Card.Footer>
        <Button>Get Started</Button>
      </Card.Footer>
    </Card>
  );
}

If styles don't appear, verify that you've imported a theme package (e.g., ui-lab-theme-onyx/styles.css) before ui-lab-components/styles.css in your stylesheet.

Troubleshooting

Components have no visual styles

This is expected if you haven't installed a theme. UI Lab components are unstyled by default.

Install ui-lab-theme-onyx:

pnpm add ui-lab-theme-onyx

Then import it in your stylesheet before ui-lab-components/styles.css:

@import "ui-lab-theme-onyx/styles.css";
@import "ui-lab-components/styles.css";

Styles look wrong or partially applied

Verify Tailwind v4:

npm ls tailwindcss

Should show v4.x.x. If not: npm install tailwindcss@latest

PostCSS error

Check postcss.config.mjs includes:

export default {
  plugins: { '@tailwindcss/postcss': {} },
};

Restart dev server after changes.

Styles still not applying

  1. Check your stylesheet import order — theme package must come before ui-lab-components:

    @import "tailwindcss";
@import "ui-lab-theme-onyx/styles.css";
@import "ui-lab-components/styles.css";

  2. Verify a theme is installed — Run npm ls ui-lab-theme-onyx (or check your custom theme package)

  3. Clear cache and restart: rm -rf node_modules/.cache && npm run dev

Still stuck?

Compare against the Components gallery. File issues on GitHub.

Next steps

Theming
How UI Lab's token system works — color families, shade ranges, dark mode inversion, and dynamic accent customization.
Next