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 source-scanning is the default

Appica UI ships its components' class names as source for your Tailwind to compile, rather than defaulting to a prebuilt stylesheet you drop in. There's an opt-in prebuilt file for projects that don't run Tailwind (see Without Tailwind below), but wherever Tailwind is present the @source path is the one to reach for. That extra 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, folding the component utilities into your existing stylesheet instead of a second file, and unused component modules drop out with your bundler.
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. The prebuilt file freezes the non-token utilities (spacing, layout) 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.

Without Tailwind

Appica UI is built on Tailwind, and the source-scanning setup above is the recommended path. If your project doesn't use Tailwind, skip that step and import the prebuilt stylesheet instead. It's a single self-contained file with every component's styles and the full token system compiled in, so there's nothing to configure:

globals.css

@import '@appica/ui-react/css';

No bundler? Link it straight from a CDN:

<link rel="stylesheet" href="https://unpkg.com/@appica/ui-react/appica.css" />

Tailwind stays an optional peer dependency, so nothing installs it on your behalf when you take this path.

Your tokens still override

The prebuilt file keeps every design token as a CSS variable, so theming works exactly like Theming describes: redefine the variable after the import and every component follows, dark mode included.

:root {
  --primary: oklch(60% 0.25 150);
}

What you trade for the convenience, versus the Tailwind path:

It carries a baseline reset. The file includes Tailwind's Preflight, which normalizes element styles (margins, headings, borders) across your whole page. That's what makes it self-contained, but it is global.
Only the token variables stay live. Colors, fonts, radii, and shadows remain overridable through their CSS variables; the structural utilities (spacing, layout) are frozen at publish time, since there's no Tailwind config of yours for them to compile against.

Don't load both

If you already run Tailwind, use Configure Tailwind instead of this file. Importing the prebuilt stylesheet and scanning with @source ships the reset and utilities twice.

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

Guides

Utilities