# Install your first component

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

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.

```bash
npx 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.

```bash
npx 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

```tsx title="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](https://ui.ballmac.com/docs/guides/base-ui) 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:

```bash
npx 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:

```bash
npx shadcn@latest registry add @ballmac=https://ui.ballmac.com/r/{name}.json
```

It adds this to your `components.json`:

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

> **Note:** The shadcn MCP server only reads `components.json`, so it needs this entry too.

You can also install straight from a URL:

```bash
npx shadcn@latest add https://ui.ballmac.com/r/button.json
```

## Next steps

- [Connect your AI agent](https://ui.ballmac.com/docs/get-started/connect-your-agent): Let Claude Code, Cursor or VS Code search and install for you.
- [Make it yours](https://ui.ballmac.com/docs/get-started/make-it-yours): Apply a theme and set your brand color.
- [Update components](https://ui.ballmac.com/docs/guides/update-components): Merge new versions without losing your edits.
- [Registry reference](https://ui.ballmac.com/docs/reference/registry): Addresses, file locations and the JSON format.