Get started

Installation

Orbit UI distributes components as source through a shadcn-compatible registry. You install with the shadcn CLI; files are copied into your app, imports are rewritten to your aliases, and npm dependencies are added automatically. Every component pulls the Orbit theme (tokens + runtime) with it, so a single install of any component leaves you fully themeable.

Prerequisites

A React app with Tailwind CSS v4 and a @/*import alias (the Next.js defaults). If you haven't used shadcn in the project before, run npx shadcn@latest init once to create components.json.

Point the CLI at the Orbit registry

Add the @orbit namespace to your components.json. The registry is served by this site at /r/{name}.json:

{
  "registries": {
    "@orbit": "https://orbitui.aic.coffee/r/{name}.json"
  }
}

Install your first component

$npx shadcn@latest add @orbit/button

This copies components/ui/button.tsx, the cn() helper, and the full theme (styles/orbit.css, the OrbitTheme store, the useTheme() hook, and the no-flash ThemeScript) into your app.

Wire up the tokens

Import the Orbit stylesheet after Tailwind in your CSS entry (e.g. app/globals.css):

@import "tailwindcss";
@import "../styles/orbit.css";

Note: Orbit replaces Tailwind's default color palette — color utilities come from the token set (bg-surface, text-text-2, bg-pri…). See the token reference.

Theme your root layout

import { ThemeScript } from "@/components/ui/theme-script";

export default function RootLayout({ children }) {
  return (
    <html lang="en" data-theme="blue" data-mode="light" suppressHydrationWarning>
      <head>
        <ThemeScript />
      </head>
      <body>{children}</body>
    </html>
  );
}

For the intended typography, load Geist and Geist Mono (e.g. via next/font) and expose them as --font-geist-sans / --font-geist-mono on <html>.

Add anything else

Every component page shows its install command. Dependencies resolve automatically — installing a block pulls every component it composes:

$npx shadcn@latest add @orbit/app-shell

Components with complex behavior (Select, Combobox, menus, dialogs…) add @base-ui/react to your dependencies; simple ones add nothing beyond clsx/tailwind-merge/class-variance-authority.