Installation

Add Calaca UI to plain HTML without a build step, or to any Tailwind CSS project such as Astro or Next.js.

Calaca UI is not on npm yet. The steps below match the test projects in its repository, which import the package exactly as shown here. The package name @calaca/ui stays the same when it is released.

Choose a setup

Prebuilt CSS for plain HTML, a CMS theme or any page without a build step. One stylesheet holds the core, a skin and every component class.
Tailwind CSS for Astro, Next.js, Vite or any other project that already builds Tailwind CSS 4. Only the classes your markup uses reach the CSS, and Tailwind utilities work next to them.

Plain HTML

Copy the files you need from @calaca/ui/dist/ into your site, then link them in the <head>:

<link rel="stylesheet" href="/calaca/ca-base.css" />
<!-- Optional: remembers the visitor's skin and appearance before first paint. -->
<script src="/calaca/ca-appearance.js"></script>
<!-- Only for dialogs: opens and closes them in browsers without invoker commands. -->
<script type="module" src="/calaca/ca-commands.js"></script>

Each built-in skin has its own file: ca-base.css, ca-calaca.css and ca-proof.css. ca-all.css holds every skin at once and switches them with data-skin (see Theming).

The prebuilt files contain no reset and no element styles, so they drop into an existing site without changing it. Style the page itself with the tokens:

body {
  background: var(--ca-surface-page);
  color: var(--ca-text-primary);
  font-family: var(--ca-font-sans);
}

Tailwind CSS

Import Calaca after Tailwind in your main stylesheet. The core comes first, the skin after it:

@import "tailwindcss";
@import "@calaca/ui/core.css";
@import "@calaca/ui/skins/base.css";

Tailwind finds the ca-* classes in your markup the way it finds its own utilities. Markup outside your project folder needs an @source line, for example @source "../content";.

Astro

Install Tailwind’s Vite plugin and add it to astro.config.mjs:

bun add @calaca/ui tailwindcss @tailwindcss/vite

import tailwindcss from "@tailwindcss/vite";
import { defineConfig } from "astro/config";

export default defineConfig({
  vite: { plugins: [tailwindcss()] },
});

Import the stylesheet above in your layout. For dialogs, load the commands polyfill once in the layout’s <head>; Astro bundles it as a module:

---
import "../styles/global.css";
---
<script>
  import "@calaca/ui/behavior/commands";
</script>

Next.js

Install Tailwind’s PostCSS plugin and add postcss.config.mjs:

bun add @calaca/ui tailwindcss @tailwindcss/postcss

export default { plugins: { "@tailwindcss/postcss": {} } };

Put the stylesheet above in app/globals.css and import it in app/layout.jsx. For dialogs, load the polyfill from a client component that the layout renders once:

"use client";

import "@calaca/ui/behavior/commands";

export function Commands() {
  return null;
}

The polyfill does nothing during server rendering, so it is safe in the App Router. In JSX the classes go in className:

<button className="ca-button ca-button--primary ca-button--md" type="button">
  Save changes
</button>

React

Any React setup with Tailwind CSS 4 works the same way as Next.js: the same stylesheet, the same classes in className. Calaca does not ship React components; the markup on each component page is the API.

Search

Documentation