Your first component.

01. Before you begin

Start with a React application and Tailwind CSS. This repository is tested with React 19 and Tailwind CSS 4. The components have no Next.js imports, so Next.js is optional for consumers.

npx shadcn@latest init

The generated Gear5 imports use @/components/gear5 and @/lib/gear5. Make sure @/* resolves to the directory containing those folders. Review your components.json configuration if your project uses a different layout.

02. Install a component

Run this in your application directory. The registry includes the source and its shared Gear5 helpers.

npx shadcn@latest add https://gear5-ui.vercel.app/r/async-boundary.json

For this example, you will get the component plus helpers for class names, announcements, network state, and locale information. They are source files in your repo, not extra runtime packages.

Already customised a file? Review the diff before replacing it. You choose when to adopt upstream changes.

03. Make it work

This self-contained example simulates an error and recovers when you press retry. In your application, connect status and retry to your own data layer.

"use client";

import { useState } from "react";
import { AsyncBoundary } from "@/components/gear5/async-boundary";

export default function Workspace() {
  const [failed, setFailed] = useState(false);

  return (
    <section>
      <button onClick={() => setFailed(true)}>Simulate an error</button>
      <AsyncBoundary
        status={failed ? "error" : "ready"}
        onRetry={() => setFailed(false)}
        minHeight="10rem"
        labels={{ error: "Could not load the workspace.", retry: "Try again" }}
      >
        <p>Your workspace is ready.</p>
      </AsyncBoundary>
    </section>
  );
}

Interactive components use React hooks. In an App Router project, keep event handlers inside a Client Component, as shown above. View all AsyncBoundary props and source →

04. Language and direction

Install a formatting component, then pass an explicit locale. Its shared LocaleProvider helper is included. Resolve the same locale on the server and client to avoid hydration differences.

npx shadcn@latest add https://gear5-ui.vercel.app/r/compact-number.json

import { LocaleProvider } from "@/lib/gear5/use-locale";
import { CompactNumber } from "@/components/gear5/compact-number";

export default function Visitors() {
  return (
    <LocaleProvider locale="ar-EG">
      <p lang="ar" dir="rtl">
        <CompactNumber value={1234567} /> زائر
      </p>
    </LocaleProvider>
  );
}

The provider supplies locale facts to components that consume them. It does not translate text or change your document attributes. Supply translated labels, and set lang and dir on your app or the relevant region.

05. Styling and dark mode

Components use Tailwind utilities and accept className where supported. Keep the installed files within Tailwind's scanned source directories. The docs site's gold palette is custom styling, not a requirement.

For class-based dark mode with Tailwind 4, include this in your application's global CSS:

@import "tailwindcss";
@custom-variant dark (&:where(.dark, .dark *));

/* Gear5 controls use this foreground token on accent fills.
   Choose colours with sufficient contrast for your theme. */
@theme {
  --color-on-accent: #ffffff;
}

Add the dark class to your document root or use ThemeToggle. If you change the accent background, check its contrast with text-on-accent.

06. Before you ship

• Test your labels and content with keyboard navigation, a screen reader, and the locales your users need.
• For draft persistence, use a formKey scoped to the signed-in user, clear it on sign-out, and mark sensitive fields with data-no-persist. Use persistDraft={false} when storage is inappropriate.
• Do not treat a lost response as a failed transaction. Safe retries need a server-side idempotency contract.
• Automated fixture checks are a baseline. Re-run checks after changing components or integrating them into your application.