feat: 🎸 Add Breadcrumbs component

[elizabetdev]

Summary

Breadcrumbs navigation component that displays the user's current location within a hierarchy, allowing quick navigation to parent pages. Supports icons, auto-collapsing middle items into an ellipsis dropdown, and active page indication.

Component name: Breadcrumbs
Type: New Component

Motivation

Why is this component needed, or why does the existing one need to change?

• Problem / gap in the current library: No breadcrumb navigation component exists in click-ui. Consumers need to build their own or use unstyled third-party solutions.
• User or product need it addresses: Multiple product surfaces (e.g., Data Sources, ClickPipes) require hierarchical navigation to help users orient themselves within deeply nested pages.

Design reference

• Figma link provided: Figma frame
• Design reviewed and approved by the design team
• All component states are covered in the design (default, hover, active, focus, disabled, error, loading)

Proposed API

Show the intended public API with usage examples.

Basic usage — all items visible

Separators are auto-inserted between items.

<Breadcrumbs>
  <BreadcrumbItem icon="home" href="/data-sources">
    Data sources
  </BreadcrumbItem>
  <BreadcrumbItem href="/clickpipes">ClickPipes</BreadcrumbItem>
  <BreadcrumbItem href="/lorem">Lorem</BreadcrumbItem>
  <BreadcrumbItem active>
    GCS Unordered mode with service account
  </BreadcrumbItem>
</Breadcrumbs>

Collapsed — middle items hidden behind ellipsis dropdown

When maxItems is set and the item count exceeds it, middle items collapse into a ... button. Clicking the ellipsis opens a popover dropdown listing the hidden items.

<Breadcrumbs maxItems={2}>
  <BreadcrumbItem icon="home" href="/data-sources">
    Data sources
  </BreadcrumbItem>
  <BreadcrumbItem href="/clickpipes">ClickPipes</BreadcrumbItem>
  <BreadcrumbItem href="/lorem">Lorem</BreadcrumbItem>
  <BreadcrumbItem active>
    GCS Unordered mode with service account
  </BreadcrumbItem>
</Breadcrumbs>
{/* Renders: [🏠 Data sources] > [...] > [GCS Unordered mode] */}
{/* Clicking "..." shows dropdown: ClickPipes, Lorem */}

Fine-grained collapse control

<Breadcrumbs maxItems={4} itemsBeforeCollapse={2} itemsAfterCollapse={1}>
  <BreadcrumbItem icon="home" href="/">Home</BreadcrumbItem>
  <BreadcrumbItem href="/data-sources">Data sources</BreadcrumbItem>
  <BreadcrumbItem href="/clickpipes">ClickPipes</BreadcrumbItem>
  <BreadcrumbItem href="/lorem">Lorem</BreadcrumbItem>
  <BreadcrumbItem href="/ipsum">Ipsum</BreadcrumbItem>
  <BreadcrumbItem active>GCS Unordered mode</BreadcrumbItem>
</Breadcrumbs>
{/* Renders: [Home] > [Data sources] > [...] > [GCS Unordered mode] */}
{/* Dropdown: ClickPipes, Lorem, Ipsum */}

Responsive usage

The consumer handles responsive behavior externally:

const isMobile = useMediaQuery('(max-width: 768px)');

<Breadcrumbs maxItems={isMobile ? 2 : undefined}>
  {/* items */}
</Breadcrumbs>

Props

BreadcrumbsProps

Prop	Type	Default	Description
children	ReactNode	—	BreadcrumbItem elements
maxItems	number	undefined	Max visible items before collapsing. When undefined, all items are shown
itemsBeforeCollapse	number	1	Number of items to always show before the ellipsis
itemsAfterCollapse	number	1	Number of items to always show after the ellipsis
separator	ReactNode	<Icon name="chevron-right" />	Custom separator element

BreadcrumbItemProps

