Breadcrumbs are a secondary navigation pattern that helps users understand their current location within a website or application hierarchy. They provide a clear path back to higher-level pages and improve overall navigation experience by showing the relationship between pages.
✅ Use breadcrumbs when:
- Your site or application has a deep hierarchical structure (3+ levels)
- Users need to understand their current location in the site structure
- You want to provide an easy way to navigate back to parent pages
- Working with multi-step processes or workflows
- Displaying content categorization (e.g., Products > Electronics > Smartphones)
- Building e-commerce product pages or content management systems
❌ Don't use breadcrumbs for:
- Single-level navigation (use primary navigation instead)
- Linear processes where users shouldn't skip steps
- Mobile-first designs where space is extremely limited
- Sites with flat information architecture
- When the primary navigation already provides clear hierarchy
A standard breadcrumb showing the page hierarchy with clickable links:
Customize the visual separator between breadcrumb items using the separator slot:
Use the mobile attribute to show only the first and last items on smaller screens:
Use the variant="inverted" attribute for breadcrumbs on dark backgrounds:
Breadcrumbs are designed with accessibility in mind:
- Semantic HTML: Uses proper
<nav>and<ol>structure for screen readers - ARIA labeling: Supports
aria-labelandaria-labelledbyattributes - Current page indication: Automatically adds
aria-current="page"to the last item - Keyboard navigation: Full keyboard support using Tab navigation
- Screen reader friendly: Proper list semantics and separator handling
<!-- Always provide an accessible name -->
<dap-ds-breadcrumb aria-label="You are here">
<!-- Or use aria-labelledby -->
<dap-ds-breadcrumb aria-labelledby="page-title">
<!-- Use descriptive link text -->
<dap-ds-breadcrumb-item href="/products">
All Products <!-- Instead of "Products" or "Back" -->
</dap-ds-breadcrumb-item>
Breadcrumbs automatically adapt to different screen sizes:
- Desktop: Shows full breadcrumb trail
- Mobile with
mobileattribute: Shows only first and last items - Mobile without
mobile: Allows horizontal scrolling
Design your URLs to support breadcrumb navigation:
// Good URL structure for breadcrumbs
/products/electronics/smartphones/iphone-15-pro
// Breadcrumb can be automatically generated from URL segments
Home > Products > Electronics > Smartphones > iPhone 15 Pro
// Example: Building breadcrumbs from route data
const routeSegments = [
{ name: 'Home', href: '/' },
{ name: 'Products', href: '/products' },
{ name: 'Electronics', href: '/products/electronics' },
{ name: 'Smartphones' } // Current page, no href
];
const breadcrumbHTML = html`
<dap-ds-breadcrumb aria-label="Page navigation">
${routeSegments.map(segment => html`
<dap-ds-breadcrumb-item href="${segment.href || nothing}">
${segment.name}
</dap-ds-breadcrumb-item>
`)}
</dap-ds-breadcrumb>
`;
- Keep breadcrumb trails reasonably short (5-7 levels maximum)
- Use semantic URLs that match the breadcrumb structure
- Consider implementing breadcrumb caching for complex hierarchies
- Avoid overly long breadcrumb item names that may wrap
The breadcrumb component supports extensive customization beyond the default appearance. This section demonstrates practical styling techniques and advanced customization patterns.
For simple customizations, use CSS custom properties directly on the component:
Experiment with custom breadcrumb styling using CSS parts and custom properties. The breadcrumb component exposes several CSS parts for advanced styling: base, item, link, separator, and label. Try the presets below or create your own styles:
Home
Products
Electronics
Smartphones
import { DapDSBreadcrumb } from 'dap-design-system'
import { DapDSBreadcrumbReact } from 'dap-design-system/react'
For optimal bundle sizes, use the tree-shakeable import syntax:
import { DapDSBreadcrumb } from 'dap-design-system/components'
| Property | Type | Default | Description |
|---|---|---|---|
variant | string | 'normal' | |
mobile | boolean | false | Mobile version of the breadcrumb |
ariaLabelledBy | string, undefined | The aria-labelledby of the breadcrumb |
| Name | Description |
|---|---|
(default) | The content of the breadcrumb. |
separator | The separator between breadcrumb items. Default is '/'. |
No custom events available.
| Part Name | Description |
|---|---|
base | The main breadcrumb container. |
separator | The separator of the breadcrumb. |
You can style CSS parts using the ::part() pseudo-element selector:
/* Target a specific part */
.my-custom-dap-ds-breadcrumb::part(base) {
/* Your custom styles */
}
/* Target multiple parts */
.my-custom-dap-ds-breadcrumb::part(base),
.my-custom-dap-ds-breadcrumb::part(separator) {
/* Shared styles */
}
Example usage:
<dap-ds-breadcrumb class="my-custom-dap-ds-breadcrumb">
Breadcrumb
</dap-ds-breadcrumb>
.my-custom-dap-ds-breadcrumb::part(base) {
border-radius: 12px;
box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
}
CSS parts allow you to style internal elements of the component while maintaining encapsulation. Learn more in our styling guide.
| Property Name | Description |
|---|---|
--dds-breadcrumb-width | The width of the breadcrumb container (default: 100%) |
--dds-breadcrumb-overflow-x | The horizontal overflow behavior of the breadcrumb (default: auto) |
--dds-breadcrumb-transition | The transition property for the breadcrumb (default: all 0.2s ease-in-out) |
--dds-breadcrumb-list-display | The display property of the breadcrumb list (default: flex) |
--dds-breadcrumb-list-flex-wrap | The flex-wrap property of the breadcrumb list (default: nowrap) |
--dds-breadcrumb-list-align-items | The align-items property of the breadcrumb list (default: center) |
--dds-breadcrumb-list-min-width | The minimum width of the breadcrumb list (default: max-content) |
CSS custom properties (CSS variables) can be set directly on the component or in your stylesheet:
Method 1: Inline styles (Quick customization)
<dap-ds-breadcrumb
style="--dds-breadcrumb-width: value; --dds-breadcrumb-overflow-x: value;">
Breadcrumb
</dap-ds-breadcrumb>
Method 2: CSS classes (Reusable styles)
.my-custom-dap-ds-breadcrumb {
--dds-breadcrumb-width: value;
--dds-breadcrumb-overflow-x: value;
--dds-breadcrumb-transition: value;
}
<dap-ds-breadcrumb class="my-custom-dap-ds-breadcrumb">
Breadcrumb
</dap-ds-breadcrumb>
Method 3: Global theme customization
/* Apply to all instances */
dap-ds-breadcrumb {
--dds-breadcrumb-width: value;
--dds-breadcrumb-overflow-x: value;
}
CSS custom properties inherit through the Shadow DOM, making them perfect for theming. Changes apply immediately without rebuilding.
| Property | Type | Default | Description |
|---|---|---|---|
href | string, undefined | The URL of the breadcrumb item. | |
target | '_blank', '_self' , '_parent' , '_top' | The target of the breadcrumb item. | |
rel | string | 'noreferrer noopener' | The rel of the breadcrumb item link. |
disabled | boolean | false | Whether the breadcrumb item is disabled. |
variant | 'normal', 'inverted' | 'normal' | The variant of the breadcrumb item. |
| Name | Description |
|---|---|
(default) | The content of the breadcrumb item. |
separator | The separator between breadcrumb items. Default is an arrow-right-s-line icon. |
No custom events available.
| Part Name | Description |
|---|---|
base | The main breadcrumb item container. The li element. |
link | The link of the breadcrumb item. The dds-link component. |
link-base | The base part of the link part. The dds-link components base part. |
item-nolink | The item of the breadcrumb item without a link. The span element. |
separator | The separator of the breadcrumb item. |
| Property Name | Description |
|---|---|
--dds-breadcrumb-item-display | The display property of the breadcrumb item (default: inline-flex) |
--dds-breadcrumb-item-flex-wrap | The flex-wrap property of the breadcrumb item (default: nowrap) |
--dds-breadcrumb-item-align-items | The align-items property of the breadcrumb item (default: center) |
--dds-breadcrumb-item-color | The text color of the breadcrumb item (default: var(--dds-text-neutral-base)) |
--dds-breadcrumb-item-transition | The transition property for the breadcrumb item (default: all 0.2s ease-in-out) |
--dds-breadcrumb-item-gap | The gap between the breadcrumb item and the separator (default: var(--dds-spacing-200)) |
--dds-breadcrumb-item-padding | The padding of the breadcrumb item (default: var(--dds-spacing-200)) |
--dds-breadcrumb-item-font-size | The font size of the breadcrumb item (default: var(--dds-font-sm)) |
--dds-breadcrumb-item-font-weight | The font weight of the breadcrumb item (default: var(--dds-font-weight-medium)) |
--dds-breadcrumb-item-font-weight-bold | The bold font weight of the breadcrumb item (default: var(--dds-font-weight-bold)) |
--dds-breadcrumb-item-separator-color | The color of the separator (default: var(--dds-text-neutral-disabled)) |
--dds-breadcrumb-item-link-color | The color of the link (default: var(--dds-link-neutral-enabled)) |
--dds-breadcrumb-item-inverted-color | The text color when inverted (default: var(--dds-text-neutral-inverted)) |
--dds-breadcrumb-item-inverted-link-color | The link color when inverted (default: var(--dds-text-neutral-inverted)) |
