Cloudflare Kumo: a Base UI component library from Cloudflare

What Kumo solves, and who it is aimed at

Kumo is Cloudflare's component library for building modern web applications, and its stated purpose is narrow. The README says it provides accessible, design-system-compliant UI components built on Base UI, and that it handles keyboard navigation, focus management, and ARIA attributes so you can build accessible applications without thinking through every detail. That is the whole pitch. It is not a headless primitive set, and it is not a general-purpose styling framework. It is a set of finished components that already look like Cloudflare's product surfaces.

The audience follows from that. If you are building a React application and you either want Cloudflare's visual language or you simply want accessible defaults without auditing every dialog and menu, Kumo is aimed at you. The library is written in TypeScript, so the component API is typed at the import site rather than documented only in prose. If your stack is Vue, Svelte, or server-rendered templates without a React island, the library has nothing to offer, because every entry point in the README is a React import.

Base UI underneath, and what that buys you

The architecture is layered. Base UI supplies the primitives, and Kumo re-exports all of them for advanced use cases through a separate entry point. On top of that sit the styled, design-system-compliant components that most users will import. This matters because you are not locked into the styled layer for every widget: when Kumo's Button does not fit, you can reach for the primitive and style it yourself, while still depending on one package.

The data flow is ordinary React. You import components from @cloudflare/kumo, import the stylesheet once from @cloudflare/kumo/styles, and state lives in your application. The README describes no runtime provider, no theme object to construct, and no configuration file to write. The styling system and semantic color tokens are documented in AGENTS.md rather than in the README, which is a real split: the README covers installation and imports, and AGENTS.md is where the design decisions live.

That split is worth flagging. A reader who only skims the README will not learn how tokens are named or how component styling is organised. The README explicitly points to AGENTS.md for component patterns, semantic color tokens, development workflows, the CI/CD pipeline, and the Figma plugin.

Installing @cloudflare/kumo and rendering a first component

The README gives pnpm as the install command, and it lists peer dependencies separately, which is the detail people miss. Install the library first:

pnpm add @cloudflare/kumo

Then install the peers. React and React DOM are expected, and so is the Phosphor icon package:

pnpm add react react-dom @phosphor-icons/react

With those in place, import components and the stylesheet in your app entry. The README gives this example:

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

If your bundler struggles to tree-shake the barrel import, the README offers a granular path that pulls in a single component:

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

For advanced cases where the styled layer does not fit, the primitives are re-exported too:

import { Popover } from "@cloudflare/kumo/primitives/popover";

You do not have to read the docs site to find a component. The package ships a CLI that queries component documentation from the terminal:

npx @cloudflare/kumo ls          # List all components
npx @cloudflare/kumo doc Button  # Get component docs
npx @cloudflare/kumo docs        # Get all docs

The first command prints the component list, and the second prints documentation for a single component. Running the CLI before opening the docs site is the fastest way to check whether a component exists at all.

Where Kumo is the wrong tool

The clearest limitation is framework lock-in. Every import path in the README is React, the peer dependencies are react and react-dom, and the components are distributed as a React package. If your team writes Vue, Svelte, or plain web components, Kumo is not a candidate, and the Base UI foundation does not change that, because the re-exported primitives are still consumed through Kumo's React entry points.

The second limitation is the peer dependency on @phosphor-icons/react. It is not optional in the README's install instructions, so an application already standardised on a different icon set either carries a second icon package or replaces the icons inside Kumo components. Neither is free.

The third is documentation shape. The README is short and points at AGENTS.md for component patterns, semantic color tokens, and workflows, and at kumo-ui.com for live docs. Anything about versioning policy, breaking changes, or migration between major versions is not covered in the README. The repository does carry a .changeset directory and release scripts, which indicates a structured release process, but the README does not document rollback or downgrade steps. If your organisation requires a written upgrade and rollback procedure before adoption, that procedure is something you will have to write yourself from the changesets.

How Kumo differs from other React component libraries

The obvious comparison is against libraries that ship their own unstyled primitives, such as Radix or Headless UI, where you get behaviour and accessibility but supply all the styling. Kumo sits one level higher: the components arrive styled and design-system-compliant, and the primitives are exposed underneath as an escape hatch rather than as the main product. The practical difference is how much visual work you do. With a headless library you build the appearance; with Kumo you accept Cloudflare's and override where needed.

The second comparison is against fully themed systems such as Material UI or Ant Design. Those bring a distinct visual identity plus a theming layer, and adopting them means your application looks like that system unless you invest in overrides. Kumo carries Cloudflare's identity instead, which is an advantage if you want that look and a liability if you do not. There is no theming story described in the README beyond the semantic color tokens referenced in AGENTS.md, so the realistic choice is to match the tokens rather than to replace the visual language.

A smaller but real difference is the CLI. Most component libraries expect you to browse a documentation site or read source. Kumo ships a command that lists components and prints per-component docs, which is useful when you are working in a terminal or when an agent needs the component surface without scraping a website.

Working on Kumo itself

If you are contributing rather than consuming, the repository is a pnpm workspace with the library under packages/ alongside a docs site. The README's quick start is short:

pnpm install
pnpm dev                    # Start docs site at localhost:4321
pnpm --filter @cloudflare/kumo test

The dev command runs codegen before starting the docs site, which the root package.json confirms by chaining a codegen step into dev. Tests are scoped to the library package rather than the whole workspace. There is also a scaffolding command for new components, and a Figma plugin build that the README marks as optional, gated on copying an .env.example file and setting FIGMA_TOKEN.

pnpm --filter @cloudflare/kumo new-component

One constraint to note: the root scripts include a lockfile check that reinstalls without a frozen lockfile and then fails if pnpm-lock.yaml changed. Contributors who edit dependencies and forget to commit the lockfile will see CI fail on that step rather than on their code.

Licence and maintenance cost

Kumo is MIT licensed, which is permissive: you can use it in commercial and closed-source applications, modify it, and redistribute it, provided the copyright notice and licence text are preserved. That is the standard MIT bargain, and it is the least restrictive option among common component library licences. It says nothing about trademark rights, so shipping a product that looks like Cloudflare's UI is a separate question from the code licence, and one this article cannot answer.

The maintenance signal is the release cadence. The most recent release listed is @cloudflare/[email protected] on 2026-09-17, preceded by 2.13.2 on 2026-09-08 and 2.13.1 on 2026-09-03. That is three releases inside a month, two of them patch releases, which suggests active bug-fixing rather than a frozen artifact. The repository's last push was on 2026-09-22, and it is not archived. A fast patch cadence cuts both ways: fixes arrive quickly, and the version you pin can fall behind within days. If you adopt Kumo, pin an exact version and read the changesets before bumping, because the README does not describe a compatibility policy across minor versions.

Editorial conclusion

Adopt Kumo if your application is React and you want accessible components that follow Cloudflare's design system without wiring ARIA attributes and focus management yourself. Do not adopt it if you are not on React, or if you need a documented migration or rollback path, because the README does not describe one. Before committing, check the peer dependency set (react, react-dom, @phosphor-icons/react), confirm that importing @cloudflare/kumo/styles fits your bundler, and read AGENTS.md for the component patterns and semantic color tokens the README points to.

Frequently asked questions

Official sources

1. cloudflare/kumo on GitHub
2. License: MIT
3. Project website
4. README
5. Releases