SubstrateUI
Get Started

Docs / Getting Started

Getting Started

Configure the named registry, install an emitted item, and connect it to the runtime density provider.

Prerequisites

Start with a React application using Tailwind CSS v4 and an initialized shadcn/ui configuration.

  • ✓Node.js 20 or later (Node.js 22 is used in this repository)
  • ✓Tailwind CSS v4
  • ✓shadcn/ui initialized in the target project
  • ✓A components.json file at the project root
1

Initialize shadcn/ui

Skip this command if the target application already has a working shadcn/ui setup.

npx shadcn@latest init
2

Configure the @substrateui namespace

Merge this registry block into the application's root components.json:

{
  "registries": {
    "@substrateui": "https://substrateui.com/r/{name}.json"
  }
}

The current CLI needs the namespace mapping to resolve dependencies between SubstrateUI items. Do not replace it with a bare item URL.

3

Install an emitted component

npx shadcn@latest add @substrateui/button

The public registry currently emits button, input, number-scrubber, property-inspector, and tree-view. The gallery also shows components whose registry gates are not complete yet; those pages are not install endpoints.

4

Provide the runtime density

Registry components consume the density context copied into the target application. The application owns the active mode.

import { DensityProvider } from "@/lib/density";

export function Workspace({ children }: { children: React.ReactNode }) {
  return (
    <DensityProvider mode="compact">
      {children}
    </DensityProvider>
  );
}

useDensity() returns the effective mode and its numeric config. To switch density, update the state that supplies the provider's mode prop.

Read the CLI reference for local registry testing, or review the density contract before building a component.