Ballmac UI home
Get Pro
View as Markdown

Install your first component

Add Ballmac UI to a React and Tailwind v4 project and import your first component. It takes about a minute.

On this page

By the end of this page you have a Ballmac component running in your project.

Set up shadcn

Skip this step if your project already has a components.json. Ballmac UI needs React 19 and Tailwind CSS v4.

pnpm dlx shadcn@latest init

Add components

@ballmac is listed in the official shadcn registry directory, so the CLI already knows it. There is nothing to configure.

pnpm dlx shadcn@latest add @ballmac/button @ballmac/number-ticker

Files go to components/ballmac/, and the CLI installs the npm packages they need.

Import and use it

app/page.tsx
import { Button } from "@/components/ballmac/button"

export default function Page() {
  return <Button>Get started</Button>
}

Is your project on a Base UI style? Components that use Radix UI also come in a Base UI version, with the same props. Switch to it when you install.

Add the Ballmac theme

Every component uses the standard shadcn CSS variables, so it follows your existing theme. To match the Ballmac look (neutral light mode, ink-navy dark mode, blue focus ring), add the theme:

pnpm dlx shadcn@latest add @ballmac/theme

If the CLI doesn't know @ballmac

Recent versions of the shadcn CLI resolve @ballmac on their own. If yours doesn't, or you want to pin the address for a mirror or a preview deployment, add the registry once per project:

pnpm dlx shadcn@latest registry add @ballmac=https://ui.ballmac.com/r/{name}.json

It adds this to your components.json:

components.json
{
  "registries": {
    "@ballmac": "https://ui.ballmac.com/r/{name}.json"
  }
}

You can also install straight from a URL:

pnpm dlx shadcn@latest add https://ui.ballmac.com/r/button.json

Next steps

Connect your AI agentLet Claude Code, Cursor or VS Code search and install for you.Make it yoursApply a theme and set your brand color.Update componentsMerge new versions without losing your edits.Registry referenceAddresses, file locations and the JSON format.