Registry path

Install loaders through the shadcn registry or npm.

Use this path when your app already uses shadcn or can add a `components.json`. The CLI pulls editable source into your project, so the installed loader is local code, not a runtime package dependency. If you prefer a regular dependency, use `cellforge-loaders`.

Use Usage when

- You want the fastest install flow.
- Your app already has Tailwind and shadcn conventions.
- You want individual loaders or the full registry bundle.

Use Manual setup when

- You cannot use the shadcn CLI.
- You want to paste source files by hand.
- You are adapting CellForge to a non-standard folder layout.

Open manual setup

1. Prepare shadcn

If `components.json` is missing, initialize shadcn first. Existing projects can skip this step.

Initialize shadcn

npx shadcn@latest init

2. Register CellForge

Add the `@cellforge` registry entry once. The CLI can then resolve items like `@cellforge/cell-square-3`.

components.json

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "default",
  "tailwind": {
    "css": "app/globals.css",
    "baseColor": "neutral",
    "cssVariables": true
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks"
  },
  "registries": {
    "@cellforge": "https://cellforge.dev/r/{name}.json"
  }
}

3. Install loaders

Install one loader:

Install loader

npx shadcn@latest add @cellforge/cell-square-3

Or install the complete set:

Install all loaders

npx shadcn@latest add @cellforge/all

4. Confirm styles

Registry items include the shared CSS file. If your setup does not import it automatically, add the generated CSS import to your global stylesheet.

globals.css

@import "../components/cellforge-loader.css";

5. Use loaders in real UI states

Keep the loader close to the pending action and pair it with text when the action is not obvious.

Save button example

import { CellSquare3 } from "@/components/ui/cell-square-3";

export function SaveButton({ isSaving }: { isSaving: boolean }) {
  return (
    <button
      type="button"
      disabled={isSaving}
      aria-busy={isSaving}
      className="inline-flex items-center gap-2 rounded-md border px-3 py-2"
    >
      {isSaving ? <CellSquare3 size={18} dotSize={3} aria-label="Saving" /> : null}
      <span>{isSaving ? "Saving..." : "Save changes"}</span>
    </button>
  );
}

npm alternative

Use the npm package when you want a normal React dependency instead of copied source files. Import the package CSS once, then import loaders from `cellforge-loaders`.

Open npm package

Install package

npm install cellforge-loaders

Import CSS once

import "cellforge-loaders/styles.css";

Runtime package example

import "cellforge-loaders/styles.css";
import { CellSquare3 } from "cellforge-loaders";

export function SaveButton({ isSaving }: { isSaving: boolean }) {
  return (
    <button type="button" disabled={isSaving} aria-busy={isSaving}>
      {isSaving ? <CellSquare3 size={18} dotSize={3} ariaLabel="Saving" /> : null}
      <span>{isSaving ? "Saving..." : "Save changes"}</span>
    </button>
  );
}