Skip to content
Pimolu UI
THE PIMOLU HANDBOOK
Skip to content

Getting started

Quick start

From npm installation to your first Pimolu screen.

Install Pimolu

In an existing React 18 or React 19 application, install the components and shared stylesheet package from npm. You do not need a repository checkout or a Pimolu build step.

The current release is 0.1.0-beta.1. Use @beta explicitly while evaluating the preview; APIs and visual tokens can change before the stable release.

bash
npm install @pimolu/react@beta @pimolu/web-styles@beta

# Or with pnpm
pnpm add @pimolu/react@beta @pimolu/web-styles@beta

Load Pimolu styles

Import the shared stylesheet once in your app's global CSS file. It provides the component styles, themes and visual presets. In Next.js, use app/globals.css and import that file from the root layout.

globals.csscss
@import "@pimolu/web-styles/styles.css";

Compose your first screen

Wrap your screen in PimoluProvider and import the components you use. The shared stylesheet is loaded separately from globals.css. For Next.js, keep the Provider in a client module, as shown in the Next.js guide. Pimolu owns component styles; your application owns the layout.

welcome.tsxtsx
"use client";

import {
  Button,
  Card,
  CardContent,
  CardHeader,
  CardTitle,
  PimoluProvider,
} from "@pimolu/react";

export function Welcome() {
  return (
    <PimoluProvider defaultTheme="system">
      <Card>
        <CardHeader>
          <CardTitle>Make room for your next idea.</CardTitle>
        </CardHeader>
        <CardContent>
          <Button onClick={() => window.alert("Your screen is ready.")}>
            Start building
          </Button>
        </CardContent>
      </Card>
    </PimoluProvider>
  );
}

Choose the packages you need

@pimolu/react contains components, hooks and the Provider. @pimolu/web-styles contains component CSS, theme variables and presets. Together they are the usual starting point for a React or Next.js application.

@pimolu/themes exposes palettes and visual-token data, @pimolu/design-tokens exposes primitive tokens, and @pimolu/core provides framework-independent class variant utilities. Add one directly to your dependencies if your application imports it directly; you do not need to install all five explicitly to render a Button.

Keep release versions aligned

The current npm release is 0.1.0-beta.1 for all five packages. Both latest and beta currently resolve to it; beta is still a prerelease, not a stable API guarantee. Commit your application's lockfile and update directly installed Pimolu packages together.

To reproduce this exact preview, use the version rather than a moving tag.

bash
npm install @pimolu/react@0.1.0-beta.1 @pimolu/web-styles@0.1.0-beta.1

Choose your next step

The Next.js guide provides the root layout and client Provider. Components contains four examples per family, copyable source and source-derived TypeScript APIs.