BREAKING: Checkbox onCheckedChange now receives event details as second argument

The onCheckedChange callback signature now matches Base UI, providing access to the underlying event:

// Before
onCheckedChange={(checked) => console.log(checked)}

// After (event details available as optional second arg)
onCheckedChange={(checked, eventDetails) => {
  console.log(checked);
  console.log(eventDetails.event); // native event
}}

Removed deprecated props:

• onChange - use onCheckedChange instead
• onValueChange on individual checkboxes - use onCheckedChange instead
• onClick - was redundant, use standard React event handling via spread props

Migration:

// Before (deprecated)
<Checkbox onChange={(e) => console.log(e.target.checked)} />
<Checkbox onValueChange={(checked) => setChecked(checked)} />

// After
<Checkbox onCheckedChange={(checked) => setChecked(checked)} />

Note: Checkbox.Group's onValueChange prop is unchanged - it still accepts (values: string[]) => void.

feat(Collapsible)!: refactor to compound component API

Breaking change: Collapsible now uses a compound component pattern matching other Kumo components like Popover and Dialog.

Before

<Collapsible label="Show details" open={open} onOpenChange={setOpen}>
  Content here
</Collapsible>

After

<Collapsible.Root open={open} onOpenChange={setOpen}>
  <Collapsible.Trigger>Show details</Collapsible.Trigger>
  <Collapsible.Panel>Content here</Collapsible.Panel>
</Collapsible.Root>

Migration

For the quickest migration, use the new DefaultTrigger and DefaultPanel components which preserve the previous styling:

<Collapsible.Root open={open} onOpenChange={setOpen}>
  <Collapsible.DefaultTrigger>Show details</Collapsible.DefaultTrigger>
  <Collapsible.DefaultPanel>Content here</Collapsible.DefaultPanel>
</Collapsible.Root>

New Sub-components

feat(Text): decouple visual heading variants from semantic HTML elements

Breaking change: heading1, heading2, heading3 variants no longer auto-render <h1>, <h2>, <h3> tags. They now render as <span> by default. Use the as prop to set the appropriate semantic heading level for your document outline.

Before:

<Text variant="heading1">Title</Text> // rendered <h1>

After:

<Text variant="heading1" as="h1">
  Title
</Text> // explicit semantic element

The as prop is now restricted to valid text elements: "h1" through "h6", "p", and "span".

feat(radio, checkbox, switch): add composable Legend sub-component for group components

• Add Radio.Legend, Checkbox.Legend, and Switch.Legend sub-components
• Accepts className for full styling control (e.g. className="sr-only" to visually hide)
• Make legend string prop optional when using the sub-component instead
• Useful when a parent Field already provides a visible label and the legend would be redundant
• Breaking: Switch.Group no longer renders a visible border/padding/rounded container — now consistent with Radio.Group and Checkbox.Group. Use className to add a border if needed.

Add InputGroup compound component for composing decorated inputs

Compound structure: InputGroup, InputGroup.Input, InputGroup.Addon, InputGroup.Suffix, InputGroup.Button.

• Field integration — pass label, description, error, required, and labelTooltip directly to InputGroup
• Size variants (xs, sm, base, lg) propagate to all sub-components via context, including icon sizing in addons
• InputGroup.Addon — positions icons, text, or buttons at align="start" (default) or align="end" of the input
• InputGroup.Suffix — inline text suffix (e.g. .workers.dev)
• InputGroup.Button — ghost button for secondary actions with tooltip support
• Deprecated InputGroup.Label — use InputGroup.Addon instead
• Deprecated InputGroup.Description — use InputGroup.Suffix instead

{
  /* Reveal / hide password */
}
<InputGroup>
  <InputGroup.Input
    type={show ? "text" : "password"}
    defaultValue="password"
    aria-label="Password"
  />
  <InputGroup.Addon align="end" className="pr-1">
    <InputGroup.Button
      size="sm"
      aria-label={show ? "Hide password" : "Show password"}
      onClick={() => setShow(!show)}
    >
      {show ? <EyeSlashIcon size={16} /> : <EyeIcon size={16} />}
    </InputGroup.Button>
  </InputGroup.Addon>
