Skip to main content
Join the waitlist

Install

Add @usefragments/ui to your React app, load the styles, and start composing.

Start with a React 18 or 19 app and the Node.js version your framework requires. TypeScript is recommended. The package works independently of Fragments desktop; CLI tooling and copied source are optional.

Choose your path

Use the npm package for Fragments UI. Copied source is optional when your project needs to own the component files.

Package

The recommended install, managed by your package manager. If you later need copied source, preview npx @usefragments/cli registry migrate --dry-run.

npm install @usefragments/ui

Heavy optional peer dependencies are needed only by the components that consume them. Import styles once, then wrap providers from @usefragments/ui.

App.tsx
import "@usefragments/ui/styles";
import type { ReactNode } from "react";
import { Theme, Tooltip, Toast } from "@usefragments/ui";

function App({ children }: { children: ReactNode }) {
  return (
    <Theme defaultMode="system">
      <Tooltip.Provider>
        <Toast.Provider>{children}</Toast.Provider>
      </Tooltip.Provider>
    </Theme>
  );
}

  1. Load styles in your app

    Import the stylesheet once at your app entry point. Use the Package or Source tab to match the installation you chose above.

    Vite

    // src/main.tsx
import "@usefragments/ui/styles";

    Source examples assume @/* maps to src/*. Without that alias, use --import-path "./fragments/ui" when adding source and import ./fragments/ui/styles/globals.scss here.

    Next.js

    // app/layout.tsx
import "@usefragments/ui/styles";

    Keep state, event handlers, and theme providers in a client component. Add 'use client' at that component's entry point. For a saved theme that loads before the first paint, follow the Theme guideto add ThemeScript and the matching provider.

    If your Next.js version reports an untranspiled package error, add transpilePackages: ['@usefragments/ui'] to its configuration.

  2. Render a component

    Import components from the package. Compound components group their parts under one name: Card.Header, Card.Body, and Card.Footer all come from Card.

    "use client";

import { Button, Card } from "@usefragments/ui";

export function Welcome() {
  return (
    <Card>
      <Card.Header>
        <Card.Title>Ready to build</Card.Title>
      </Card.Header>
      <Card.Body>Compose your interface from Fragments components.</Card.Body>
      <Card.Footer>
        <Button>Start a project</Button>
      </Card.Footer>
    </Card>
  );
}

    Confirm the card and button are styled. If they render without styling, check that the stylesheet import is in the entry file your app actually loads.

Set your theme

Set the brand seed in your app's CSS. Load this after the package stylesheet.

styles/globals.css
:root {
  --fui-seed-brand: #6366f1;
}

Use Theme for light, dark, and system modes. Components inside it read the current mode; useTheme lets your own controls change it.

Optional Sass configuration

Install sass as a dev dependency if you use Sass configuration. The package's explicit Sass entry configures tokens; keep the prebuilt CSS for component styles.

styles/globals.scss
@use "@usefragments/ui/scss" with (
  $fui-brand: #6366f1,
  $fui-radius-style: "rounded"
);
import "@usefragments/ui/styles";
import "./styles/globals.scss";

Optional agent tooling

For repository checks and local MCP access in Claude Code, Codex, or Cursor, add the standalone CLI setup. This is separate from Fragments desktop's checks.

npx @usefragments/cli@latest init --install --metadata-only

Continue with the local MCP guide to verify the integration, or read the Desktop Checks guide when working in the app.

Optional copied source

Use the public source registry when your project needs the component files in its own repository. No account or key is required. add writes the selected components, their source dependencies, a stylesheet, and a registry lockfile.

Copied-source commands
Command
Purpose
npx @usefragments/cli add button cardCopy named components. Use --all for the full library.
npx @usefragments/cli registry statusInspect the lockfile and installed source.
npx @usefragments/cli registry diffCompare installed source with the registry artifact.
npx @usefragments/cli registry syncRefresh the selection recorded in the lockfile.

The first install chooses the source directory and import path; later runs keep the lockfile's settings. See the CLI reference for custom paths, local artifacts, and existing authenticated Cloud registries.

Move an existing app to source

Preview the migration before applying it. It installs source and rewrites package imports. The UI package is removed unless you pass --keep-package.

npx @usefragments/cli registry migrate --dry-run
npx @usefragments/cli registry migrate

Review source changes

Commit .fragments/registry-lock.json with the installed files. Local edits can differ from its recorded hashes. Review statusand diff before refreshing; use the registry commands to update managed source. npx @usefragments/cli check checks registry integrity along with your configured rules.

Next steps