Getting started

Receive active-ui in your repository, compile its stylesheet, choose a theme, and render the first component.

@workspace/active-ui 8.0.0Developmentunreleased, in development in Foundationbaseline ce081dc3

1. Receive the package#

   active-ui arrives through the managed transfer, like every package; see 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:

   Terminal

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

   Do not edit the packages after they arrive.

2. 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:

   Terminal

   pnpm installnode tools/rps/rps-apply.mjs verify-install --from <app-folder>

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

3. 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:

   JavaScript

   // postcss.config.mjsexport {default} from '@workspace/active-ui/postcss.config';

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

   JavaScript

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

4. 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 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';

5. 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, or see the component overview.