</InputGroup>;

{
  /* Search input */
}
<InputGroup>
  <InputGroup.Addon>
    <MagnifyingGlassIcon className="text-kumo-subtle" />
  </InputGroup.Addon>
  <InputGroup.Input placeholder="Search..." />
</InputGroup>;

Adds Autocomplete component. A free-form text input with an optional filtered suggestion list. Unlike Combobox, the value is not constrained to the items list.

feat(radio): accept ReactNode for Radio.Item label and honor controlPosition on card appearance

• Radio.Item's label prop now accepts ReactNode, allowing icons, badges, or other markup alongside text.
• Radio.Group's controlPosition prop now takes effect on appearance="card". Card appearance continues to default to "end" (radio on the right); pass controlPosition="start" to render the radio on the left of the label and description.

Polish TableOfContents indicator and semantic HTML

• Replace pill/background-tint hover with left-border indicator pattern
• Switch to semantic ul/li HTML structure
• Add href and active props to TableOfContents.Group for clickable labels

Update chart color docs and demos, including sequential heatmap/CVD coverage and improved chart demo behavior.

Improved focus and keyboard accessibility styles across Kumo components and docs navigation.

• Added the kumo-focus semantic token to the theme generator config and generated theme-kumo.css output.
• Updated focus ring behavior across interactive components (including Button, Input, InputGroup, Select, Checkbox, Radio, Switch, Sidebar, Tabs, Menubar, and related controls) for more consistent and visible keyboard focus visibility.
• Text-entry controls use a lighter opacity kumo-focus ring to keep pointer and keyboard focus visually consistent where browsers apply :focus-visible heuristics to typed-input controls.
• Refined Select and Input styling/state combinations to align focus visuals with current semantic token usage.
• Updated docs SidebarNav keyboard-focus affordances (links, section toggles, search trigger) and adjusted collapsible list overflow so focus rings remain visible.
• Replace raw colors in Select with kumo semantic tokens.

chore: update @base-ui/react to v1.4.0

Bugfix release with improvements to Popover hover state, Checkbox/Switch readOnly mode, Select touch handling, Tabs activation direction, Toast timers, and various other fixes. No breaking changes.

feat(chart): rename formatter to dangerousHtmlFormatter for XSS awareness

BREAKING CHANGE: The formatter property in KumoChartOption['tooltip'] has been renamed to dangerousHtmlFormatter. This change makes the security implications of using HTML formatters more explicit to developers. The API remains identical—only the name has changed.

Migration: Replace formatter with dangerousHtmlFormatter in your chart tooltip configurations.

feat(tooltip, popover): deprecate asChild in favor of render prop

Unifies composition patterns across the library by adopting Base UI's render prop pattern. The asChild prop is now deprecated on:

• Tooltip
• Popover.Trigger
• Popover.Close

Migration:

- <Tooltip content="Save" asChild>
-   <Button>Save</Button>
- </Tooltip>
+ <Tooltip content="Save" render={<Button>Save</Button>} />

- <Popover.Trigger asChild>
-   <Button>Open</Button>
- </Popover.Trigger>
+ <Popover.Trigger render={<Button>Open</Button>} />

- <Popover.Close asChild>
-   <Button>Close</Button>
- </Popover.Close>
+ <Popover.Close render={<Button>Close</Button>} />

The asChild prop remains functional for backward compatibility but will be removed in a future major version.

feat(popover): expose anchor prop on Popover.Content for virtual positioning

Forwards Base UI's anchor prop through Popover.Content to the underlying Positioner, enabling popover positioning against custom elements, refs, or virtual points (e.g., a DOMRect from getBoundingClientRect()). This is useful when the popover trigger and the desired anchor are in different component trees, or when anchoring to a coordinate rather than a DOM element.

Convert Table of Contents to exported Kumo component

