Skip to content
BlazorUI

Navs

Breadcrumb

Bit.BlazorUI

Breadcrumbs should be used as a navigational aid in your app or site. They indicate the current page’s location within a hierarchy, afford one-click access to the higher levels of it, and handle the levels that do not fit by collapsing them - at a fixed count or automatically as the room changes - into a keyboard-operable overflow menu or behind a button that expands them back into the trail, or by letting the trail wrap onto more lines or scroll sideways instead. The trail is rendered as a navigation landmark holding an ordered list, with the current page marked for assistive technologies (and optionally rendered as plain text rather than a link) and the dividers hidden from them, and it can publish the whole hierarchy as schema.org structured data for search engines.

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

The breadcrumb renders a navigation landmark holding an ordered list of the Items. An item with an Href becomes a link, the item marked with IsSelected becomes the current page of the trail (aria-current) and an item with IsEnabled set to false stays in the trail but is not actionable (aria-disabled). Setting Target on an item opens its link in another browsing context, in which case the link is rendered with a rel of "noopener noreferrer". SelectedItemAsText renders the current page as plain text instead of as a link, which is what the breadcrumb pattern asks of the page the user is already on, without taking its aria-current away.


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

MaxDisplayedItems & OverflowIndex

MaxDisplayedItems caps how many items stay in the trail, the rest are collapsed behind an overflow button that opens them in a menu. OverflowIndex chooses where that button sits among the displayed items, so the first and the last steps of the hierarchy can be kept visible while the middle collapses. The collapsed steps open in a menu the keyboard drives: Enter, Space or the arrow keys open it, the arrow keys and Home/End move inside it, typing a character jumps to the item that starts with it, and Escape or Tab closes it back onto the button.


Max displayed items (1)
Max displayed items (2)
Max displayed items (3)
Max displayed items (3), Overflow index (0)
Max displayed items (3), Overflow index (1)
Max displayed items (3), Overflow index (2)

Icons

Each item can carry an icon next to its text through IconName, and ReversedIcon swaps the icon and the text around (per item, or for the whole breadcrumb). The icon of the overflow button is configurable through OverflowIconName as well.


Item icons (OverflowIcon: ChevronDown - DividerIcon: CaretRightSolid8)

Item icons (OverflowIcon: CollapseMenu) with active ReversedIcon

Divider

The chevron between the items can be replaced by any other icon with DividerIconName, or by a plain text separator with DividerText (the classic "/" of a file path, for example). Dividers are decorative, so they are always hidden from screen readers.


Default divider
DividerIconName
DividerText (/)
DividerText (›)

Templates

Every part of the content is templatable: DividerIconTemplate for the separator, ItemTemplate and OverflowTemplate for all of the items at once, and the Template and OverflowTemplate of a single item for a one-off. A template of an item wins over the template of the component.


DividerIconTemplate

ItemTemplate & OverflowTemplate

Item's Template & Item's OverflowTemplate

Events

OnItemClick reports every activated item, no matter whether it is rendered as a link or as a button, and each item can also carry its own OnClick handler. Here the handler moves the selection, which the SelectedItem and OverflowSelectedItem styles pick up.


Customizations

The breadcrumb keeps up with an Items collection that changes at runtime, and with the collapsing settings changing along with it. Add or remove items and move the two sliders to see how the trail and the overflow menu are recomputed.


Truncation, Wrapping & Scrolling

A trail of long titles is kept on a single line by default, which makes it overflow a container that is too narrow for it. MaxItemWidth truncates the text of each item with an ellipsis at the given CSS length, in which case the text of an item that carries no Title of its own becomes its tooltip so the full text stays reachable. Wrap lets the trail flow onto more than one line instead, and Scrollable keeps it on a single line but hands it a scrollbar of its own, which is what a trail whose every step is worth keeping in place asks for. Wrap wins over Scrollable, since a trail that may flow onto another line never runs out of room on one.


Auto Collapse

AutoCollapse measures the trail and moves the items that do not fit into the overflow menu, bringing them back as the room for them returns, so the breadcrumb always stays on a single line whatever the width of its container is. MaxDisplayedItems, when it is set, still caps how many items may stay in the trail and OverflowIndex still decides where the overflow button sits, so setting it to 1 keeps the root of the hierarchy visible and collapses the middle of the trail instead. Wrap turns the measuring off entirely, since a trail that may flow onto another line has no items that do not fit.



Overflow index (1): the first item stays, the middle collapses

Structured Data

