Skip to content
BlazorUI

Navs

Breadcrumb

Bit.BlazorUI

Breadcrumbs show where the current page sits in a hierarchy and give one-click access to its higher levels. Levels that do not fit collapse, at a fixed count or automatically, into a keyboard-operable overflow menu, or the trail wraps or scrolls instead.

Notes

The BitBreadcrumb is a Multi-API component which can accept the list of Items in 3 different ways:
1. The BitBreadcrumbItem class
2. A Custom Generic class
3. The BitBreadcrumbOption component

Usage

Every example is live. Open its code to see exactly what produced the component running underneath.

Basic

An item with an Href is a link; IsSelected marks the current page (aria-current="page") and SelectedItemAsText renders it as plain text. Disabled disables the whole trail and IsDisabled a single item (a disabled link stays a link, announced as unavailable), and Target opens a link elsewhere (with rel="noopener noreferrer").

Selected item as text
Item target (opens in a new tab)

MaxDisplayedItems & OverflowIndex

MaxDisplayedItems caps the visible items and collapses the rest into an overflow menu; OverflowIndex places its button. Keyboard: Enter, Space or the arrows open the menu, arrows and Home/End move, a letter jumps to the matching item, Escape or Tab closes it. AriaLabel names the landmark ("Breadcrumb" by default) and OverflowAriaLabel the button ("More items"), for example to localize them.

Max displayed items (2)
Max displayed items (3), Overflow index (1)
Max displayed items (3), Overflow index (2), AriaLabel & OverflowAriaLabel

Truncation, Wrapping & Scrolling

A long trail stays on one line by default. MaxItemWidth truncates each item (its text becomes the tooltip when it has no Title), Wrap flows it onto more lines and Scrollable scrolls it sideways, opening on its end.

Auto Collapse

AutoCollapse moves what does not fit into the overflow menu and brings it back as room returns. MaxDisplayedItems and OverflowIndex still apply; Wrap turns it off. Once only the last item is left, its text truncates.

Expand Overflow

ExpandOverflow makes the overflow button reveal the collapsed items in place instead of opening a menu, and moves the focus to the first revealed item. Pair it with Wrap or Scrollable when room is tight.

Expand in place

Icons & Divider

IconName adds an icon to an item and IconPlacement End puts it after the text. An icon-only item needs an AriaLabel. DividerIconName, DividerText and OverflowIconName replace the default glyphs; dividers are always hidden from screen readers.

Item icons, DividerIconName & OverflowIconName
IconPlacement End
Icon-only root with an AriaLabel & DividerText

Templates

DividerIconTemplate, ItemTemplate and OverflowTemplate customize every item; an item's own Template and OverflowTemplate win over them.

DividerIconTemplate
ItemTemplate & OverflowTemplate
Item's Template & OverflowTemplate

Events & Dynamic Items

OnItemClick reports every activated item, link or button, and each item may carry its own OnClick. Here a click goes back up to that item and Add item goes one level deeper; the overflow follows the trail.

Structured Data

StructuredData renders the whole trail, collapsed items included, as a schema.org BreadcrumbList JSON-LD script with absolute URLs for search engines. Inspect the page to see it.

Cascading parameters

BitParams hands a BitBreadcrumbParams to every breadcrumb under it, whatever its item type. The values are defaults, not overrides: a parameter a breadcrumb sets itself wins.

Takes the divider, the collapsing and the plain text current page from the cascade
Its own divider, the cascaded rest
Outside the cascade, back to the defaults

Color

The color role of the items, the dividers and the focus ring.

External Icons

External icon libraries like FontAwesome can be used with the Icon parameter.

Implicit string conversion (auto-detects external icons)
BitIconInfo.Css (uses CSS classes directly)
BitIconInfo.Fa (FontAwesome helper)
BitIconInfo.Bi (Bootstrap Icons helper)

Size

Sizes the text, the glyphs and the overflow menu together.

Style & Class

