Add passwordManagerIgnore to Input for suppressing password manager overlays on non-credential fields.

Add scroll fade to segmented tabs. When tabs overflow, gradient masks appear on the edges based on scroll position via scroll-driven animations (Chrome 115+, degrades gracefully). Scrollbar is hidden; the fade is the scroll affordance.

Add size="sm" variant to Tabs component (h-6.5 / 26px, matching Input sm)

Forward toastManager prop on <Toasty> so code outside the React tree (timers, query-cache listeners, module-load callbacks) can dispatch toasts via a manager created by createKumoToastManager(). Also surface createKumoToastManager on the top-level package export (previously only available via the deep @cloudflare/kumo/components/toast path).

Add transparent background to SankeyChart component

Expose optionUpdateBehavior prop on TimeseriesChart to control how ECharts applies option updates

Add hideLabel prop to Field so components can skip the native <label> while keeping description/error wiring. Use it in Select with Base UI's Select.Label to fix hover/focus coupling between the label text and trigger.

fix(input): render error and description props without requiring a label

fix(radio): prevent radio button distortion with long labels by adding shrink-0 to the default appearance radio indicator

Fix overflowing segmented Tabs drag-to-scroll interactions so mouse and touch drags reliably scroll while normal tab clicks still activate tabs.

Create Sankey Chart component

Fix CommandPalette List bottom ring being clipped by Footer background. Add scroll padding to prevent items from clipping behind rounded corners.

Deprecate to prop on Link in favor of href. The to prop is a routing-framework concept that doesn't belong on a presentational component. Use href for all link destinations and configure a LinkProvider wrapper to bridge to your router. to continues to work but emits a dev-mode deprecation warning.

Allow LayerCard.Primary and LayerCard.Secondary to accept all standard HTML div attributes, including data-testid for testing.

Set cursor-default on Tooltip triggers so disclosure buttons don't appear clickable. Overridable via className.

Export Combobox.Trigger, Combobox.Value, and Combobox.Icon — the raw Base UI primitives for building custom combobox triggers. Use these when you need full control over the trigger's visual treatment (e.g. a sidebar account switcher that renders as a plain button instead of an input-like control).

fix(CloudflareLogo): remove registered trademark symbol from full logo variant

Fix Google Translate DOM mutation crash in Button

Remove z-50 from mobile Sidebar Dialog backdrop and panel. The z-50 caused portaled floating elements (Popover, DropdownMenu, Select, Combobox) opened from inside the Sidebar to render behind the Dialog backdrop. Matches the pattern used by Kumo's own Dialog component, which relies on DOM order for stacking with no explicit z-index. Also adds data-sidebar-backdrop and data-sidebar-popup attributes as stable CSS hooks.

fix(combobox): forward all props from TriggerValue to ComboboxBase.Value, enabling placeholder support and styled placeholder text via data-[placeholder]:text-kumo-placeholder

fix(registry): correct Select component metadata for AI-generated code

The component registry metadata was incorrectly typing Select's value, defaultValue, and onValueChange props as string, causing AI agents to produce broken code when implementing Select with object values (e.g., rendering object.value in the trigger instead of the label).

Changes:

• value type: string → T (generic, matches actual component interface)
• defaultValue type: string → T
• onValueChange type: (value: string) => void → (value: T) => void
• Added missing renderValue prop: (value: T) => ReactNode — required for object values
• Added missing items prop: supports both Record<string, string> and Array<{ label, value }> forms
• Added missing isItemEqualToValue prop: required for object equality comparison

Gracefully fall back to default variant instead of crashing when an invalid variant prop is passed at runtime. Previously 22 of 25 components would throw TypeError on unknown variant values; all 25 now use a shared resolveVariant() utility that returns the default config and logs a dev warning.

Forward all Base UI Panel props (including keepMounted and hiddenUntilFound) through Collapsible.DefaultPanel. Previously these were silently dropped because DefaultPanel used a standalone props interface instead of extending BasePanelProps.

Fix registry codegen to match demo examples when component export name differs from directory name (e.g. DropdownMenu vs dropdown). This restores missing examples for DropdownMenu and other affected components.

TooltipProvider props (delay, closeDelay, timeout) are now shown in the Tooltip component's API Reference on the docs site.

Rebalanced semantic text token usage to improve hierarchy and consistency across components, docs, and generated Figma output.