StructuredData writes the trail next to the breadcrumb as a schema.org BreadcrumbList in a JSON-LD script, which is what search engines read to show the hierarchy of a page in their results. The whole hierarchy is written, the steps the overflow menu holds included, so what the crawlers are told does not depend on how much of the trail fits the screen, and the Href of each item is resolved into an absolute address. Inspect the elements of the page to see the script the breadcrumb below renders.


Expand Overflow

ExpandOverflow turns the overflow button into a disclosure of the collapsed steps: pressing it puts them back into the trail instead of opening them in a menu, and the button is gone along with the collapsing it undid. The focus it held is handed over to the first of the steps it revealed, so the keyboard carries on from where the trail grew. The expanded trail may be wider than the room it has, so pairing it with Wrap (or with Scrollable) keeps it readable. It works the same way over an automatically collapsed trail, which stops measuring once it is expanded.


Expand the collapsed items in place

Color

Offering a range of specific colors for the items and the divider of the breadcrumb.


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

Three sizes of the breadcrumb, driving the text and the overflow menu of the trail.


Style & Class

The look of the breadcrumb is customizable at three levels: the Style and Class of the component, the Style and Class of a single item, and the Styles and Classes of every part of it (the root, the items, the selected item, the dividers, the overflow button and menu, ...).




RTL

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

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 the width of the breadcrumb into the overflow menu, and brings them back as the room for them returns, so the trail always stays on a single line. MaxDisplayedItems, when it is set, still caps how many items the automatic collapsing may leave in the trail. It is turned off entirely by Wrap, since a trail that may flow onto another line has no items that do not fit.
AutoReorderOptions bool false Keeps the rendered order of the items in sync with the markup order of the options even when existing options are only reordered (not added or removed). It reads the DOM order of the options after each render, so it adds a JS interop call per render and is opt-in. It only affects the options API (ChildContent/Options).
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 put the collapsed items back into the trail instead of opening them in a menu. The whole trail is revealed at once and the button is gone with the collapsing it undid. The next change of the items or of the collapsing settings starts the breadcrumb over as collapsed.
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 before coalescing. If not specified, all of the items will be rendered.
MaxItemWidth string? null The maximum width of the text of each item as a CSS length (for example "8rem"). The text of a longer item is truncated with an ellipsis, and the text of an item that carries no Title of its own becomes its tooltip so that the full text stays reachable.
NameSelectors BitBreadcrumbNameSelectors<TItem>? null Names and selectors of the custom input type properties.
OnItemClick EventCallback<TItem> Callback for when a breadcrumb item is clicked, no matter whether it is rendered as a link or as a button.
Options RenderFragment? null Alias of the ChildContent.
OverflowAriaLabel string? More items Aria label of the overflow button and of the overflow menu.
OverflowIndex uint 0 Optional index where overflow items will be collapsed. It is the position the overflow button takes among the displayed items, and the items that collapse are the ones that start there, so the default of 0 collapses the trail from its root while 1 keeps the root visible and collapses the middle instead.
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 each overflow icon.
OverflowTemplate RenderFragment<TItem>? null The custom template content to render each item in overflow list.
ReversedIcon bool false Reverses the positions of the icon and the item text of the item content.
Scrollable bool false Lets a long breadcrumb trail scroll sideways inside its container instead of overflowing it, which is what a trail whose every step is worth keeping in place asks for. It has nothing to do while Wrap is on, since a trail that may flow onto another line never runs out of room on one.
SelectedItemAsText bool false Renders the selected item as plain text instead of as a link or a button, which is what the breadcrumb pattern asks of the page the user is already on. It keeps its aria-current either way, and the items around it stay actionable.
Size BitSize? null The size of the items of the breadcrumb.
StructuredData bool false Renders the trail as a schema.org BreadcrumbList in a JSON-LD script next to it, which is what search engines read to show the hierarchy of the page in their results. The whole hierarchy is written, including the items the overflow menu holds, and the Href of each item is resolved against the base address of the app.
Styles BitBreadcrumbClassStyles? null Custom CSS styles for different parts of the breadcrumb.
Wrap bool false Lets a long breadcrumb trail wrap into multiple lines instead of overflowing its container in a single line. It turns AutoCollapse and Scrollable off while it is on, though a fixed MaxDisplayedItems still collapses what it is told to.

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.
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.
IsEnabled bool true Gets or sets a value indicating whether the component is enabled and can respond to user interaction.
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.
ReversedIcon BitNameSelectorPair<TItem, bool?> new(nameof(BitBreadcrumbItem.ReversedIcon)) The ReversedIcon 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.
IsEnabled BitNameSelectorPair<TItem, bool> new(nameof(BitBreadcrumbItem.IsEnabled)) The IsEnabled 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.

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.