Installation

Requirements

KiotaPay components are built against the same stack shadcn/ui targets. Your project needs:

• Tailwind CSS v4 with CSS variables enabled
• shadcn/ui initialised — a components.json at the project root
• React 19 or later

If you do not have components.json yet, create it first:

npx shadcn@latest init

Add a component directly

Every item is a plain JSON file over HTTP, so nothing has to be configured before your first install:

pnpm dlx shadcn@latest add https://kiotapay-ui-staging.staging.kiotapay.com/r/money-input.json

npx shadcn@latest add https://kiotapay-ui-staging.staging.kiotapay.com/r/money-input.json

yarn dlx shadcn@latest add https://kiotapay-ui-staging.staging.kiotapay.com/r/money-input.json

bunx --bun shadcn@latest add https://kiotapay-ui-staging.staging.kiotapay.com/r/money-input.json

The CLI reads the item, installs any npm packages it needs, pulls in the shadcn primitives it depends on, and writes the source into your project.

Register the namespace

Adding the registry to components.json lets you use the shorter @kiota/… form and makes the registry discoverable to shadcn search and shadcn view.

{
"$schema": "https://ui.shadcn.com/schema.json",
"registries": {
  "@kiota": "https://kiotapay-ui-staging.staging.kiotapay.com/r/{name}.json"
}
}

{name} is a required placeholder — the CLI substitutes the item name at resolve time. With that in place:

pnpm dlx shadcn@latest add @kiota/money-input

npx shadcn@latest add @kiota/money-input

yarn dlx shadcn@latest add @kiota/money-input

bunx --bun shadcn@latest add @kiota/money-input

Keeping the origin configurable

Rather than hardcoding the host, use an environment variable. The shadcn CLI expands ${VAR} in registry configuration from your environment:

{
"registries": {
  "@kiota": "${REGISTRY_URL}/r/{name}.json"
}
}

# .env.local
REGISTRY_URL=https://ui.kiotapay.com

The CLI is not a Next.js process, so it does not read NEXT_PUBLIC_* variables automatically. Use REGISTRY_URL for the CLI/server build and NEXT_PUBLIC_REGISTRY_URL where the browser also needs the value.

Where files land

Custom components install into custom/ rather than ui/, keeping our code separate from the shadcn primitives it builds on:

  components/
    ui/
+     input.tsx          ← shadcn primitive, pulled in as a dependency
      button.tsx
    custom/
+     money-input.tsx    ← the item you asked for
  hooks/
+   use-copy.ts
  lib/
+   kiota-format.ts

Destinations follow your own components.json aliases, so a project using src/ or non-default alias paths gets the right locations without any configuration on your side.

Private hosting

If the registry moves behind authentication, consumers supply a token through the same config:

{
"registries": {
  "@kiota": {
    "url": "${REGISTRY_URL}/r/{name}.json",
    "headers": { "Authorization": "Bearer ${KIOTA_REGISTRY_TOKEN}" }
  }
}
}