Style/Class reach the root, an item's own Style/Class reach that item, and Styles/Classes reach every part by name. The CSS variables inherit: set on :root or an ancestor they re-skin every breadcrumb below it, and set in a breadcrumb's Style they reach its overflow menu too.

RTL

Use BitBreadcrumb in right-to-left (RTL) layouts, where the dividers and the overflow menu flip along with the text.

CSS variables

The public custom properties this component reads off its root, for what no parameter covers.

Every variable is read with a fallback and never declared by the component, so it inherits like any other custom property: set one on :root (or in a [bit-theme] block) to restyle every instance, on any ancestor to restyle the ones inside it, or on the Style of one instance to restyle that one alone. Leave a variable unset and the component falls back to the theme token beside it.

BitBreadcrumb CSS variables

Name Default value Description
--bit-Breadcrumb-color The Color role's main color (--bit-clr-fg-pri without a Color) Text of the items, in the trail and in the overflow menu.
--bit-Breadcrumb-selected-color --bit-Breadcrumb-color Text of the current (selected) item.
--bit-Breadcrumb-selected-font-weight --bit-tpg-fw-semibold Weight of the current (selected) item.
--bit-Breadcrumb-disabled-color --bit-clr-fg-dis Text of a disabled item or of a disabled breadcrumb.
--bit-Breadcrumb-hover-color The color at rest Text of a hovered item or menu item, and the glyph of a hovered overflow button.
--bit-Breadcrumb-hover-background --bit-clr-bg-pri-hover Background of a hovered item, overflow button or menu item.
--bit-Breadcrumb-active-background --bit-clr-bg-pri-active Background of a pressed item, overflow button or menu item.
--bit-Breadcrumb-focus-color The Color role's focus color (--bit-clr-pri-focus without a Color) Focus indicator color.
--bit-Breadcrumb-font-size Per Size Text size of the items.
--bit-Breadcrumb-item-height Per Size (--bit-siz-ctrl-*) Line height of the items, which sets the height of the trail.
--bit-Breadcrumb-item-padding 0 8px Padding of the items.
--bit-Breadcrumb-item-gap 8px Space between the icon and the text of an item.
--bit-Breadcrumb-item-radius --bit-shp-radius-control Corner radius of the items and the overflow button.
--bit-Breadcrumb-item-max-width none Width the text of an item truncates at. The MaxItemWidth parameter takes precedence and also adds the tooltips.
--bit-Breadcrumb-divider-color The Color role's main color (--bit-clr-fg-sec without a Color) Color of the dividers and of the overflow button glyph.
--bit-Breadcrumb-divider-size Per Size Size of the divider icons.
--bit-Breadcrumb-divider-spacing 0 Space on each side of a divider.
--bit-Breadcrumb-callout-background --bit-clr-bg-pri Background of the overflow menu.
--bit-Breadcrumb-callout-radius --bit-shp-radius-popup Corner radius of the overflow menu.
--bit-Breadcrumb-callout-shadow --bit-shd-popup Elevation of the overflow menu.
--bit-Breadcrumb-callout-max-width The width of the viewport Widest the overflow menu gets before the text of its rows is truncated.
--bit-Breadcrumb-overflow-item-height Per Size (--bit-siz-item-*) Height of a row of the overflow menu.
--bit-Breadcrumb-overflow-font-size Per Size Text size of a row of the overflow menu.

API

Every parameter, public member, sub-class and enum this component exposes.

BitBreadcrumb parameters