Prop	Type	Default	Description
children	ReactNode	—	The text label of the breadcrumb
icon	IconName	undefined	Optional icon displayed before the label
active	boolean	false	Whether this is the current/active page
href	string	undefined	When provided, the item renders as a link

Collapse behavior

Children count	maxItems	itemsBeforeCollapse	itemsAfterCollapse	Result
4	undefined	—	—	All 4 shown, no ellipsis
4	2	1	1	1st + ... + last
6	4	2	1	1st, 2nd + ... + last
2	2	1	1	All shown (count ≤ maxItems)

• Props are consistent with existing component conventions in click-ui
• Component supports className and ref forwarding
• Default prop values are documented

Variants & states

List the variants and states the component should support:

• Variants defined: link item (muted text, clickable), active item (default text, non-clickable), collapsed ellipsis (with dropdown)
• Sizes defined — N/A (single size, follows docs.typography.breadcrumbs tokens)
• States handled: default, hover (underline on link items), active (current page)
• Error / validation state — N/A
• Loading state — N/A

Accessibility

• Correct semantic HTML elements used (<nav>, <ol>, <li>, <a>)
• ARIA attributes added where needed (aria-label="Breadcrumb", aria-current="page" on active item)
• Keyboard navigation works (Tab through links, Enter to activate)
• Screen reader tested or reviewed
• Focus management is correct (focus ring visible on links)
• Color contrast meets WCAG AA (4.5:1 text, 3:1 UI)

Theming

• Component works with the light theme
• Component works with the dark theme
• Uses design tokens from src/theme/tokens (no hardcoded colors, spacing, or font sizes)
  • theme.click.docs.typography.breadcrumbs.default — link items
  • theme.click.docs.typography.breadcrumbs.active — current page item
  • theme.click.global.color.text.muted — link item color
  • theme.click.global.color.text.default — active item color
  • theme.click.genericMenu.* — ellipsis dropdown styling

Implementation checklist

• Component file created: src/components/Breadcrumbs/Breadcrumbs.tsx
• Exports added to src/components/index.ts
• Styled with styled-components using theme tokens
• TypeScript types/interfaces exported
• No any types used

Testing

• Unit tests added: Breadcrumbs.test.tsx
• All variants and states have test coverage
• Accessibility checks included in tests (e.g., toHaveAccessibleName)
• Edge cases covered (empty state, overflow, long text, etc.)
• Storybook story added: Breadcrumbs.stories.tsx
• Visual regression covered (Chromatic snapshot via Storybook)

Documentation

• Storybook story includes all variants, sizes, and states
• Props table is auto-generated or manually documented in the story
• Usage guidelines / do's and don'ts added (if applicable)

Changeset

• yarn changeset:add has been run and the changeset file is included
• Change type is correct (minor for new components, patch for changes/fixes)

Security checklist

• All user inputs are validated and sanitized
• No usage of dangerouslySetInnerHTML
• Sensitive data has been identified and is being protected properly
• Build output contains no secrets or API keys

Rollout & migration (for component changes only)

Skip this section for brand-new components.

N/A — new component.

Open questions

List any unresolved decisions or areas where you'd like reviewer feedback.

1. Should BreadcrumbItem accept an as prop (e.g., for React Router Link integration)?
2. Should the ellipsis dropdown use the existing Popover or a custom implementation?
3. Should maxItems support a responsive object like { sm: 2, md: 4 }?

Preview

Link to a deployed Storybook preview or attach screenshots.

Storybook preview will be available once CI deploys.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 1f224f4

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[workflow-authentication-public]

📚 Storybook Preview Deployed

✅ Preview URL: https://click-l7f6c1h0i-clickhouse.vercel.app

Built from commit: b9f97581f1abdc3b55764db76834992a0baacd68

[punkbit]

@elizabetdev mind include a changeset? Add a short description explaining how to use the component.

Ref:
https://github.com/ClickHouse/click-ui?tab=readme-ov-file#add-a-new-changeset