Ballmac UI home
Get Pro
View as Markdown

Registry

Addresses, file locations, dependencies and the JSON format of the @ballmac shadcn registry.

On this page

Ballmac UI is a standard shadcn registry. Everything the shadcn CLI can do with a registry, it can do with @ballmac.

Addresses

Every item has a permanent name and a JSON URL:

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

The first form uses the namespace: @ballmac is in the official shadcn registry directory, so it needs no setup. The second works anywhere.

Search and inspect

pnpm dlx shadcn@latest search @ballmac -q "chat"
pnpm dlx shadcn@latest view @ballmac/prompt-input

search lists everything in @ballmac that matches. view shows an item's files, dependencies and docs.

Compare before updating

Components are your code once installed, so updates never happen silently. To see what changed in a newer version, compare before overwriting:

pnpm dlx shadcn@latest add @ballmac/button --diff
pnpm dlx shadcn@latest add @ballmac/button --overwrite

To merge new versions into edited copies instead, see Update components without losing your edits.

Where files go

  • Components: components/ballmac/, which respects your components alias and src/ folder
  • Blocks: components/ballmac/blocks/<name>/
  • Hooks and helpers: hooks/ballmac/, lib/ballmac/

Ballmac UI never writes to components/ui, so it can't overwrite your shadcn/ui components.

Dependencies

Each item declares the npm packages it imports and the registry items it builds on, for example @ballmac/motion-presets or shadcn's utils. The CLI installs them for you. Every build checks that declared dependencies match the actual imports.

JSON format

Items follow the official shadcn registry schema. The full index is at ui.ballmac.com/r/registry.json. Each item's meta adds Ballmac fields for tools and agents: tier, tags, version, when to use it, what it composes with, and keyboard notes.

shadcn search @ballmac --query button returns ranked results from our server instead of downloading the whole 1,600-item catalog. The CLI sends q, type, limit and offset to /r/registry.json and gets back the matching items with a pagination object:

curl "https://ui.ballmac.com/r/registry.json?q=data+grid&type=registry:ui&limit=5"

Components rank ahead of blocks, and blocks ahead of examples, when two items match equally well. Every word of the query has to match something in the name, title, tags, category or description. Without any of those parameters the response is the full catalog, as before, so older clients are unaffected.

The same data is available as a JSON API, and as llms.txt for assistants.