feat(Select): add size prop (xs/sm/base/lg) matching Input and Combobox heights

feat(layer-card): support simple card usage and deprecate Surface

• allow LayerCard to be used directly without LayerCard.Primary for simple single-layer card layouts
• keep LayerCard.Secondary and LayerCard.Primary supported for the existing layered card pattern
• deprecate Surface in favor of LayerCard while keeping the old API working as a compatibility wrapper
• update docs and examples to prefer LayerCard, including table examples that no longer need a nested LayerCard.Primary

fix(pagination): add ARIA attributes for screen reader accessibility

• Wrap pagination controls in <nav> for proper landmark navigation
• Add aria-live="polite" and aria-atomic="true" to status text for page change announcements
• Add navigation to PaginationLabels for i18n customization of the nav aria-label

fix(chart): escape HTML in tooltip series name and values

Escapes HTML entities in TimeseriesChart tooltip series names and values before rendering.

fix(combobox): make TriggerInput caret button clickable for Playwright tests

fix(dropdown): pass children through when render prop is provided on DropdownMenu.Trigger

fix(Select): TypeScript inference with strictNullChecks and renderValue/placeholder interaction

TypeScript fix: Under strictNullChecks, using value={objectOrNull} would cause T to be inferred as never, making callbacks like onValueChange and renderValue unusable. This is now fixed.

Runtime fix: renderValue is now only called with non-null values. When value is null, the placeholder is shown instead. Previously, renderValue would receive null at runtime despite being typed as (value: T) => ReactNode.

// Recommended pattern
<Select
  placeholder="Select..."
  value={value}
  onValueChange={setValue} // value is T | null (works with strictNullChecks)
  renderValue={(v) => v.name} // v is T (non-null), no defensive coding needed
/>

Fix sidebar collapsible content snapping shut instead of animating smoothly when closing.

fix(table): align sticky column colors with compact header variant

fix(tokens): correct text-kumo-subtle dark mode value to provide visible contrast

Updated the token value for kumo-line and kumo-hairline in dark mode so they are more visible.

• replace kumo-line usages with kumo-hairline across Kumo components and docs UI/content styles
• use ring-kumo-line for shadowed surfaces (for example combobox, dialog, select, dropdown, toast, and related surface wrappers)
• adjust theme token configuration and generated styles to support updated neutral/hairline appearance

fix(a11y): add accessible labels to icon-only controls

Add Enter key navigation to Pagination page number input and new pageSelector prop for dropdown mode

• The page number input in Pagination.Controls now navigates on Enter key press (previously only on blur)
• New pageSelector prop on Pagination.Controls: set to "dropdown" to render a Select dropdown instead of a text input for page selection

Add disabled option support, groups, group labels, and separators to Select

• Select.Option now accepts disabled and className props
• New Select.Group and Select.GroupLabel sub-components for organizing options under labeled headers
• New Select.Separator sub-component for visual dividers between groups
• The items object-map prop now accepts SelectItemDescriptor values with disabled metadata

Expose delay and closeDelay props on Tooltip component to control open and close timing. These props are forwarded to the underlying Base UI Trigger component.

Input and InputArea now automatically apply error styling when the error prop is truthy. You no longer need to set variant="error" separately - just pass an error message and the styling is applied automatically. The variant="error" prop is now deprecated but still works for backwards compatibility.

Adjust semantic tint usage for status/error ring styles across core form and feedback components.

• Update background styles in Badge and Banner components to use *-tint tokens.
• Update kumo-danger to a darker token to improve a11y contrast.
• Update error ring styling in form components to use semantic tokens (now darker with token swap).
• Removed text-color-badge-red-subtle token in replacement of the danger token.
• Update theme generator color mappings used by these tints to improve visual consistency.

Fix CodeBlock crash when an unsupported lang value is passed at runtime. The codeVariants() function now uses optional chaining with a nullish coalescing fallback to the default language, matching the defensive pattern already used by switchVariants() and badgeVariants().

