Lumi UI

Installation

Lumi UI uses the `shadcn/ui` CLI for dependency management and component installation.

Initialize Project & Install Base Theme

Run the following command in your terminal:

pnpm dlx shadcn@latest init https://lumiui.dev/r/init.json

This command initializes your project, installs the necessary dependencies, and sets up the base Lumi UI theme. It also configures a necessary CSS isolation rule (e.g., root:isolete) in your global styles.

Configure Lumi UI Registry

Update your component.json file to include the Lumi UI component registry. This allows you to fetch Lumi UI components using the npx shadcn-ui add command.

Add the following entry to your configuration:

component.json
{
  // ... other configurations
  "registries": {
    "@lumi-ui": "https://lumiui.dev/r/{name}.json"
  }
  // ...
}
Apply Root Layout Wrapper

For the scoping and isolation (configured in Step 1) to work correctly, you must wrap your main application content in a div with the class name root.

Update your main layout file (e.g., layout.tsx or similar) as follows:

layout.tsx
  <body>
    <div className="root">{children}</div>
  </body>

This step ensures all Base UI styles are correctly scoped and isolated from the rest of your application. See portals from Base UI for more details.

Add Design Tokens

Add global variables into @theme inline block:

globals.css
  /* For popups/toasts */
  --ease-spring: cubic-bezier(0.23, 1, 0.32, 1);
 
  /* For drawers/dialogs */
  --ease-smooth: cubic-bezier(0.32, 0.72, 0, 1);
Add CSS Utilities

Paste the following css utility into your global styles (e.g., globals.css or similar):

globals.css
 /* Popups Animation */
 @utility animate-popup {
   @apply origin-[var(--transform-origin)] transition-[opacity,scale,transform] ease-spring duration-150;
   &[data-starting-style],
   &[data-ending-style] {
     opacity: 0;
     scale: 0.95;
   }
 }
 
 /* Overlay Outline */
 @utility overlay-outline {
   @apply outline outline-border dark:-outline-offset-1;
 }
 
 /* Active Highlight */
 @utility highlight-on-active {
   @apply data-highlighted:relative data-highlighted:z-0 data-highlighted:before:absolute data-highlighted:before:inset-x-1.5 data-highlighted:before:inset-y-0 data-highlighted:before:z-[-1] data-highlighted:before:rounded-md data-highlighted:before:bg-accent data-highlighted:text-accent-foreground;
 }

Component-specific css for Dialog, Drawer, and Toast can be found in their respective installation guides.

Run the following command to install all available components from Lumi UI:

pnpm dlx shadcn@latest add @lumi-ui/ui