Installation

It works on my machine. Now on yours too. Set up a project, add components and keep them up to date.

Requirements

A Vue 3 or Nuxt project with Tailwind CSS v4. Components rely on utilities that v3 doesn't have or draws differently, and nothing checks your version for you. Check it before you add anything.

The components are written in TypeScript, so a TypeScript project needs TypeScript 5 or 6. vue-tsc, which checks .vue files, won't run on anything older than 5.0.

Set up

  1. Run init once:
    npx shadcn-vue@latest init --preset https://kappa-ui.pages.dev/r/init.json
    

    It creates components.json with the @kappa-ui registry, adds the cn() helper and writes the tokens and the default theme into your stylesheet.
  2. Add a component:
    npx shadcn-vue@latest add @kappa-ui/button
    

    Its source lands in your project. From here on, it's your code.

Here's what the two commands leave behind:

What lands in your project
components.jsonThe @kappa-ui registryinit
lib/utils.tscn(), which knows the typescaleinit
Your stylesheetTokens, the theme and @import "@kappa-ui/core/tailwind.css"init
package.json@kappa-ui/core and the dependencies of each componentinitadd
components/ui/button/Button.vue and the index.ts that exports itadd

Using Nuxt? Do the Nuxt step too.

Every component page has its own install command. It uses the full URL, which works with or without init. Rather copy files by hand? The Manual tab lists the dependencies and files:

Already have components.json?

Skip init and add the registry to it instead:

components.json
{
  "registries": {
    "@kappa-ui": "https://kappa-ui.pages.dev/r/{name}.json"
  }
}

Components work with the theme you already have. Want Kappa UI's look as well? Add the theme.

Nuxt

Nuxt registers every file under components/ as a component. Each component folder holds both Button.vue and an index.ts that re-exports it, so both claim the name UiButton and Nuxt warns about the clash (NUXT_B3011). Scan .vue files only:

nuxt.config.ts
export default defineNuxtConfig({
  components: [{ path: '~/components', extensions: ['.vue'] }],
})

This array replaces Nuxt's default directories instead of adding to them. Using components/global or components/islands? List them too.

Theme

Components read colour tokens but never set them. Your existing theme keeps working, and adding a component never changes a colour you've set.

Kappa UI's own look is the theme item. Init adds it. Skipped init? Add it once, and the CLI asks before overwriting your variables:

The theme makes --primary and --ring follow --brand, so rebrand through --brand. See Brand colour.

Update

Components are your code, so they change only when you add them again. --overwrite replaces the file with the current version, and your edits go with the old one, so commit first:

npx shadcn-vue@latest add @kappa-ui/button --overwrite

The core package updates from npm. Install its latest release:

npm install @kappa-ui/core@latest

npm update won't get you there: it stays inside the range the CLI wrote, such as ^0.9.0, and while the version starts with 0., a caret range never reaches the next minor release.

What installing changes

Some items write to your global stylesheet, not just to their own files. Here's what lands there.

Components that need them bring the tokens item. It only adds variables your theme doesn't have, so it never replaces anything:

  • the status colours --success, --warning and --info, and --destructive-foreground
  • the shadow and state tokens from Theming
  • the typescale, motion and control size tokens
  • the corner roles --radius-control-*, --radius-surface-* and --radius-item-*, scaled from your --radius

tokens also adds the core package as a dependency, and one line to your stylesheet: @import "@kappa-ui/core/tailwind.css";. That file holds the utilities components are drawn with, such as state-layer, focus-ring and press-scale, and updates with the package. The tokens stay in your stylesheet, where you can change them.

Button also adds the base rule that shadcn-vue init --pointer installs. Tailwind v4 dropped the pointer cursor on buttons, and this brings it back for every button in your project, not only Kappa UI's:

@layer base {
  button:not(:disabled),
  [role="button"]:not(:disabled) { cursor: pointer; }
}

Content Security Policy

Got a Content Security Policy? Parts from the core package set the styles they depend on inline: the overlay scrim's position, the ripple's geometry and the scroll area's overflow. With server-side rendering, some of them reach the page as style="" attributes. A policy that forbids inline style attributes blocks those, hydration doesn't put them back, and the parts stop working.

If your policy sets style-src or style-src-attr, allow 'unsafe-inline' for style attributes.

Next