Installation

NPM Registry

The @cloudflare/kumo package is published to the public npm registry. No special configuration is required for installation.

Install Package

Install Kumo using your preferred package manager. The current version is v1.5.1.

npm

npm install @cloudflare/kumo@1.5.1

pnpm

pnpm add @cloudflare/kumo@1.5.1

yarn

yarn add @cloudflare/kumo@1.5.1

Peer Dependencies

Kumo requires the following peer dependencies. Most React projects will already have these installed:

# Required peer dependencies
pnpm add react react-dom @phosphor-icons/react

Import Components

Import components from the main package or use granular imports for better tree-shaking:

Main Package Import

import { Button, Input, Surface } from "@cloudflare/kumo";

Granular Import (Recommended)

import { Button } from "@cloudflare/kumo/components/button";
import { Input } from "@cloudflare/kumo/components/input";

Kumo is built on top of Base UI, a library of unstyled, accessible React components. For advanced use cases where you need access to the underlying primitives, Kumo re-exports all 37 Base UI components with both barrel and granular imports:

Barrel Import (Convenient)

// Import multiple primitives at once
import { Popover, Slider, Accordion } from "@cloudflare/kumo/primitives";

Granular Imports (Recommended for Performance)

// Import individual primitives for better tree-shaking
import { Popover } from "@cloudflare/kumo/primitives/popover";
import { Slider } from "@cloudflare/kumo/primitives/slider";
import { Accordion } from "@cloudflare/kumo/primitives/accordion";

Granular imports result in smaller bundle sizes by only including the primitives you actually use.

Available Primitives (37 total):

Layout: Accordion, Collapsible, Separator, ScrollArea, Toolbar
Overlays: AlertDialog, Dialog, Popover, PreviewCard, Tooltip, Toast
Menus: Menu, Menubar, ContextMenu, NavigationMenu
Form Controls: Autocomplete, Button, Checkbox, CheckboxGroup, Combobox, Input, NumberField, Radio, RadioGroup, Select, Slider, Switch, Toggle, ToggleGroup
Form Structure: Field, Fieldset, Form
Display: Avatar, Meter, Progress, Tabs

Note: Prefer using styled Kumo components when available. Primitives are intended for building custom components that aren't yet available in Kumo, or for cases requiring fine-grained control over styling and behavior.

Import Styles

Kumo provides two CSS distribution options depending on your setup:

For Tailwind CSS Users (Recommended)

If your application uses Tailwind CSS, add Kumo's source files to your content configuration and import the styles. Import order matters — Kumo styles must come before @import "tailwindcss" so that Kumo's theme tokens are registered first:

Important: Tailwind CSS v4 does not scan node_modules/ by default. You must add a @source directive so Tailwind can discover the utility classes used by Kumo components. Without this, components may render with missing styles (e.g. Dialogs not centered).

/* app.css or main.css */
@source "../node_modules/@cloudflare/kumo/dist/**/*.{js,jsx,ts,tsx}";
@import "@cloudflare/kumo/styles/tailwind";
@import "tailwindcss";

/* Your custom styles */

The @source path is relative to your CSS file. Adjust it based on your project structure — e.g. if your CSS is in src/styles/, you may need ../../node_modules/@cloudflare/kumo/dist/**/*.{js,jsx,ts,tsx}.

Note: You can also use the default export @cloudflare/kumo/styles which is equivalent to styles/tailwind.

For Non-Tailwind Users (Standalone)

If your application doesn't use Tailwind CSS, use the standalone build which includes all compiled styles:

// In your app entry point (e.g., main.tsx, index.tsx)
import "@cloudflare/kumo/styles/standalone";

The standalone build includes all Tailwind utilities and Kumo component styles pre-compiled. No Tailwind configuration needed!

Usage Example

Here's a complete example of using Kumo components with Tailwind CSS:

CSS File (app.css)

@source "../node_modules/@cloudflare/kumo/dist/**/*.{js,jsx,ts,tsx}";
@import "@cloudflare/kumo/styles/tailwind";
@import "tailwindcss";

Note: The @source path is relative to your CSS file. Adjust it based on your project structure.

Component File (App.tsx)

import { Button, Input, Surface } from "@cloudflare/kumo";
import "./app.css";

export default function App() {
  return (
    <Surface className="p-6 rounded-lg">
      <h1 className="text-2xl font-bold mb-4">Welcome to Kumo</h1>
      <Input placeholder="Enter your name..." className="mb-4" />
      <Button variant="primary">Submit</Button>
    </Surface>
  );
}

Blocks vs Components

Kumo provides two types of building blocks for your application:

Components (NPM Exports)

Components are published as NPM exports and can be imported directly from the package. These are the core UI primitives like Button, Input, and Dialog.

import { Button, Input, Dialog } from "@cloudflare/kumo";

Use components when you need consistent, pre-styled UI primitives that integrate seamlessly with your application. Components are versioned, tree-shakeable, and receive automatic updates.

Blocks (CLI Installation)

Blocks are higher-level compositions (like PageHeader and ResourceListPage) that are installed via the Kumo CLI. Blocks give you full ownership of the code, allowing you to customize them to your specific needs.

# Initialize Kumo configuration
npx @cloudflare/kumo init

# List available blocks
npx @cloudflare/kumo blocks

# Install a block
npx @cloudflare/kumo add PageHeader

After installation, blocks live in your project (e.g., src/components/kumo/) and can be customized as needed. The CLI automatically transforms imports from relative paths to @cloudflare/kumo for seamless integration.

import { PageHeader } from "src/components/kumo/page-header/page-header";

When to use blocks:

• You need to customize the component beyond props
• You want full control over the implementation
• You're building application-specific layouts
• You prefer copy-paste over package dependencies for certain code

Utilities

Kumo also exports utility functions for common tasks:

import { cn, safeRandomId, LinkProvider } from "@cloudflare/kumo";

// Merge class names with Tailwind
const className = cn("base-class", condition && "conditional-class");

// Generate safe random IDs
const id = safeRandomId();

// Configure link component for your framework
<LinkProvider component={YourLinkComponent}>
  {/* Your app */}
</LinkProvider>