Components
installation

Installation

Set up JK-UI with the same file structure used by the official templates

JK-UI follows the shadcn distribution model: components and styles are copied into your project and remain yours to customize.

1. Initialize shadcn

Use the React Aria base:

bunx --bun shadcn@latest init --base aria

Verify that components.json points to your real main CSS file and aliases:

{
  "tailwind": {
    "css": "src/styles/globals.css"
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "lib": "@/lib",
    "hooks": "@/hooks"
  }
}

2. Register JK-UI

bunx shadcn@latest registry add @jk-ui=https://jk-ui.unoforge.com/r/{name}.json

Equivalent manual components.json configuration:

{
  "registries": {
    "@jk-ui": "https://jk-ui.unoforge.com/r/{name}.json"
  }
}

3. Install an icon library

JK-UI supports any Iconify icon source. Choose one:

Phosphor (default):

bun add -D @iconify-json/ph

Or any Iconify source:

# Heroicons
bun add -D @iconify-json/heroicons

# Lucide
bun add -D @iconify-json/lucide

# HugeIcons
bun add -D @iconify-json/hugeicons

# Solar
bun add -D @iconify-json/solar

Update the iconLibrary in components.json:

{
  "iconLibrary": "ph"  // or "heroicons", "lucide", "hugeicons", "solar"
}

5. Install the foundation

bunx shadcn add @jk-ui/base

base installs everything shared by JK-UI:

the default light/dark variables and Tailwind mappings into the main CSS declared in components.json
styles/jk-ui/base.css, form.css, button.css, ui.css, intents.css, utils.css
lib/utils.ts, lib/ui-variants.ts, lib/ui-variant-types.ts
Required dependencies (React Aria, tailwind-variants, animations)

6. Configure the main CSS

Use this structure in the CSS file declared in components.json:

@import "tailwindcss";
@import "tw-animate-css";

@reference "./jk-ui/base.css";
@reference "./jk-ui/form.css";
@reference "./jk-ui/button.css";
@reference "./jk-ui/ui.css";
@reference "./jk-ui/intents.css";
@reference "./jk-ui/utils.css";

@plugin "@iconify/tailwind4" {
  prefixes: ph;
  scale: 1.0;
}

The shadcn CLI writes the semantic variables and their @theme inline mappings directly into this main CSS file. The @reference files expose reusable JK-UI utilities without duplicating their CSS. Adjust relative paths when your main CSS lives elsewhere.

7. Install components

bunx shadcn add @jk-ui/button
bunx shadcn add @jk-ui/card
bunx shadcn add @jk-ui/input

Every UI registry item depends on @jk-ui/base; installing a component in a fresh project therefore brings the foundation automatically. You only configure the main CSS once.

import { Button } from "@/components/jk/button"

export default function Page() {
  return <Button intent="primary">Continue</Button>
}

Optional theme preset

The base already contains the editable default palette. Install a preset only when you want to replace it:

npx shadcn add @jk-ui/theme-water

Alternative install methods

Method	Example
Namespace	`npx shadcn add @jk-ui/button`
Direct URL	`npx shadcn add https://jk-ui.unoforge.com/r/button.json`
GitHub	`npx shadcn add johnkat-mj/jk-ui/button`

Next: Theming, Colors, Migration.

Edit this page

AI Skills