feat(breadcrumbs): add items-based API with overflow support

[mattrothenberg]

Summary

Adds a new items-based API to the Breadcrumbs component with automatic overflow support:

• New items prop accepts an array of BreadcrumbItem objects for declarative breadcrumb definition
• New currentItem prop for the current page item
• Automatic overflow detection collapses items that don't fit into a dropdown menu
• Tree visualization in overflow menu shows breadcrumb hierarchy with L-shaped SVG connectors
• Support for custom router links via render prop on items
• Loading state support on current item
• Exported new types: BreadcrumbItem, BreadcrumbsItemsProps, BreadcrumbsCombinedProps

Screen.Recording.2026-04-10.at.12.27.20.PM.mov

Usage

import { Breadcrumbs, type BreadcrumbItem } from "@cloudflare/kumo";

const items: BreadcrumbItem[] = [
  { label: "Home", href: "/" },
  { label: "Projects", href: "/projects" },
  { label: "Settings", href: "/projects/settings" },
];

<Breadcrumbs 
  items={items} 
  currentItem={{ label: "General" }} 
/>

Backward Compatibility

The existing compound component API continues to work unchanged:

<Breadcrumbs>
  <Breadcrumbs.Link href="/">Home</Breadcrumbs.Link>
  <Breadcrumbs.Separator />
  <Breadcrumbs.Current>Current Page</Breadcrumbs.Current>
</Breadcrumbs>

Demo

The demo page includes an interactive example with a width slider to test overflow behavior.

Checklist

• Tests included/updated
• bonk has reviewed the change

[pkg-pr-new]

npm i https://pkg.pr.new/@cloudflare/kumo@389

commit: 24fea1c

[github-actions]

Docs Preview

View docs preview

Commit: 39702a1

[mattrothenberg]

/bonk check my work. this is a big change

[github-actions]

Visual Regression Report — 26 changed, 11 unchanged

26 screenshot(s) with visual changes:

Button / Basic

90 px (0.09%) changed

Before	After	Diff

Button / Variant: Primary

370 px (0.36%) changed

Before	After	Diff

Button / Variant: Ghost

101 px (0.1%) changed

Before	After	Diff

Button / Variant: Outline

82 px (0.08%) changed

Before	After	Diff

Button / Variant: Secondary Destructive

383 px (0.38%) changed

Before	After	Diff

Button / Icon Only

68 px (0.07%) changed

Before	After	Diff

Button / Loading State

1 px (0%) changed

Before	After	Diff

Button / Disabled State

182 px (0.18%) changed

Before	After	Diff

Dialog / Dialog With Actions

191 px (0.19%) changed

Before	After	Diff

Dialog / Dialog Alert

1,427 px (1.41%) changed

Before	After	Diff

Dialog / Dialog Confirmation

352 px (0.35%) changed

Before	After	Diff

Dialog / Dialog With Combobox

225 px (0.22%) changed

Before	After	Diff

Dialog / Dialog With Dropdown

130 px (0.13%) changed

Before	After	Diff

Dialog (Open)

0 px (0%) changed

Before	After	Diff

Select / Select Basic

486 px (0.48%) changed

Before	After	Diff

Select / Select Sizes

599 px (0.32%) changed

Before	After	Diff

Select / Select With Field

0 px (0%) changed

Before	After	Diff

Select / Select Placeholder

672 px (0.66%) changed

Before	After	Diff

Select / Select Custom Rendering

576 px (0.57%) changed

Before	After	Diff

Select / Select Loading

2,168 px (1.01%) changed

Before	After	Diff

Select / Select Multiple

801 px (0.79%) changed

Before	After	Diff

Select / Select Complex

1,093 px (0.92%) changed

Before	After	Diff

Select / Select Disabled Options

508 px (0.5%) changed

Before	After	Diff

Select / Select Grouped With Disabled

753 px (0.74%) changed

Before	After	Diff

Select / Select Long List

1,428 px (1.21%) changed

Before	After	Diff

Select (Open)

0 px (0%) changed

Before	After	Diff

11 screenshot(s) unchanged

• Button / Variant: Secondary
• Button / Variant: Destructive
• Button / Sizes
• Button / With Icon
• Button / Title
• Dialog / Dialog Basic
• Dialog / Dialog With Select
• Select / Select Without Label
• Select / Select With Tooltip
• Select / Select Disabled Items
• Select / Select Grouped

---

Generated by Kumo Visual Regression

[ask-bonk]

Review of PR #389: Breadcrumbs Items-based API with Overflow Support

Summary

This is an excellent feature addition that brings a powerful items-based API to the Breadcrumbs component with automatic overflow handling. The implementation is solid and follows Kumo conventions well.

What I Like

1. Clean dual API design: The discriminated union approach with hasItemsProps() makes the API elegant - users can use either the compound component or items-based API seamlessly.

2. Smart overflow calculation: The resize observer-based approach with cached measurements is performant. The logic to preserve parent context by measuring from the end is thoughtful.

3. Tree visualization: The L-shaped SVG connectors in the overflow dropdown are a nice UX touch that helps users understand the breadcrumb hierarchy.

4. Excellent backward compatibility: The existing compound component API works unchanged - this is exactly how API evolution should work.

5. Good test coverage: 7 tests covering both APIs, icons, and aria attributes.

6. Proper type exports: All new types are exported properly through both the breadcrumbs index and main index.

Minor Issues

1. Missing displayName: The component uses Breadcrumb as the function name but exports as Breadcrumbs. According to Kumo conventions, it should have a displayName set for React DevTools:

   Breadcrumb.displayName = "Breadcrumbs";

2. JSDoc comments: While the component has good JSDoc at the top level, the compound component sub-components (Link, Current, Separator, Clipboard) don't have displayName set with dot notation like other compound components in the codebase.

3. Changeset: ✅ The changeset is properly marked as minor and describes the changes well.

Code Quality

• ✅ Uses semantic tokens correctly (text-kumo-subtle, bg-kumo-control, etc.)
• ✅ No dark: variants (follows Kumo convention)
• ✅ Uses cn() utility for class merging
• ✅ Proper aria attributes (aria-label, aria-current="page")
• ✅ No cross-package relative imports
• ✅ Properly typed props with JSDoc

Testing

• ✅ All 7 tests pass
• ✅ Typecheck passes (0 errors)
• ✅ Tests cover both APIs

Suggestion

Add the displayName for better React DevTools support:

// At the end of breadcrumbs.tsx
Breadcrumb.Link = Link;
Breadcrumb.Current = Current;
Breadcrumb.Separator = Separator;
Breadcrumb.Clipboard = Clipboard;
+Breadcrumb.displayName = "Breadcrumbs";

Conclusion

This is a well-implemented feature that significantly enhances the Breadcrumbs component. The API design is thoughtful, the implementation is clean, and backward compatibility is preserved. The minor displayName addition would be nice but isn't blocking.

LGTM 👍 - approved with optional displayName addition.

github run