Name Type Default value Description
AutoCollapse bool false Collapses the items that do not fit into the overflow menu and brings them back as room returns, keeping the trail on one line; once only the last item is left, its text truncates. MaxDisplayedItems still caps the trail and Wrap turns it off.
AutoReorderOptions bool false Keeps the rendered order in sync with the markup order of the options even when they are only reordered. Costs one JS interop call per render; options API only.
ChildContent RenderFragment? null The content of the BitBreadcrumb, that are BitBreadcrumbOption components.
Classes BitBreadcrumbClassStyles? null Custom CSS classes for different parts of the breadcrumb.
Color BitColor? null The general color of the items and the divider of the breadcrumb.
DividerIcon BitIconInfo? null Render a custom divider icon in place of the default chevron.
DividerIconName string? null The divider icon name.
DividerIconTemplate RenderFragment? null The custom template content to render divider icon.
DividerText string? null A plain text divider (for example "/" or "›") to render in place of the default chevron icon. It is ignored when the DividerIconTemplate is provided.
ExpandOverflow bool false Makes the overflow button reveal the collapsed items in place instead of opening a menu. The next change of the items or of the collapsing settings collapses the trail again.
IconPlacement BitPlacement? null Where the icon of each item is rendered relative to its text: before it (Start, the default) or after it (End). An item's own IconPlacement wins.
Items IList<TItem> [] Collection of the items to render in the breadcrumb.
ItemTemplate RenderFragment<TItem>? null The custom template content to render each item.
MaxDisplayedItems uint 0 The maximum number of items to display; the rest collapse into the overflow menu. 0 displays them all.
MaxItemWidth string? null The maximum width of the text of each item as a CSS length (for example "8rem"). Longer text is truncated with an ellipsis and, when the item has no Title, becomes its tooltip.
NameSelectors BitBreadcrumbNameSelectors<TItem>? null Names and selectors of the custom input type properties.
OnItemClick EventCallback<TItem> Callback for when an item is clicked, whether it is rendered as a link or as a button.
Options RenderFragment? null Alias of the ChildContent.
OverflowAriaLabel string? More items Accessible label of the overflow button, which also names the menu it opens.
OverflowIndex uint 0 Where the overflow button sits among the displayed items; the collapsed items start there. 0 collapses from the root, 1 keeps the root and collapses the middle.
OverflowIcon BitIconInfo? null Render a custom overflow icon in place of the default icon.
OverflowIconName string? More The overflow icon name.
OverflowIconTemplate RenderFragment? null The custom template content to render the overflow icon.
OverflowTemplate RenderFragment<TItem>? null The custom template content to render each item in overflow list.
Scrollable bool false Lets a long trail scroll sideways instead of overflowing its container, scrolled to its end so the current page is in view. Ignored while Wrap is on.
SelectedItemAsText bool false Renders the selected item as plain text instead of as a link or a button. It keeps its aria-current.
Size BitSize? null The size of the items of the breadcrumb.
StructuredData bool false Renders the whole trail, collapsed items included, as a schema.org BreadcrumbList JSON-LD script for search engines, with each Href resolved to an absolute URL.
Styles BitBreadcrumbClassStyles? null Custom CSS styles for different parts of the breadcrumb.
Wrap bool false Lets a long trail wrap onto more lines instead of overflowing its container. It turns AutoCollapse and Scrollable off; a fixed MaxDisplayedItems still applies.

BitComponentBase parameters

Name Type Default value Description
AriaLabel string? null Gets or sets the accessible label for the component, used by assistive technologies.
Class string? null Gets or sets the CSS class name(s) to apply to the rendered element.
Dir BitDir? null Gets or sets the text directionality for the component's content.
Disabled bool false Gets or sets a value indicating whether the component is disabled and cannot respond to user interaction.
ForceAnimation bool false Gets or sets a value indicating whether the component's animations play at their full duration even when reduced motion is requested.
HtmlAttributes Dictionary<string, object> new Dictionary<string, object>() Captures additional HTML attributes to be applied to the rendered element, in addition to the component's parameters.
Id string? null Gets or sets the unique identifier for the component's root element.
Style string? null Gets or sets the CSS style string to apply to the rendered element.
TabIndex string? null Gets or sets the tab order index for the component when navigating with the keyboard.
Visibility BitVisibility BitVisibility.Visible Gets or sets the visibility state (visible, hidden, or collapsed) of the component.

BitComponentBase public members

Name Type Default value Description
UniqueId Guid Guid.NewGuid() Gets the readonly unique identifier for the component's root element, assigned when the component instance is constructed.
RootElement ElementReference Gets the reference to the root HTML element associated with this component.