• Updated theme token definitions so text-kumo-strong represents high-emphasis text and text-kumo-inactive is lighter/inactive in both light and dark modes.
• Migrated affected UI surfaces from text-kumo-strong to text-kumo-subtle where content is supportive metadata, labels, or secondary text.
• Synced token usage in docs and Figma code generators with the updated semantic text mapping.

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".

BREAKING (v2): Text requires an explicit as prop when variant is a heading ("heading1", "heading2", "heading3").

The previous major bump (#393) decoupled heading variants from semantic HTML — heading variants render as <span> unless an as prop is provided. That made the library more flexible but introduced a silent accessibility footgun: forgetting as on a real section heading produced a <span>, excluding it from the document outline without any type-level feedback.

This change makes as required for heading variants via a discriminated union. Body and monospace variants are unchanged (as remains optional; defaults to <p> and <span> respectively).

Migration

Every <Text variant="heading1">, <Text variant="heading2">, <Text variant="heading3"> must now pass as. TypeScript will flag each call site:

// Before (compiled, silently produced a <span>)
<Text variant="heading1">Page Title</Text>

// After (required)
<Text variant="heading1" as="h1">Page Title</Text>

// Still allowed — decorative heading-styled text that is NOT a section heading:
<Text variant="heading1" as="span">Big bold card label</Text>

For each heading call site, decide whether it's a real section heading (use as="h1"/"h2"/etc.) or decorative (use as="span"). Codemod cannot make this choice mechanically — it is a semantic judgment per usage.

Body and monospace variants: no changes required.

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

feat(table): add onCheckedChange prop to Table.CheckCell and Table.CheckHead, aligning with the Checkbox component's signature.

The new prop exposes an optional second argument with event details, matching Base UI's idiom:

<Table.CheckCell
  checked={selected.has(row.id)}
  onCheckedChange={(checked, eventDetails) => {
    toggle(row.id);
    eventDetails?.event.stopPropagation();
  }}
/>

The existing onValueChange prop still works but is now deprecated and flagged by the no-deprecated-props lint rule. It will be removed in a future major version. Migrate by renaming the prop — the single-argument callback shape is preserved.

This change is additive and does not require consumer code changes at this time.

Expand Text component's as prop to accept additional HTML text elements: label, dt, dd, li, figcaption, legend, pre, code, em, strong, small, abbr, and time. This unblocks downstream usage in Stratus where Text needs to render as definition list terms, labels, and code elements.

Remove invalid hover border utility from secondary button variants to keep hover styling consistent and avoid unintended class output.

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

Combobox.Item now renders a visible disabled state when the disabled prop is set. Previously the prop was forwarded to Base UI (so click/keyboard selection were correctly blocked) but the row looked identical to an enabled one. Adds data-[disabled]:* Tailwind classes for muted text, cursor-not-allowed, reduced opacity, and suppresses the highlight background on disabled rows during keyboard navigation. Also fixes className passthrough — user-supplied classes are now merged via cn() instead of being overridden.

Improve focus ring consistency and clipping behavior across inputs and related controls.

• Move the command palette focus ring to the input header container with focus-within and remove duplicate input-level ring styles.
• Update Select trigger and option focus styles to use inset focus rings to prevent clipping in rounded/overflow contexts.
• Fix clipboard copy button focus ring clipping by using inset focus-visible ring, matching border-radius inheritance, and isolated stacking.
• Align InputGroup and InputGroup.Button focus ring color to ring-kumo-focus, including hybrid container-zone focus ring classes.
• Update InputGroup tests to match inline focus ring class changes.
• Set DatePicker (react-day-picker) focus ring token to var(--color-kumo-brand).
• Update InputGroup container and hybrid keyboard outlines in kumo-binding.css to use var(--color-kumo-focus) at 1px weight.

Allow CommandPalette.Input to accept standard HTML input attributes (autoComplete, autoCorrect, autoCapitalize, spellCheck, data-*, etc.) by extending its props type with InputHTMLAttributes<HTMLInputElement>. Export new CommandPaletteInputProps type.

Fix InputGroup hover state incorrectly propagating to the first child button (e.g. in Pagination.Controls). Root now renders as <div> instead of <label> when it contains multiple labelable controls.

Fix Table body cells rendering at 16px. The Table root now sets text-base (14px) so <td> cells match Kumo's default body font-size instead of inheriting the browser default. Also replaces an arbitrary text-[14px] in Empty with text-base.

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.

Fix InputGroup container className to enforce mb-0, ensuring all container variants (not just the standalone <label> mode) reset inherited bottom margin.

Fix InputGroup label wrappers to enforce mb-0, preventing inherited label margins from shifting layout and click-target overlays.

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