OUI ships two distribution channels. The npm package (@opengovsg/oui) is canonical and governed. The registry channel lets you install any component as local source you fully own — useful when you need a one-off variant that can't be merged upstream.

When to use which

• Use the npm package for everything by default. You get centralized fixes, smaller upgrades, and no surprise drift.
• Use the registry channel for a specific component when you need to customize behavior or styling beyond what props expose. The trade-off: you own the local copy from that point on.

Installation

You need Tailwind CSS v4 configured.

1. Initialize with the OUI base

In a fresh project (or any project without a components.json), run:

pnpm dlx shadcn@latest init https://oui.open.gov.sg/r/oui.json

This writes a components.json configured for OUI — aliasing ui to @/components/oui and utils to @/lib/oui/cn — and installs @opengovsg/oui-theme plus the shared cn utility. Passing the URL as a positional argument bypasses shadcn's interactive base and preset prompts.

Then import the OUI base CSS in your global stylesheet:

/* globals.css */
@import "tailwindcss";
@import "@opengovsg/oui-theme/base.css";

2. Add components

pnpm dlx shadcn@latest add https://oui.open.gov.sg/r/button.json

The CLI:

• Writes the component file (and its variant slice) to your components/oui/ directory.
• Writes any shared utilities to your lib/oui/ directory.
• Installs the npm dependencies listed in the manifest.
• Recursively pulls any registry dependencies (e.g., Button pulls Spinner, Ripple, plus the shared cn, tv, variants utilities).

You can chain the two steps in one command:

pnpm dlx shadcn@latest init https://oui.open.gov.sg/r/oui.json https://oui.open.gov.sg/r/button.json

Once installed, the code is yours

The file lives in your repo. We do not push updates to it. When OUI ships a fix:

1. We update the npm package and publish a release through Changesets.
2. The @opengovsg/oui changelog records the change. Watch it for fixes that affect components you've pulled.
3. To audit your local copy vs. current upstream, run npx shadcn diff https://oui.open.gov.sg/r/<name>.json.
4. To re-pull (overwriting your local copy), run shadcn add again. The CLI will prompt before overwriting.

We do not maintain backward-compatible manifests across major OUI versions. The registry URL is always current.

A note on changelog accuracy

The changelog describes the npm package's behavior. Most fixes apply identically to the registry-installed copy, but some (e.g., changes to internal export shapes) won't matter because the transformer rewrites those away. When in doubt, shadcn diff.

Discovery

A machine-readable index of every registry item is at https://oui.open.gov.sg/r/index.json.