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 Lumi UI styles are correctly scoped and isolated from the rest of your application. See portals from Base UI for more details.

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-[cubic-bezier(0.23,1,0.32,1)] duration-150;
   &[data-starting-style],
   &[data-ending-style] {
     opacity: 0;
     scale: 0.95;
   }
 }
 
 /* Dialogs Animation */
 @utility animate-fade-up {
   @apply transition-all duration-300 ease-[cubic-bezier(0.25,1,0.5,1)];
   &[data-starting-style],
   &[data-ending-style] {
     opacity: 0;
     translate: 0 100%;
   }
 }
 
 @utility animate-fade-down {
   @apply transition-all duration-300 ease-[cubic-bezier(0.25,1,0.5,1)];
   &[data-starting-style],
   &[data-ending-style] {
     opacity: 0;
     translate: 0 -100%;
   }
 }
 
 @utility animate-slide-left {
   @apply transition-all duration-300 ease-[cubic-bezier(0.25,1,0.5,1)];
   &[data-starting-style],
   &[data-ending-style] {
     opacity: 0;
     translate: 100% 0;
   }
 }
 
 @utility animate-slide-right {
   @apply transition-all duration-300 ease-[cubic-bezier(0.25,1,0.5,1)];
   &[data-starting-style],
   &[data-ending-style] {
     opacity: 0;
     translate: -100% 0;
   }
 }
 
 @utility animate-fade-zoom {
   @apply transition-all duration-200 ease-[cubic-bezier(0.25,1,0.5,1)];
   &[data-starting-style],
   &[data-ending-style] {
     opacity: 0;
     scale: 0.94;
   }
 }
 
 @utility animate-fade {
   @apply transition-all duration-200;
   &[data-starting-style],
   &[data-ending-style] {
     opacity: 0;
   }
 }
 
 /* Active Highlight */
 @utility highlight-on-active {
   @apply data-[highlighted]:relative data-[highlighted]:z-0 data-[highlighted]:before:absolute data-[highlighted]:before:inset-x-1 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;
 }

Install All UI Components

Run the following command to install every component from Lumi UI:


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

Toast component requires extra css and setup. Please refer to Toast Installation for more details.