Installation

Add Appica UI to your React project.

Appica UI ships as a single tree-shakeable package. Components are built on Base UI primitives and styled with Tailwind CSS v4 design tokens, so installation is two steps: add the package, then point Tailwind at it.

Prerequisites

Appica UI targets modern React and Tailwind. Make sure your project has:

Dependency	Version
React	`>= 19`
React DOM	`>= 19`
Tailwind CSS	`>= 4.0`

React 19 is a hard requirement: components use the modern ref-as-prop API and other React 19 patterns, with no forwardRef shims. If you're on React 18, upgrade before installing.

Tailwind v4 must be working first

Appica UI doesn't bundle Tailwind — it relies on your project's Tailwind to compile the component styles. Before installing, set up Tailwind v4 in your app: install tailwindcss and its build plugin (@tailwindcss/vite for Vite, @tailwindcss/postcss for PostCSS/Next.js), then confirm that @import 'tailwindcss'; in your global stylesheet generates utilities. If Tailwind isn't compiling your own classes yet, Appica UI's components will render unstyled.

Install

pnpm add @appica/ui-react

Configure Tailwind

Import the design tokens after Tailwind in your global stylesheet, and add a @source directive so Tailwind scans the compiled library for class names.

globals.css

@import 'tailwindcss';
@import '@appica/ui-react/styles.css';

@source '../node_modules/@appica/ui-react/dist';

Don't skip @source — and give it a real path

Tailwind ignores node_modules by default. Without the @source directive it won't generate the utility classes used inside the compiled components, and they'll render unstyled.

@source takes a path or glob relative to the stylesheet that contains it, not a bare package name — @source '@appica/ui-react' does not resolve and silently scans nothing. Count the ../ needed to reach node_modules from your CSS file: a stylesheet one level deep (app/globals.css, src/index.css) needs a single ../; a deeper one (src/styles/app.css) needs ../../. This matches Tailwind's own @source documentation, whose example is @source '../node_modules/@my-company/ui-lib';.

The styles.css import brings in the full token system — colors, radii, shadows, typography, and the light/dark themes. See Theming to customize it.

Why there's no prebuilt CSS to import

Appica UI ships its components' class names as source for your Tailwind to compile, rather than a prebuilt stylesheet you drop in. That extra @source line buys a lot:

One deduplicated build. The utilities the components use are generated into the same pass as your own, so shared classes (flex, rounded-lg, px-4…) are emitted once instead of shipping twice.
Only what you use. Tailwind tree-shakes across your app and the library together — utilities for components you never import are never generated.
Your tokens win. Because the classes are compiled against your Tailwind config, overrides to the design tokens in Theming — colors, radii, spacing, fonts — flow into the components automatically. A prebuilt stylesheet would freeze those values at publish time.
No version-locked CSS. There's no compiled stylesheet to drift out of sync with your Tailwind version; the components restyle themselves against whatever Tailwind v4 you're on.

Add the provider

Wrap your app in ThemeProvider to enable theming and dark mode. It injects a small inline script that applies the stored theme before first paint, so there's no flash of the wrong theme. In Next.js that's the root layout's <body>; in a Vite/CRA app, wrap your root the same way.

app/layout.tsx (Next.js)

import { ThemeProvider } from '@appica/ui-react/providers/theme-provider'

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <ThemeProvider>{children}</ThemeProvider>
      </body>
    </html>
  )
}

That's all you need to start. See Theme Provider for the full API — custom themes, forcing a theme, and flash-prevention details — and the optional DirectionProvider (RTL) and ReducedMotionProvider, which you add only when you need them.

Framework notes

Appica UI is a plain package, so the steps above are the same everywhere — unlike a file-scaffolding CLI, there's no per-framework setup to learn. The only things that move are which Tailwind build plugin you install, where your global stylesheet lives, and where the provider goes:

Framework	Tailwind plugin	Global stylesheet	Wrap the provider
Next.js (App Router)	`@tailwindcss/postcss`	`app/globals.css`	root layout `<body>`
Vite / CRA	`@tailwindcss/vite`	`src/index.css`	root component in `main.tsx`
TanStack Start	`@tailwindcss/vite`	`src/styles/app.css`	root route component
React Router 7 / Remix	`@tailwindcss/vite`	`app/app.css`	root component in `root.tsx`
Astro	`@tailwindcss/vite`	`src/styles/global.css`	see note below

Everything else — the @imports and the subpath imports — is identical regardless of framework. The one value that tracks the stylesheet is the @source path: count the ../ needed to reach node_modules from wherever your global CSS lives (see Configure Tailwind above).

Astro needs the React integration and an island

Astro renders React as islands, not a single tree, so it needs a little extra wiring. Add the @astrojs/react integration first, then mount anything interactive with a client directive (e.g. client:load) — components without one ship zero JS and won't react to theme changes. Because each island is its own React root, a ThemeProvider placed in an .astro layout won't share context across islands; either render an interactive section as one island wrapped in the provider, or apply the theme class in your .astro <head> and use the provider only inside hydrated islands.

Use a component

Import components from their subpath for the smallest bundle, and you're ready:

import { Button } from '@appica/ui-react/button'

export default function App() {
  return <Button>Get started</Button>
}

Next steps

Usage — import conventions, variants, and composition basics.
Theming — customize colors, radii, and tokens.
Dark Mode — build a theme toggle.
Components — browse the full catalog.

Getting Started

For AI Agents

Guides

Utilities