Documentation
v1.4

SUI Docs

SUI is a source-first system for React components and blocks. Browse the catalog, read the docs, and use the CLI to add components directly into your project.

Browse ComponentsCLI Reference

CLI-first

A ready command surface for the `npx sui ...` workflow.

Registry-ready

A base layer for remote distribution through a JSON registry.

Source-first

The real component file can be taken directly from the code tab.

Docs-linked

Markdown sources are automatically turned into HTML pages.

Workflow

How SUI works

SUI is not just a component gallery. The catalog, markdown docs, and CLI install flow are designed to work together in a single workflow.

1

Catalog

The registry catalog exposes components and blocks in a machine-readable index.

2

Inspect

Each package has a detail document with dependencies, files, source paths, and download URLs.

3

Install

Teams can install through CLI (`npx sui add <name>`), shadcn-style endpoints, or direct downloads.

4

Compose

Components and blocks can be composed in your own project without runtime vendor lock-in.

5

Distribute

The backend serves CLI contract routes and shadcn-compatible routes from the same source catalog.

Compatibility

Supported frameworks

Built around React + Tailwind CSS, so it adapts anywhere React is part of the stack.

Next.js

Recommended

Works with both App Router and Pages Router. The strongest path for credentials auth and source-first component workflows.

Vite + React

Supported

If Tailwind CSS and React are already configured, component files can be copied in directly with zero friction.

Remix / React Router

Supported

React-based pieces adapt well, with standard client/server boundaries for client-only components.

Astro + React

Manual

Source files can be used through a manual add workflow inside React islands.

CLI

CLI surface

StructUI packages can be installed from the sui command surface, backed by the registry API routes.

terminal
sui initInitialize SUI in a project
sui add <name>Add a component or block
sui search [query]Search the registry
sui info <name>Inspect a package entry
sui listList installed components
sui update [name]Update a component to latest
sui registryView registry details
sui doctorDiagnose configuration issues
sui versionPrint CLI version
sui helpShow usage information

Built areas

Unified registry source layer for components and blocks
CLI-friendly index and detail contracts under `/api/registry/...`
Direct source download endpoint for component and block files
shadcn-style index and item endpoints under `/api/registry.json` and `/api/r/...`
Search filtering via query params (`?q=...`) on index routes
Consistent English JSON error responses and cache headers
cli-install-examples.sh
bash
npx sui init
npx sui add button
npx sui add hero-section
npx sui info button
npx sui search pricing

Key files

package.json
src/lib/registry/distribution.ts
src/lib/registry/catalog.ts
app/api/registry/index.json/route.ts
app/api/registry/components/[slug]/route.ts
app/api/registry/blocks/[slug]/route.ts
app/api/registry/download/[type]/[slug]/route.ts
app/api/registry.json/route.ts
app/api/r/index.json/route.ts
app/api/r/[slug]/route.ts

Install

Component and block install flows

You can install with CLI, inspect detail payloads, and download raw source files directly from the API.

install-component.sh
bash
# 1) List component packages
curl -s https://structui.com/api/registry/components/index.json | jq '.items[0]'

# 2) Inspect one package detail
curl -s https://structui.com/api/registry/components/button | jq '.files[0]'

# 3) Download source file directly
curl -L https://structui.com/api/registry/download/component/button -o button.tsx

# 4) CLI install
npx sui add button
install-block.sh
bash
# 1) List block packages
curl -s https://structui.com/api/registry/blocks/index.json | jq '.items[0]'

# 2) Inspect one block package
curl -s https://structui.com/api/registry/blocks/hero-section | jq '.files[0]'

# 3) Download source file directly
curl -L https://structui.com/api/registry/download/block/hero-section -o hero-section.tsx

# 4) CLI install
npx sui add hero-section

Registry

Registry API contract

StructUI serves both a CLI contract and shadcn-compatible contract from the same package catalog.

/api/registry/index.json

Combined CLI index for all package types.

/api/registry/components/index.json

CLI index for component packages only.

/api/registry/blocks/index.json

CLI index for block packages only.

/api/registry/components/:slug

