Fix language alias normalization in ShikiProvider

• Add normalizeLanguage() function that maps common language aliases (js, ts, sh, yml, py, md, gql) to their canonical SupportedLanguage names
• Normalize language aliases in ShikiProvider when preloading grammars, so passing ['js', 'ts'] works the same as ['javascript', 'typescript']
• Normalize language aliases in highlight() hook at runtime, so code fences using js or ts highlight correctly without warnings
• Export normalizeLanguage from @cloudflare/kumo/code for consumers who need to normalize aliases themselves
• Intentionally omit mdx alias since MDX has a distinct grammar that would lose JSX highlighting if mapped to markdown

fix(banner): remove variant selection background for legibility

Selected text inside Banner now uses the browser default selection color instead of a same-hue variant-tinted background. The previous selection:bg-kumo-{info,warning,danger} utilities produced low contrast between the selection background and the variant text color (most notably in light mode for the error and alert variants), making selected text hard to read.

Add left and right props to SankeyChart for controlling series layout padding

Fix tooltip popup exit transitions by animating the Tailwind scale property alongside opacity.

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.