---
id: "packages/active-ui/getting-started"
title: "Getting started"
description: "Receive active-ui in your repository, compile its stylesheet, choose a theme, and render the first component."
url: "/packages/active-ui/getting-started"
locale: "en"
revision: "2631c655d61bf1a7"
---

# Getting started

## Receive the package

`active-ui` arrives through the managed transfer, like every package; see
[Receiving packages](/receiving-packages). It depends on `@workspace/active-format`, so a bundle of
`active-ui` brings `active-format` along; both land in `packages/` as one managed set:

```bash
node tools/rps/rps-apply.mjs plan --bundle <bundle-folder> --development
node tools/rps/rps-apply.mjs apply --bundle <bundle-folder> --expect-plan <digest> --development
```

Do not edit the packages after they arrive.

## Declare, install and verify

In the `package.json` of your app:

```json
{
  "dependencies": {
    "@workspace/active-ui": "workspace:*",
    "react": "^19.2.4",
    "react-dom": "^19.2.4"
  },
  "devDependencies": {
    "@tailwindcss/postcss": "^4.3.3",
    "tailwindcss": "^4.3.3"
  }
}
```

`react`, `react-dom` and `tailwindcss` are peers: your app installs them. With Vite, use
`@tailwindcss/vite` instead of `@tailwindcss/postcss`. Then install and prove that your app
resolves the managed copies:

```bash
pnpm install
node tools/rps/rps-apply.mjs verify-install --from <app-folder>
```

The output must list `@workspace/active-ui` and `@workspace/active-format`, each as `current`.

## Compile the stylesheet

The stylesheets are Tailwind CSS 4 source, compiled by your build. Import one of them in your own
stylesheet and tell Tailwind where your code is:

```css
/* your app's stylesheet */
@import '@workspace/active-ui/styles.css';
@source '../src/**/*.{ts,tsx}'; /* the code your app renders */
```

- `styles.css` carries Tailwind, the design tokens and the base styles.
- `globals.css` is the same plus `typeset.css`, the prose styles for long text (this site uses
  it).

Neither sets a font: choose one with `@theme`, and override tokens after the import if you need to:

```css
@theme {
  --font-sans: 'Your Sans', system-ui, sans-serif;
}
```

With PostCSS, the package ships the configuration:

```js
// postcss.config.mjs
export {default} from '@workspace/active-ui/postcss.config';
```

In a Next.js app, the package is TypeScript and Tailwind source; let Next compile it:

```js
// next.config.mjs
const nextConfig = {
  transpilePackages: ['@workspace/active-ui', '@workspace/active-format'],
};
```

## Choose a theme

- **Fixed.** Render `class="dark"` on `<html>` for dark, or no class for light. No provider and no
  script.
- **Switchable.** Put `ThemeInitScript` in `<head>` and [`ThemeProvider`](/packages/active-ui/theming) around the app. Your app
  supplies the font families and, to remember the choice, the cookie names and a function that
  writes the cookie. The provider's state starts from the mode you pass as `initialMode`; read the
  stored choice on the server and pass it there, so the state matches the page after a reload.

```tsx
import {ThemeInitScript} from '@workspace/active-ui/providers/theme-init-script';
import {ThemeProvider} from '@workspace/active-ui/providers/theme-provider';
```

## The first component

Import each component from its own subpath; there is no barrel for the primitives:

```tsx
import {Button} from '@workspace/active-ui/components/primitives/button';

export function Toolbar() {
  return <Button variant="outline">Export</Button>;
}
```

Every text in it comes from you. Continue with [Button](/packages/active-ui/button), or see the
[component overview](/packages/active-ui#components).