fix(select): use ring-kumo-hairline token in Select popup (missed in PR #355)

Fix Select popup scrolling and height behavior; align popup/list structure with Base UI. Split popup into frame (Popup) and scroll container (List) to match Combobox pattern and fix touch scroll on long lists.

fix(loader): add ARIA attributes for screen reader accessibility

Added role="status" and aria-label="Loading" to the Loader SVG component to make it accessible to screen readers. This resolves a WCAG 2.1 SC 4.1.3 (Status Messages) violation where assistive technology users received no indication that content was loading.

Refine badge semantics/fill styling and banner tone updates

• Rework Badge variant model to prioritize semantic variants (primary, secondary, error, warning, success, info) with updated descriptions and primary as default.
• Keep token color variants for product-specific use cases while updating class mappings so semantic and token variants are distinct.
• Slight updates to token color variants to meet a11y contrast requirements.
• Update token color variants by replacing yellow with purple since yellow doesn't meet a11y contrast requirements, and keeping docs/demo examples in sync.
• Update badge docs demos/content to focus on primary semantic badges and a consolidated "other variants" section.
• Adjust banner variant surfaces (default, alert, error) to stronger tinted backgrounds and borders.
• Update theme generator badge/semantic token mappings and regenerate theme-kumo.css to match the new badge color system.

Fix Switch label click not toggling when a custom id prop is provided

The id was not being forwarded to Base UI's Switch.Root, causing a mismatch between the label's htmlFor and the button's actual id.

Align semantic token documentation and docs presentation updates.

• Update colors.mdx token documentation structure.
• Replaced kumo-ring with kumo-hairline for border/ring colors and all its instances in kumo components and docs.
• Sync packages/kumo/ai/USAGE.md token reference categories and descriptions with the docs token guide.
• Adjust the typo in the recessed dark token value in theme generator config and regenerate theme-kumo.css.
• Updated kumo-fill-hover token value from neutral-700 to neutral-800

Badge: add color-based variants and deprecate semantic variants

• Add color variants: red, orange, yellow, green, teal, blue, neutral, inverted
• Add subtle variants for each color (red-subtle, orange-subtle, etc.) with lighter backgrounds and darker text
• Retain outline and beta variants unchanged
• Deprecate primary (use inverted), secondary (use neutral), destructive (use red), success (use green)
• Dark mode support: subtle variants flip to dark backgrounds with light text, regular color variants darken slightly, inverted flips to white bg with black text
• Default variant changed from primary to neutral

Add action prop to Banner for rendering CTA buttons alongside structured title/description content without resorting to the children prop.

Refresh semantic surface color tokens and component surface usage.

• Add and adopt kumo-canvas as the page-level surface token in theme output and docs usage.
• Rebalance neutral token values in kumo-binding.css and generated theme variables for improved light/dark surface hierarchy.
• Update surface-related component styling (LayerCard, MenuBar, Tabs) to align with the refreshed canvas/elevated/recessed layering model.
• Update token usage guidance in ai/USAGE.md to reflect page vs component background roles.

Make timeseries' highlighted on hovering a data point

Add Shadow DOM support via KumoPortalProvider and container prop on all portal-based components

All overlay components (Dialog, DropdownMenu, Combobox, Select, Tooltip, Popover, CommandPalette, Toast) now support rendering inside Shadow DOM or custom containers.

New exports:

• KumoPortalProvider - Context provider to set default portal container for all overlays
• PortalContainer - Type for portal container (HTMLElement, ShadowRoot, or ref)

Component updates: All portal-based components now accept an optional container prop:

• Dialog - container prop on Dialog component
• DropdownMenu.Content - container prop
• Combobox.Content - container prop
• Select - container prop
• Tooltip - container prop
• Popover.Content - container prop
• CommandPalette.Root and CommandPalette.Dialog - container prop
• Toasty (Toast provider) - container prop

Usage:

Set once at the app level:

<KumoPortalProvider container={shadowRoot}>
  <App />
</KumoPortalProvider>

Or override per component:

<Dialog container={customContainer}>
  <Dialog.Title>Modal inside shadow DOM</Dialog.Title>
</Dialog>

When no provider or prop is set, components default to document.body (existing behavior).

SkeletonLine: add blockHeight prop to set a container height and vertically center the skeleton line within it

Table: add sticky prop to Table.Head and Table.Cell for pinning columns to left/right edges, and sticky prop to Table.Header for sticky header rows. Uses isolate stacking context with z-0/z-1/z-2 layering.

Add toml as a supported language for syntax highlighting in the Code component

Add title prop to Button — wraps the button in a Tooltip when provided.

Checkbox.Group & Radio.Group: remove fieldset border box and simplify styling

• Remove rounded-lg border border-kumo-line p-4 wrapper from both group fieldsets
• Downsize legend from text-lg to text-base with inline-flex layout
• Drop font-medium from Checkbox.Item and Radio.Item labels

Fix missing disabled styling on Combobox triggers. TriggerValue and TriggerMultipleWithInput now apply opacity-50 and cursor-not-allowed when disabled, matching the behaviour of the Select component.

Update dialog backdrop overlay to use bg-kumo-recessed token

Remove ai/schemas.ts from version control (now fully generated at build time)

Fix LayerCard.Primary stacking order when sandwiched between LayerCard.Secondary elements

Fix SensitiveInput focus ring and global CSS pollution

• Fix focus ring not showing on container when inner input is focused (focus-within:outline)
• Add defensive styles to eye toggle and copy buttons to prevent global CSS pollution
• Fix inputVariants parentFocusIndicator using wrong selector ([&:has(:focus-within)] → focus-within:)

SkeletonLine: move .skeleton-line styles into @layer base so Tailwind utility classes (e.g. className="h-6") can override the default height

Tabs indicator now uses translate-x for its transition animation, replacing the CSS left transition with a GPU-accelerated transform.

fix flow component not reflecting padding prop

Surface: replace as prop with Base UI render prop for polymorphism

The as prop used a hand-rolled generic forwardRef pattern (with as any casts) that conflicted with how the rest of the library handles polymorphism via Base UI's useRender hook.

Surface now accepts a render prop, consistent with Link and other components. The old as prop is kept as a deprecated alias and continues to work unchanged — no migration required.

// Still works (deprecated)
<Surface as="section">...</Surface>

// Preferred going forward
<Surface render={<section />}>...</Surface>

Switch: polish squircle styling

• Use ring-inset on thumb to prevent border protruding beyond the track
• Make thumb ring transparent to remove visible border outline
• Switch focus indicator from ring to outline with outline-offset-2 to avoid clashing with the track's own ring border

fix(Tabs): update segmented tab spacing and track styling

• Adjust segmented Tabs list styling colour to bg-kumo-recessed and added ring to make the Tabs background more visible
• Remove extra edge spacing and keep the segmented track/indicator alignment consistent

update toast styling to use a subtle ring and background that reflect each state.

update status text token values for info and danger to improve a11y contrast ratio on banners.

Add truncate prop to Text component. When true, applies truncate min-w-0 classes to clip overflowing text with an ellipsis.

Make Chart components keyboard focusable with tabindex. Timeseries adds ariaDescription prop

Generate component-registry files at build time, remove from git

Eliminates contributor friction by generating component-registry.json, component-registry.md, and schemas.ts during the build process instead of tracking them in git. Contributors will no longer see stale diffs or need to manually regenerate these files.

• Add ai/component-registry.json and ai/component-registry.md to .gitignore
• Convert ai/schemas.ts to a stub file for TypeScript compilation
• Add codegen:registry to build script for deterministic generation

feat(code): add HCL (HashiCorp Configuration Language) as a supported syntax highlighting language

fix(flow): connector lines no longer misalign when the page scrolls or a sidebar shifts the layout

getBoundingClientRect values were stored in React state per node and later subtracted against a freshly-read container rect at connector-draw time. Any layout shift (sidebar open/close, page scroll, inner container scroll) between those two reads produced stale coordinates, causing connector lines to jump out of place or disappear entirely.

Fix: add scroll and resize listeners (capture phase) at the FlowNode, FlowParallelNode, and FlowNodeList levels so all rects are remeasured after any layout shift. Connector computation in FlowNodeList and FlowParallelNode is also moved from the render phase into useLayoutEffect so the container rect and node rects are always read in the same synchronous pass.

Add missing HCL language import to server-side Shiki bundle

The HCL language was added to SupportedLanguage type and the client-side provider in a previous commit, but the server.tsx BUNDLED_LANGS object was missed. This caused typecheck failures when building.

Sidebar: polish animations, fix separator reflow bug, improve header spacing

Fix connector alignment and spacing between adjacent parallel nodes in Flow diagrams

Add success and info toast variants with semantic token styling. Migrate error/warning variants from raw CSS to semantic tokens for consistent theming.

Fix Radio compound component to use Object.assign pattern, enabling sub-component detection (Radio.Group, Radio.Item) in the component registry.

Revert outline button variant ring width from ring-2 (2px) back to ring (1px) to restore visual consistency with existing dashboard usage.

fix: update styling for mostly-used components with new greyscale tokens (combobox, dialog, input, layerCard, select & tabs) as well as homegrid and component preview backgrounds.

Remove es2022 build target that caused Jest/babel-jest test failures in stratus

Add radio card appearance via appearance="card" prop on Radio.Group and Radio.Item. Cards display a bordered, selectable container with title and description. Also adds description prop to Radio.Item for helper text. Supports vertical and horizontal orientations, error state, and disabled state.

Expose Chart optionUpdateBehavior to control how ECharts applies option updates; notMerge now defaults to false.

Add neutral variant to Switch component and improve accessibility

• New variant="neutral" option: monochrome switch with squircle shape, matching the design from stratus
• Improved off-state visibility for default variant with darker background/ring colors
• Removed error variant (not useful for toggle switches)
• Added defensive fallback so invalid variant values don't cause runtime crashes

removed outline-none to bring back focus states on all buttons

Fix flaky vitest "Closing rpc while fetch was pending" error in deep-imports test

Fix InputArea label click not focusing textarea. Use FieldBase.Control with render callback to properly associate the label with the textarea element.

Fix TypeScript return types for ShikiProvider and CodeHighlighted components.

Changed return type from ReactNode to React.JSX.Element to resolve JSX compatibility errors. This fixes issues when consuming these components in projects with stricter TypeScript configurations (e.g., skipLibCheck: false), where ReactNode was incorrectly inferred as a valid JSX element return type.

Fix table header font size to ensure consistent rendering across dashboards with different default font sizes

Add dedicated kumo-placeholder text color token and use it for Input, InputArea, SensitiveInput, and CommandPalette placeholder text. The new token provides better visual distinction between placeholder and active text in both light and dark modes.

Replace the package-level ESLint pass with Oxlint JS plugin coverage for the remaining jsx-a11y rules, and pin the library build to es2022 with a post-build browser-compat test that blocks newer runtime APIs from shipping in dist.

fix(Select): prevent chevron overflow with long multi-select values

Added min-w-0 truncate to the value element and shrink-0 to the chevron icon so that long option names truncate gracefully instead of pushing the chevron outside the select bounds.

Fix combobox caret icon to use text-kumo-subtle with fill-current instead of invalid fill-kumo-subtle token

fix TimeseriesChart brush cursor not activating when loading prop transitions from true to false

add xAxisTickFormat, yAxisTickFormat, and tooltipValueFormat props to TimeseriesChart; deprecate yAxisTickLabelFormat

Deprecation: yAxisTickLabelFormat is deprecated

If you were using yAxisTickLabelFormat to customize tooltip output, switch to tooltipValueFormat.

Before:

<TimeseriesChart yAxisTickLabelFormat={(v) => `${v} req/s`} />

After:

<TimeseriesChart tooltipValueFormat={(v) => `${v} req/s`} />