CLI detail payload for a single component package.

/api/registry/blocks/:slug

CLI detail payload for a single block package.

/api/registry/download/:type/:slug

Direct source file download endpoint.

/api/registry.json

shadcn-style registry index.

/api/r/:slug

shadcn-style registry item document.

cli-index.json
json
{
  "registryVersion": 1,
  "updatedAt": "2026-03-19T00:00:00.000Z",
  "message": "StructUI registry index generated successfully.",
  "source": "StructUI Registry API",
  "items": [
    {
      "name": "button",
      "type": "component",
      "version": "0.1.0",
      "description": "Interactive button with multiple variants and sizes.",
      "entrypoint": "components/button.json",
      "dependencies": ["@radix-ui/react-slot", "class-variance-authority"],
      "tags": ["action", "trigger", "form", "cta"]
    },
    {
      "name": "hero-section",
      "type": "block",
      "version": "0.1.0",
      "description": "Marketing hero section with CTA and headline content.",
      "entrypoint": "blocks/hero-section.json",
      "dependencies": [],
      "tags": ["hero", "marketing", "landing"]
    }
  ]
}
component-detail.json
json
{
  "name": "button",
  "type": "component",
  "version": "0.1.0",
  "title": "Button",
  "description": "Interactive button with multiple variants and sizes.",
  "dependencies": ["@radix-ui/react-slot", "class-variance-authority"],
  "registryDependencies": [],
  "tags": ["action", "trigger", "form", "cta"],
  "files": [
    {
      "path": "button.tsx",
      "sourcePath": "src/components/ui/button.tsx",
      "target": "components/ui/button.tsx",
      "content": "..."
    }
  ],
  "downloadUrl": "/api/registry/download/component/button",
  "message": "Registry item generated successfully."
}
shadcn-index.json
json
{
  "$schema": "https://ui.shadcn.com/schema/registry.json",
  "name": "structui",
  "homepage": "https://structui.com",
  "updatedAt": "2026-03-19T00:00:00.000Z",
  "items": [
    {
      "name": "button",
      "type": "registry:ui",
      "title": "Button",
      "description": "Interactive button with multiple variants and sizes.",
      "dependencies": ["@radix-ui/react-slot", "class-variance-authority"],
      "registryDependencies": []
    }
  ]
}
shadcn-item.json
json
{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "button",
  "type": "registry:ui",
  "title": "Button",
  "description": "Interactive button with multiple variants and sizes.",
  "dependencies": ["@radix-ui/react-slot", "class-variance-authority"],
  "registryDependencies": [],
  "files": [
    {
      "path": "button.tsx",
      "type": "registry:ui",
      "target": "components/ui/button.tsx",
      "content": "..."
    }
  ]
}

Status

Current state

Known limitations

Block package entries currently map selected existing component source files.
Registry endpoints are public and do not include auth- or plan-based gating.
Dependency installation is still executed by consumer tooling, not by the API itself.
Semver release channels (stable, beta, canary) are not split yet.
Package signatures and integrity hashes are not exposed yet.

Recommended next steps

1
Add dedicated source templates for every block package.
2
Expose integrity hash fields to support secure installs.
3
Add version channels and per-item changelog metadata.
4
Add optional authentication and role-based package visibility.
5
Ship CLI autofix flows for dependency sync and upgrade previews.

Component Docs

Markdown documentation

Generated from markdown files under docs/components.

Accordion

Use Accordion when content should stay compact until the user asks for more detail.

Avatar

Use Avatar to represent a user, team, workspace, or record with a recognizable visual identity.

Badge

Use Badge for lightweight status labels, metadata chips, and inline semantic markers.

Button

Use Button for primary and secondary actions across forms, dialogs, and pagelevel calls to action.

Input

Use Input for singleline text entry in forms, search bars, settings screens, and compact filters.

Select

Use Select when users should choose one value from a fixed set of known options.

Tabs

Use Tabs to switch between related content panels without forcing a route change.

Textarea

Use Textarea for freeform, multiline content such as descriptions, messages, notes, and support tickets.