Quick start

It's dangerous to go alone! Take this. Install the kit, add your first component and set up what your app needs once.

Kappa UI is a Vue 3 UI kit in two halves. Components are Vue files copied into your project, so the code is yours to read and change. The core package, @kappa-ui/core, holds the behaviour behind them, such as overlays, toasts and directives, and updates from npm like any other dependency.

Two halves
Your project
components/ui/button/
Button.vue
index.ts

Components, copied in by the CLI.

Yours to edit
imports
@kappa-ui/core
OverlaysToastsDirectivesGestures

The behaviour behind them, from npm.

Updates with npm

Install

You need a Vue 3 or Nuxt project with Tailwind CSS v4. Version 3 won't do: components use utilities it doesn't have.

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

    You get a components.json, the cn() helper, and the tokens and default theme in your stylesheet. Tokens are the CSS variables components read, such as --primary or --radius: change one, and every component that reads it follows.
  2. Find this line in your stylesheet. Init added it, so leave it there:
    @import "@kappa-ui/core/tailwind.css";
    

    It brings the utilities components are drawn with, and updates with the core package.

Using Nuxt? Add a bit of config too. Already have a components.json? Skip init and follow Installation instead.

Add a component

  1. Add the button:
    npx shadcn-vue@latest add @kappa-ui/button
    

    The component lands in components/ui/button. It's your code now: edit it however you like.
  2. Use it:
    <script setup lang="ts">
    import { Button } from '@/components/ui/button'
    </script>
    
    <template>
      <Button variant="outline" color="neutral">Button</Button>
    </template>
    

    variant is the look: solid, soft, subtle, outline, ghost or link. color picks the tone, the colour it's drawn in: primary, neutral, destructive, success, warning or info. size runs from xs to xl, on one scale shared by every control.

Two things hold for every component:

  • It takes one class prop, merged over its own classes, so yours win.
  • Its root carries a data-slot attribute, so you can target it from CSS and tests without relying on class names.

One-time app setup

Some components need a line or two at the app root, once. Skip what you don't use.

  • ConfigProvider with :scroll-body="false" around the app. You need this if you use a select, a menu, a dialog, a drawer or a modal popover. Kappa UI keeps the scrollbar's space while one is open, so without :scroll-body="false", Reka UI pads the page a second time and it jumps sideways. Overlays
  • createDialogs() and one DialogHost. You need this if you open dialogs, drawers or confirms from code. Dialog
  • createToaster() and one Toaster. You need this if you show toasts. Toast
  • TooltipProvider around the app. Optional: tooltips work without it, but with it, the next tooltip along a toolbar opens instantly. Tooltip
  • app.directive('ripple', vRipple). You need this if you put v-ripple on your own elements. Kappa UI's pressable parts import it themselves. Ripple
  • DrawerIndent around the app. Optional: the page steps back while a drawer is open. Put DialogHost inside it. Drawer

All of it together, in a Vite app:

// main.ts
import { createApp } from 'vue'

import { createDialogs } from '@/components/ui/dialog'
import { createToaster } from '@/components/ui/toast'
import vRipple from '@/lib/ripple'
import App from './App.vue'

const app = createApp(App)
app.use(createDialogs())
app.use(createToaster())
app.directive('ripple', vRipple)
app.mount('#app')
<!-- App.vue -->
<script setup lang="ts">
import { ConfigProvider } from 'reka-ui'

import { DialogHost } from '@/components/ui/dialog'
import { Toaster } from '@/components/ui/toast'
import { TooltipProvider } from '@/components/ui/tooltip'
</script>

<template>
  <ConfigProvider :scroll-body="false">
    <TooltipProvider>
      <RouterView />
      <DialogHost />
    </TooltipProvider>
    <Toaster />
  </ConfigProvider>
</template>

In Nuxt, install createDialogs() and createToaster() from plugins instead, as Dialog and Toast show.

Next