BitBreadcrumbClassStyles properties

Name Type Default value Description
Root string? null Custom CSS classes/styles for the root element of the BitBreadcrumb.
Overlay string? null Custom CSS classes/styles for the overlay of the BitBreadcrumb.
ItemContainer string? null Custom CSS classes/styles for the item container of the BitBreadcrumb.
OverflowButton string? null Custom CSS classes/styles for the overflow button of the BitBreadcrumb.
OverflowButtonIcon string? null Custom CSS classes/styles for the overflow button icon of the BitBreadcrumb.
ItemWrapper string? null Custom CSS classes/styles for the item wrapper of the BitBreadcrumb.
Item string? null Custom CSS classes/styles for each item of the BitBreadcrumb.
ItemIcon string? null Custom CSS classes/styles for each item icon of the BitBreadcrumb.
ItemText string? null Custom CSS classes/styles for each item text of the BitBreadcrumb.
SelectedItem string? null Custom CSS classes/styles for the selected item of the BitBreadcrumb.
Divider string? null Custom CSS classes/styles for the divider of the BitBreadcrumb.
DividerIcon string? null Custom CSS classes/styles for the divider icon of the BitBreadcrumb.
Callout string? null Custom CSS classes/styles for the callout element of the BitBreadcrumb.
CalloutContainer string? null Custom CSS classes/styles for the callout container of the BitBreadcrumb.
OverflowItemWrapper string? null Custom CSS classes/styles for the overflow item wrapper of the BitBreadcrumb.
OverflowItem string? null Custom CSS classes/styles for each overflow item of the BitBreadcrumb.
OverflowItemIcon string? null Custom CSS classes/styles for each overflow item icon of the BitBreadcrumb.
OverflowItemText string? null Custom CSS classes/styles for each overflow item text of the BitBreadcrumb.
OverflowSelectedItem string? null Custom CSS classes/styles for the overflow selected item of the BitBreadcrumb.

BitBreadcrumbNameSelectors<TItem> properties

Name Type Default value Description
AriaLabel BitNameSelectorPair<TItem, string?> new(nameof(BitBreadcrumbItem.AriaLabel)) The AriaLabel field name and selector of the custom input class.
Key BitNameSelectorPair<TItem, string?> new(nameof(BitBreadcrumbItem.Key)) The Key field name and selector of the custom input class.
Text BitNameSelectorPair<TItem, string?> new(nameof(BitBreadcrumbItem.Text)) The Text field name and selector of the custom input class.
Href BitNameSelectorPair<TItem, string?> new(nameof(BitBreadcrumbItem.Href)) The Href field name and selector of the custom input class.
Class BitNameSelectorPair<TItem, string?> new(nameof(BitBreadcrumbItem.Class)) The CSS Class field name and selector of the custom input class.
Style BitNameSelectorPair<TItem, string?> new(nameof(BitBreadcrumbItem.Style)) The CSS Style field name and selector of the custom input class.
Icon BitNameSelectorPair<TItem, BitIconInfo?> new(nameof(BitBreadcrumbItem.Icon)) The Icon field name and selector of the custom input class.
IconName BitNameSelectorPair<TItem, string?> new(nameof(BitBreadcrumbItem.IconName)) The IconName field name and selector of the custom input class.
IconPlacement BitNameSelectorPair<TItem, BitPlacement?> new(nameof(BitBreadcrumbItem.IconPlacement)) The IconPlacement field name and selector of the custom input class.
IsSelected BitNameSelectorPair<TItem, bool> new(nameof(BitBreadcrumbItem.IsSelected)) The IsSelected field name and selector of the custom input class.
IsDisabled BitNameSelectorPair<TItem, bool> new(nameof(BitBreadcrumbItem.IsDisabled)) The IsDisabled field name and selector of the custom input class.
OnClick Action<TItem>? Click event handler of the item.
OverflowTemplate BitNameSelectorPair<TItem, RenderFragment<TItem>?> new(nameof(BitBreadcrumbItem.OverflowTemplate)) The OverflowTemplate field name and selector of the custom input class.
Target BitNameSelectorPair<TItem, string?> new(nameof(BitBreadcrumbItem.Target)) The Target field name and selector of the custom input class.
Template BitNameSelectorPair<TItem, RenderFragment<TItem>?> new(nameof(BitBreadcrumbItem.Template)) The Template field name and selector of the custom input class.
Title BitNameSelectorPair<TItem, string?> new(nameof(BitBreadcrumbItem.Title)) The Title field name and selector of the custom input class.

