Skip to content
Beautiful UI

Installation

Every component is a source file the shadcn CLI copies into your project. Check the requirements, add the registries once, then install anything in one command. The theme is optional: see Theming.

Requirements and compatibility

  • React 19. Components take ref as a plain prop (no forwardRef), which React 18 doesn't support.
  • Tailwind CSS v4 only. The installed CSS uses v4's cascade layers and theme variables; Tailwind v3 projects are not supported.
  • A components.json (run npx shadcn@latest init if you don't have one) and the @/* import alias pointing at your source root. Tested with shadcn CLI 4.21.0.
  • Bundler or ESM module resolution ("moduleResolution": "bundler" in tsconfig.json, the Next.js and Vite default): some dependencies, such as @tanstack/react-table v9, are ESM-only.
  • Tested in Next.js (Base UI and Radix projects) and Vite (Radix). Other React 19 setups with Tailwind v4, such as React Router or Astro with React, should work but are untested.
  • Current browsers: Lumen uses color-mix(), :has() and cascade layers (Chrome and Edge 111+, Safari 16.4+, Firefox 121+).

A few items are written against a current major of a library. If your app is on an older major (check package.json), it has to move to this one to use them, so check that the rest of your app works with it first:

1. Add the registries

Add both registries to components.json. The Pro one only works with a token, but adding it now means you never have to touch this file again. With them, @beautiful-ui/<name> and @beautiful-ui-pro/<name> install the build that matches your style: radix-*, new-york and default get Radix, base-* gets Base UI.

components.json
{
  "registries": {
    "@beautiful-ui": "https://beautiful-ui.dev/r/{style}/{name}.json",
    "@beautiful-ui-pro": {
      "url": "https://beautiful-ui.dev/r/pro/{style}/{name}.json",
      "headers": { "Authorization": "Bearer ${BEAUTIFUL_UI_TOKEN}" }
    }
  }
}

2. Install a component

Free components also install by URL with no setup. The URL names the build, so use the one for your project's primitives (the style in components.json):

Free, Base UI project (base-* style)
npx shadcn@latest add https://beautiful-ui.dev/r/lumen-button.json https://beautiful-ui.dev/r/lumen-switch.json
Free, Radix project (radix-*, new-york or default style)
npx shadcn@latest add https://beautiful-ui.dev/r/radix-nova/lumen-button.json https://beautiful-ui.dev/r/radix-nova/lumen-switch.json
Pro: with the registries above (your style picks the build)
npx shadcn@latest add @beautiful-ui-pro/lumen-command

The bare URL always installs the Base UI build, of the item and of its dependencies, so a Radix project needs the /r/radix-nova/ URL or the registries. Pro items need your key in BEAUTIFUL_UI_TOKEN (see Pro setup).

Components land in components/ui/lumen/ as source you own, with shared code in lib/beautiful-ui/lumen/. The first one also adds Lumen's foundation (its --lumen-* tokens, keyframes and motion levels) to your global stylesheet. Each component's styles install into @layer components, so your Tailwind classes always win. Component installs don't change your shadcn tokens.

3. Use it

app/page.tsx
import { Button } from "@/components/ui/lumen/button";

export default function Page() {
  return <Button>Create workspace</Button>;
}

Sound (optional)

Lumen components mark their moments (a press, a toggle, a success) but ship no audio code: installing them is silent. To hear them, install the sound provider and mount it once. The audio engine loads only when a provider is mounted and sound is on, and nothing plays before the first click or key press.

Terminal
npx shadcn@latest add https://beautiful-ui.dev/r/glass-sound.json
app/layout.tsx
import { GlassSoundProvider, GlassSoundToggle } from "@/components/beautiful-ui/glass-sound";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {/* clicks="components": only Lumen components answer. The default, "all", adds a tap to every button and link. */}
        <GlassSoundProvider clicks="components">
          <header>
            {/* The mute control. The choice is saved in localStorage ("beautiful-ui-sound"). */}
            <GlassSoundToggle />
          </header>
          {children}
        </GlassSoundProvider>
      </body>
    </html>
  );
}

defaultMuted starts silent until the visitor turns sound on; sound={false} silences one component, and data-sound="off" silences everything inside an element. See Sound for every option.

Phones and overlays

Components are responsive; Sidebar becomes a sheet below 768px. Overlays (dialogs, menus, popovers) portal to document.body. If you render Lumen inside a scoped container or a shadow root, wrap it in LumenPortalContext so overlays keep its tokens.

Next