Quick start

npx create-yugen-ui@latest my-app --template starter
cd my-app
npm run dev

The starter comes with a remembered theme choice, toast, an @/ alias, SEO basics and a welcome page to delete when you start. Swap starter for saas (8-page SaaS app), blog (Markdown blog), dashboard, ai-chat, glass (travel journal with glass navigation), landing (product landing page), admin (back office: tables, forms, sign-in), next-starter (Next.js App Router), docs (Markdown documentation site) or store (shop: cart, multi-step checkout), or drop --template to pick in the terminal. More options on @yugen-ui/cli.

npx @yugen-ui/cli@latest init

Pick package when asked: the CLI installs yugen-ui, adds the theme line to your main CSS file (or styles.css without Tailwind v4) and prints the YugenProvider wrapper with the file to put it in. Prefer doing it by hand? Follow the three steps below.

1. 1

   Install the package

   npmnpmpnpmpnpmyarnyarnbunbun

   Copy

   npm install yugen-ui

   Radix primitives, Fluent icons and helpers are all dependencies of the package — nothing else to install.

2. 2

   Add the theme to your CSS

   Copy

   /* src/index.css (Vite) · app/globals.css (Next.js) */
   @import "tailwindcss";
   @import "yugen-ui/theme.css";

   Not using Tailwind? Skip that and import the precompiled stylesheet (preflight + tokens + every utility the components use):

   Copy

   // src/main.tsx — no Tailwind
   import "yugen-ui/styles.css";

3. 3

   Wrap your app in YugenProvider

   ViteViteNext.jsNext.js

   Copy

   // src/main.tsx
   import { StrictMode } from "react";
   import { createRoot } from "react-dom/client";
   import { Toaster, YugenProvider } from "yugen-ui";
   import App from "./App";
   import "./index.css";
   
   createRoot(document.getElementById("root")!).render(
     <StrictMode>
       <YugenProvider applyToDocument>
         <Toaster />
         <App />
       </YugenProvider>
     </StrictMode>,
   );

   applyToDocument writes the theme to <html> so portalled Dialog, Menu and Tooltip match; Put Toaster once inside the root provider to call toast() anywhere. Done — try your first component below.

npx @yugen-ui/cli@latest init --mode source

npx @yugen-ui/cli@latest add button dialog data-grid

The CLI writes the theme, cn() and YugenProvider, copies the components each one depends on, installs missing npm packages and rewrites imports to your project's alias. Details on @yugen-ui/cli. Already using the shadcn CLI? See Install with the shadcn CLI.

// The root: everything from one place. Bundlers keep only what you use.
import { Dialog, DialogSurface, DialogTrigger } from "yugen-ui";

// A subpath: only that component and what it uses.
import { Button } from "yugen-ui/Button";
import { LineChart, Sparkline } from "yugen-ui/Chart";
import { useDisclosure } from "yugen-ui/hooks";

With Vite, Rollup, webpack and Next.js a production build is the same size either way. With esbuild code splitting (splitting: true), import from subpaths: from the root, esbuild puts the parts that load on demand into the first chunk (see Performance). Subpaths also help where nothing tree-shakes the package: tests (Vitest, Jest), server rendering in Node and the dev server. A cold import { Button } from "yugen-ui/Button" in Node loads 14 modules instead of about 500. Both paths load the same files, so you can mix them.

The subpath is the folder of the component: CardHeader comes from yugen-ui/Card, DateRangePicker from yugen-ui/DatePicker. The exceptions are yugen-ui/AppShell/Sidebar, yugen-ui/YugenProvider/document, yugen-ui/messages-en and yugen-ui/messages-vi. cn and the brand color helpers are only on the root. readAppShellCookie runs in a Server Component only when imported from yugen-ui; yugenHtmlAttributes and yugenThemeScript when imported from yugen-ui or yugen-ui/YugenProvider/document.

TypeScript with moduleResolution: node (node10) does not read exports, so it finds no types for subpaths there: import from yugen-ui, or switch to bundler or nodenext.

Next.js: to keep root imports and still load only what a page uses in development and on the server, add the package to optimizePackageImports.

// next.config.ts
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  experimental: { optimizePackageImports: ["yugen-ui"] },
};

export default nextConfig;

// src/App.tsx — remember the user's theme
import * as React from "react";
import { Toaster, YugenProvider, type YugenTheme } from "yugen-ui";

const STORAGE_KEY = "yugen-ui-theme";

// The script in index.html already set data-theme before React ran — read it back to match.
const initialTheme = (): YugenTheme =>
  document.documentElement.getAttribute("data-theme") === "dark" ? "dark" : "light";

export default function App() {
  const [theme, setTheme] = React.useState(initialTheme);

  React.useEffect(() => {
    try {
      localStorage.setItem(STORAGE_KEY, theme);
    } catch {
      /* storage blocked */
    }
  }, [theme]);

  return (
    <YugenProvider applyToDocument theme={theme}>
      <Toaster />
      <AppShell onThemeChange={setTheme} />
    </YugenProvider>
  );
}

YugenProvider writes the attributes when React runs, after the browser has painted index.html, so add a script to <head> to avoid a white flash for users who picked the dark theme. For Next.js, see SSR & Next.js.

<!-- index.html — place BEFORE the app script -->
<script>
  (function () {
    var t;
    try { t = localStorage.getItem("yugen-ui-theme"); } catch (e) {}
    if (t !== "light" && t !== "dark") t = matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
    document.documentElement.setAttribute("data-theme", t);
  })();
</script>