BitNameSelectorPair<TItem, TProp> properties

Name Type Default value Description
Name string Custom class property name.
Selector Func<TItem, TProp?>? Custom class property selector.

BitIconInfo properties

Represents icon information for rendering icons. Supports built-in Fluent UI icons and external icon libraries (FontAwesome, Bootstrap Icons, etc.). Use BitIconInfo.Css("fa-solid fa-star"), BitIconInfo.Fa("solid star"), or BitIconInfo.Bi("star-fill") for external icons.

Name Type Default value Description
Name string? null Gets or sets the name of the icon. For external icons, this can be the full CSS class name if BaseClass and Prefix are empty.
BaseClass string? null Gets or sets the base CSS class for the icon. For built-in Fluent UI icons, this defaults to "bit-icon". For external icon libraries like FontAwesome, you might set this to "fa" or leave empty.
Prefix string? null Gets or sets the CSS class prefix used before the icon name. For built-in Fluent UI icons, this defaults to "bit-icon--". For external icon libraries, you might set this to "fa-" or leave empty.

BitColor enum

Name Value Description
Primary 0 Primary general color.
Secondary 1 Secondary general color.
Tertiary 2 Tertiary general color.
Info 3 Info general color.
Success 4 Success general color.
Warning 5 Warning general color.
SevereWarning 6 SevereWarning general color.
Error 7 Error general color.
PrimaryBackground 8 Primary background color.
SecondaryBackground 9 Secondary background color.
TertiaryBackground 10 Tertiary background color.
PrimaryForeground 11 Primary foreground color.
SecondaryForeground 12 Secondary foreground color.
TertiaryForeground 13 Tertiary foreground color.
PrimaryBorder 14 Primary border color.
SecondaryBorder 15 Secondary border color.
TertiaryBorder 16 Tertiary border color.

BitPlacement enum

Name Value Description
Top 0 The top edge.
Bottom 1 The bottom edge.
Start 2 The edge the reading direction starts from - the left in LTR, the right in RTL. On the vertical axis, which does not turn around, it is the top.
End 3 The edge the reading direction ends at - the right in LTR, the left in RTL. On the vertical axis, which does not turn around, it is the bottom.
Left 4 The left edge, in both reading directions.
Right 5 The right edge, in both reading directions.
Center 6 The middle of the axis, against neither edge.
TopAndBottom 7 Both edges of the block axis at once.
StartAndEnd 8 Both edges of the inline axis at once, following the reading direction the way Start and End do.

BitSize enum

Name Value Description
Small 0 The small size.
Medium 1 The medium size.
Large 2 The large size.

BitVisibility enum

Name Value Description
Visible 0 The content of the component is visible.
Hidden 1 The content of the component is hidden, but the space it takes on the page remains (visibility:hidden).
Collapsed 2 The component is hidden (display:none).

BitDir enum

Name Value Description
Ltr 0 Ltr (left to right) is to be used for languages that are written from the left to the right (like English).
Rtl 1 Rtl (right to left) is to be used for languages that are written from the right to the left (like Arabic).
Auto 2 Auto lets the user agent decide. It uses a basic algorithm as it parses the characters inside the element until it finds a character with a strong directionality, then applies that directionality to the whole element.

Feedback

Found a mistake, a gap, or something that could be clearer? Every page and every component is one click from its source.