Installation

Flab ships on two tracks. Install it as a versioned package, or copy the component source into your project with the CLI. Both read the same token layer, so they look identical and can be mixed.

Flab targets React 19 and Tailwind CSS v4. Every component is a client component (they carry 'use client'), so they render inside Server Components but run in the browser.

Option 1 — install the package

Best when you want versioned upgrades and the smallest diff in your own repo. Components are imported from @flabbergasted-ai/react.

Add the packages

The token package is required; the charts package is optional and only needed for ECharts-backed charts.

pnpm add @flabbergasted-ai/react @flabbergasted-ai/tokens# optional, for chartspnpm add @flabbergasted-ai/charts

React and react-dom are peer dependencies. Use npm, yarn or bun if you prefer.

Import the token layer

In your global stylesheet, after Tailwind. The token import must come after Tailwind so its @theme registration can extend it. Point @source at Flab's shipped files so Tailwind generates the utilities the components use.

/* app/globals.css */@import 'tailwindcss';@import '@flabbergasted-ai/tokens/css';
@source '../node_modules/@flabbergasted-ai/react/dist';

Add the theme provider

Wrap your app in FlabThemeProvider, and run themeInitScript in the document head so the light/dark class is set before first paint (no flash). The theme-script subpath is server-safe on purpose.

// app/layout.tsx (Next.js App Router)import { FlabThemeProvider } from '@flabbergasted-ai/react';import { themeInitScript } from '@flabbergasted-ai/react/theme-script';import './globals.css';
export default function RootLayout({ children }: { children: React.ReactNode }) {  return (    <html lang="en" suppressHydrationWarning>      <head>        <script dangerouslySetInnerHTML={{ __html: themeInitScript() }} />      </head>      <body data-flab-root className="bg-canvas text-primary">        <FlabThemeProvider>{children}</FlabThemeProvider>      </body>    </html>  );}

Use a component

import { Button } from '@flabbergasted-ai/react';
export default function Page() {  return <Button variant="accent">Get started</Button>;}

Option 2 — copy components in with the CLI

Best when you want the source in your repo to read and adapt, shadcn style. The CLI copies component files in and rewrites imports to your project's aliases.

Initialise the project

This writes flab.json, ensures the token layer is imported into your stylesheet, and installs the base dependencies.

pnpm dlx @flabbergasted-ai/cli init# or: npx @flabbergasted-ai/cli init

Add components

Name one or more components. Any components they depend on are copied too.

pnpm dlx @flabbergasted-ai/cli add button badge card
# see everything availablepnpm dlx @flabbergasted-ai/cli list
# compare your local copies against the registrypnpm dlx @flabbergasted-ai/cli diff button

Configure paths (optional)

flab.json records where components land and how registry aliases map to your folders. Edit it to match your project layout.

{  "registry": "https://flab-ui.invalid/r",  "css": "app/globals.css",  "aliases": {    "ui": "@/components/flab",    "lib": "@/lib",    "hooks": "@/hooks"  }}

You still add the theme provider and init script as shown in step 3 above.