Skip to content
BlazorUI

Navs

NavBar

Bit.BlazorUINavMenuTabPanelBottomNavigationTabBarNavigationRail

A bar of navigation links to the main areas of an app, the way a mobile app puts its top-level destinations along the bottom of the screen.

Notes

Each item renders an icon over its text and becomes a link when it carries a URL. In the default Automatic mode the navbar follows the browser and selects the item whose URL points at the current page — matched exactly, by prefix, by a wildcard or by a regular expression — while the Manual mode leaves the selection to clicks and to the two-way SelectedItem binding. The selected item can swap to a filled SelectedIconName and take an Indicator of its own — a line along its edge or a pill behind its icon — and the bar reshapes itself for the space it has: labels beside the icons, only on the selected item or dropped altogether, a column that turns it into a navigation rail, a chosen Alignment of the items along it, a Scrollable list for more destinations than it fits, content of its own before and after them, and a safe-area inset for a bar pinned to the bottom of a phone.

The items are marked up as the list they are, the selected one reports itself to assistive technology as the current page, a badge is folded into the name of its item rather than announced twice, every item is a tab stop of its own (or one roving stop, with SingleTabStop) and the arrow keys, Home and End move the focus along the bar, optionally carrying the selection with it.

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

Usage

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

Basic

Each item of the navbar renders an icon over its text and becomes a link when it carries a Url. By default the navbar runs in the Automatic mode, where it highlights the item whose URL points at the current page all by itself. Every item is a tab stop of its own and the selected one reports itself as the current page to a screen reader.


Disabled

IsEnabled turns the whole navbar off, and the IsEnabled of an item turns that one item off. A disabled item is not only greyed out: it loses its link, its tab stop and its keyboard stop, so it cannot be reached or followed at all.


Disabled:





Disabled item:

Manual Mode

In the Manual mode the selection is driven by clicks instead of by the current URL, which is what a navbar that switches between panels of the same page needs. DefaultSelectedItem sets the item to start on. A navbar that switches panels rather than pages marks its current item with an AriaCurrent of True, since it is not the page that is current but one item of a set.


URL Matching

In the Automatic mode the navbar selects the item whose URL points at the current page. Match sets how those URLs are compared for the whole navbar, and the Match of an item overrides it: Exact asks for the same URL, Prefix also matches everything below it, Wildcard reads the URL of the item as a pattern in which ? stands for a single character other than /, * for any number of them and ** for any number of characters at all, slashes included, and Regex reads it as a regular expression. Exact and Prefix compare the path alone when the URL of the item carries neither a query string nor a fragment, and the whole URL when it carries one, and they ignore the letter case and a trailing slash either way; a Wildcard or a Regex pattern is run against both, so it can match the query and the fragment as well. AdditionalUrls gives an item other URLs to light up on. The navbars below are all matched against the URL of this page.


Exact (the default):





Prefix:





Wildcard:





Regex:





AdditionalUrls:

IconOnly

IconOnly drops the text of every item and keeps the icons alone. The text is still what names the item for a screen reader, and it is moved onto the item as its label and its tooltip, so nothing is lost by hiding it.


HideUnselectedText

HideUnselectedText keeps the text of the selected item alone and leaves the rest with their icon, which is how a bar holding more destinations stays readable without dropping every label. Select an item to move the label along with the selection.


Layout

InlineText puts the text of an item beside its icon instead of under it, which is what a navbar does with the room a wider layout gives it. Stacking the items into a column instead turns the navbar into a navigation rail, which Vertical covers in a section of its own below.


Width

FitWidth shrinks the navbar to the width of its own content, and FullWidth stretches it over the full width of its container. Without either one the navbar takes the width its container gives it. Those two size the bar; Justified sizes the items inside it, giving each one an equal share instead of the width of its own label, which is how a navigation bar keeps its destinations on a predictable grid, and Scrollable is the other answer to a bar that runs out of room: it leaves the items at the size of their own content and scrolls them instead.


FitWidth:





FullWidth:





Justified (items of unequal label length):

Alignment

Alignment distributes the items along the navbar: packed at its Start, its Center or its End, or spread over it with SpaceBetween, SpaceAround (what a horizontal bar does on its own) and SpaceEvenly. It works in both directions, so it is also what moves the destinations of a Vertical rail away from its top edge. Justified is the other half of the picture: it has the items fill the navbar instead of sitting somewhere along it.


Start:





Center:





End:





SpaceBetween:

Indicator

Indicator gives the selection a mark of its own beside the color of the item: a Line along the edge of the selected item — its bottom edge across a bar and its leading edge down a Vertical rail, the way a tab strip marks its current tab — or the Pill a Material navigation bar draws behind the icon of its current destination. The pill is the filled part in that mode, so it takes the fill of the item over, and both follow the Color while Filled is enabled.


Line:





Pill:





Pill, filled:

Scrollable

A navbar squeezes its items into the room it has, which runs out once it holds more destinations than it fits. Scrollable leaves every item at the size of its own content and scrolls the list instead, with the scrollbar itself hidden, and it brings the selected item into view whenever the selection moves — from a click, from the URL in the Automatic mode, or from the binding, as the button below does. A Vertical rail scrolls down its own length in exactly the same way.





Selected item:

Header & Footer

HeaderTemplate and FooterTemplate render content before and after the items and outside of the list the items form, so whatever they hold is not counted among the destinations by a screen reader: the logo or the menu button of a bar, and the button a navigation rail is conventionally headed or ended with.


Vertical

Vertical stacks the items in a column, which turns the navbar into the navigation rail that runs down the side of a page instead of across the foot of it. The header, the items and the footer all follow that direction, and a rail is normally sized with FitWidth, so it takes the width of its own content rather than the width of its container. Everything the bar does the rail does too: InlineText and IconOnly reshape its items, Alignment moves them away from its top edge, the Line indicator runs down the leading edge of the selected item instead of along its bottom, Scrollable scrolls the rail down its own length, and the header and the footer sit above and below the items.


Basic:





InlineText:





IconOnly:





Alignment:





Indicator:





Scrollable:





Header & Footer:

Badge

Badge puts a short count or status on the icon of an item, and Dot marks it as needing attention without a number. Both are drawn on the icon and hidden from assistive technology, and the badge is folded into the name of the item instead, so it is announced once rather than twice — "Inbox (12)". BadgeAriaLabel replaces that with a description a screen reader can read out on its own, and is the only way a Dot is announced at all, since a dot carries no text.


Filled

Filled fills the hovered and the selected item, which gives the selection a mark of its own instead of leaving it to the text color alone. The fill takes the Color of the navbar, and the content of the item — along with the Indicator, when the navbar carries one — moves onto the on-color of that color so that it stays legible over the fill.


Templates

ItemTemplate replaces the content of every item of the navbar, and the Template of a single item replaces that one item's content and wins over the navbar's template. Either one renders inside the anchor (or the button) the item is; TemplateRenderMode of an item (and ItemTemplateRenderMode of the navbar, for its own template) set to Replace has the template render that element itself instead, which is what an item that is a control of its own — the center action of a mobile bar — needs, since an interactive element cannot be nested in another one. A replaced item owns its clicks, its focus and its accessible name, and is left out of the keyboard navigation of the bar.


ItemTemplate:





Item's template:





Replaced item template:

Events

OnItemClick is invoked when an item is clicked, and OnSelectItem when the selection actually moves onto an item, whether that came from a click or from the URL in the Automatic mode.




Clicked item:
Selected item:

Binding

DefaultSelectedItem only sets the item to start on, while SelectedItem binds both ways, so the selection can be read and written from outside the navbar at any time.


DefaultSelectedItem:


Selected item: Home



Two-way SelectedItem:


Reselectable

The events of an item that is already selected are swallowed, so a second click on the current destination changes nothing. Reselectable lets them through, which is what a bar that scrolls its page back to the top on a repeated click needs.




Item click count: 0

Keyboard

By default the navbar is a set of links that Tab reaches one by one, which is how a navigation landmark behaves. SingleTabStop turns it into the roving tab index of a toolbar instead: the whole bar is a single stop that lands on the selected item, and the rest are reached from there. In both modes the arrow keys of either axis, Home and End move the focus along the bar, the horizontal pair flipping in RTL, and a disabled item is skipped. The focus stops at both ends; WrapNavigation lets it wrap around from the last item to the first one and back, and SelectOnFocus moves the selection along with the focus in the Manual mode, the way the tabs of a tab list do.


SingleTabStop:





WrapNavigation:





SelectOnFocus:

Selected Icon

A navigation bar conventionally marks its current destination with the filled variant of the same glyph, which is what SelectedIconName (and SelectedIcon, for an external icon library) is for: the item swaps to it while it is the selected one and falls back to its IconName otherwise. It reads as a second, shape-based cue for the selection next to the color, which is what keeps the current destination legible where a color difference alone is not enough. Indicator adds a third cue, drawn beside the content of the item rather than in it.


Dynamic Items

The Items collection is read again on every render, so items appended to (or removed from) the very same list are picked up without handing the navbar a new collection. The selection survives as long as the item it points at is still in the list, and the keyboard follows the new order at once.




Selected item:

Color

Offering a range of specialized colors, providing visual cues for specific states within your application.


Primary:





Secondary:





Tertiary:





Info:





Success:





Warning:





SevereWarning:





Error:





PrimaryBackground:





SecondaryBackground:





TertiaryBackground:





PrimaryForeground:





SecondaryForeground:





TertiaryForeground:





PrimaryBorder:





SecondaryBorder:





TertiaryBorder:

External Icons

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


Size

The Size scales the icon, the text and the padding of every item of the navbar at once.


Small:





Medium:





Large:

Style & Class

Empower customization by overriding default styles and classes, allowing tailored design modifications to suit specific UI requirements.


Component's Style:



Component's Class:





Item's style & class:





Styles:



Classes:

RTL

Use BitNavBar in right-to-left (RTL).


API

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

BitNavBar parameters

Name Type Default value Description
Alignment BitAlignment? null How the items are distributed along the navbar: packed at its start, its center or its end, or spread over it. While it is not set, the items of a horizontal navbar are spread evenly over its width and the items of a vertical rail are packed at its top. Baseline and Stretch carry no distribution of their own and are left at the default; use Justified to have the items fill the navbar.
AutoReorderOptions bool false Keeps the order of the registered options in sync with the markup order of the options, even when an option is added, removed or reordered conditionally after the first render (an option that shows up later registers itself at the end of the list, which leaves the keyboard moving between the items in another order than the one they are rendered in). This is achieved by reading the DOM order of the options after each render, so it adds a JS interop call per change and is opt-in.
ChildContent RenderFragment? null Items to render as children.
Classes BitNavBarClassStyles? null Custom CSS classes for different parts of the navbar.
Color BitColor? null The general color of the navbar, used for the icon, the text and the indicator of the selected item.
DefaultSelectedItem TItem? null The initially selected item in manual mode.
Filled bool false Fills the hovered and the selected item of the navbar with the Color of the navbar. While it is not enabled, the selection is conveyed by the color of the item alone.
FitWidth bool false Renders the nav bar in a width to only fit its content.
FooterTemplate RenderFragment? null The content rendered after the items of the navbar, outside of the list they form: the trailing actions of a bar, or the account button at the bottom of a navigation rail.
FullWidth bool false Renders the nav bar in full width of its container element.
HeaderTemplate RenderFragment? null The content rendered before the items of the navbar, outside of the list they form: the logo or the menu button of a bar, or the button a navigation rail is conventionally headed with.
HideUnselectedText bool false Only renders the text of the selected item and leaves the rest of the items with their icon alone, which is how a navigation bar keeps its labels readable while holding more destinations. Ignored while IconOnly is enabled.
IconOnly bool false Only renders the icon of each navbar item.
Indicator BitNavBarIndicator? null The shape of the indicator that marks the selected item: a line along the edge of the item, or the pill a Material navigation bar draws behind the icon of its current destination. While it is not set, the selection is conveyed by the color of the item and by the fill Filled gives it.
InlineText bool false Renders the icon and the text of each item side by side instead of stacking the text under the icon.
Items IList<TItem> new List<TItem>() A collection of items to display in the navbar.
ItemTemplate RenderFragment<TItem>? null Used to customize how content inside the item is rendered.
ItemTemplateRenderMode BitNavItemTemplateRenderMode BitNavItemTemplateRenderMode.Normal Whether the ItemTemplate is rendered inside the anchor (or the button) each item is, or replaces it altogether, which is what items that are controls of their own need, since an interactive element cannot be nested in another one. Replaced items are left out of the keyboard navigation of the navbar, and whatever they render owns its own clicks, its own focus and its own accessible name.
Justified bool false Gives every item an equal share of the navbar so that the items evenly fill it, which is how a navigation bar keeps its destinations on a predictable grid. By default each item only takes the width of its own content.
Match BitNavMatch? null Modifies how the URL of an item is matched against the current URL in the automatic mode. The Match of an item takes precedence over this value, and the default is an exact match.
Mode BitNavMode BitNavMode.Automatic Determines how the navigation will be handled.
NameSelectors BitNavBarNameSelectors<TItem>? null Names and selectors of the custom input type properties.
OnItemClick EventCallback<TItem> Callback invoked when an item is clicked.
OnSelectItem EventCallback<TItem> Callback invoked when an item is selected.
Options RenderFragment? null Alias of ChildContent.
Reselectable bool false Enables recalling the select events when the same item is selected.
SafeArea bool false Reserves the safe area of the device (the home indicator of a phone, for instance) under the navbar, so a bar pinned to the bottom of the screen is not overlapped by it.
Scrollable bool false Lets the items scroll along the navbar instead of being squeezed into it, which is what a bar (or a rail) holding more destinations than it has room for needs. The scrollbar itself is hidden, the items keep the size of their own content, and the selected one is scrolled into view as the selection moves.
SelectedItem TItem? null Selected item to show in the navbar. Supports two-way binding.
SelectOnFocus bool false Selects an item as soon as the focus reaches it, so walking the navbar with the arrow keys switches the selection along with it, the way the tabs of a tab list do. It only applies to the Manual mode, where the selection is the navbar's own.
SingleTabStop bool false Takes the navbar out of the tab sequence as a single stop: only the selected item (or the first one, while nothing is selected) is tabbable and the arrow keys move between the items, exactly like a toolbar. By default every item is a tab stop of its own, the way the links of a navigation are.
Size BitSize? null The size of the navbar.
Styles BitNavBarClassStyles? null Custom CSS styles for different parts of the navbar.
Vertical bool false Stacks the items of the navbar in a column, which turns it into a vertical navigation rail.
WrapNavigation bool false Lets the arrow keys wrap around at both ends of the navbar, from the last item to the first one and back, the way the toolbar pattern does. By default the focus stops at the ends instead.

BitNavBar public members

Name Type Default value Description
FocusItem Func<TItem, ValueTask> Moves the focus to an item of the navbar.
ScrollItemIntoView Func<TItem, ValueTask> Brings an item into the visible area of a Scrollable navbar, without selecting it or moving the focus onto it. It is a no-op on a navbar that does not scroll.
SelectItem Func<TItem?, Task> Selects an item programmatically, exactly like a click on that item would in the manual mode.

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.

BitNavBarNameSelectors<TItem> properties

Name Type Default value Description
AdditionalUrls BitNameSelectorPair<TItem, IEnumerable<string>?> new(nameof(BitNavBarItem.AdditionalUrls)) The AdditionalUrls field name and selector of the custom input class.
AriaCurrent BitNameSelectorPair<TItem, BitNavAriaCurrent?> new(nameof(BitNavBarItem.AriaCurrent)) The AriaCurrent field name and selector of the custom input class.
AriaLabel BitNameSelectorPair<TItem, string?> new(nameof(BitNavBarItem.AriaLabel)) The AriaLabel field name and selector of the custom input class.
Badge BitNameSelectorPair<TItem, string?> new(nameof(BitNavBarItem.Badge)) The Badge field name and selector of the custom input class.
BadgeAriaLabel BitNameSelectorPair<TItem, string?> new(nameof(BitNavBarItem.BadgeAriaLabel)) The BadgeAriaLabel field name and selector of the custom input class.
Class BitNameSelectorPair<TItem, string?> new(nameof(BitNavBarItem.Class)) The Class field name and selector of the custom input class.
Data BitNameSelectorPair<TItem, object?> new(nameof(BitNavBarItem.Data)) The Data field name and selector of the custom input class.
Dot BitNameSelectorPair<TItem, bool?> new(nameof(BitNavBarItem.Dot)) The Dot field name and selector of the custom input class.
Icon BitNameSelectorPair<TItem, BitIconInfo?> new(nameof(BitNavBarItem.Icon)) The Icon field name and selector of the custom input class. Maps to Icon for external icon libraries.
IconName BitNameSelectorPair<TItem, string?> new(nameof(BitNavBarItem.IconName)) The IconName field name and selector of the custom input class. Maps to IconName for built-in Fluent UI icons.
IsEnabled BitNameSelectorPair<TItem, bool?> new(nameof(BitNavBarItem.IsEnabled)) The IsEnabled field name and selector of the custom input class.
Key BitNameSelectorPair<TItem, string?> new(nameof(BitNavBarItem.Key)) The Key field name and selector of the custom input class.
Match BitNameSelectorPair<TItem, BitNavMatch?> new(nameof(BitNavBarItem.Match)) The Match field name and selector of the custom input class.
SelectedIcon BitNameSelectorPair<TItem, BitIconInfo?> new(nameof(BitNavBarItem.SelectedIcon)) The SelectedIcon field name and selector of the custom input class. Maps to SelectedIcon for external icon libraries.
SelectedIconName BitNameSelectorPair<TItem, string?> new(nameof(BitNavBarItem.SelectedIconName)) The SelectedIconName field name and selector of the custom input class. Maps to SelectedIconName for built-in Fluent UI icons.
Style BitNameSelectorPair<TItem, string?> new(nameof(BitNavBarItem.Style)) The Style field name and selector of the custom input class.
Target BitNameSelectorPair<TItem, string?> new(nameof(BitNavBarItem.Target)) The Target field name and selector of the custom input class.
Template BitNameSelectorPair<TItem, RenderFragment<TItem>?> new(nameof(BitNavBarItem.Template)) The Template field name and selector of the custom input class.
TemplateRenderMode BitNameSelectorPair<TItem, BitNavItemTemplateRenderMode?> new(nameof(BitNavBarItem.TemplateRenderMode)) The TemplateRenderMode field name and selector of the custom input class.
Text BitNameSelectorPair<TItem, string?> new(nameof(BitNavBarItem.Text)) The Text field name and selector of the custom input class.
Title BitNameSelectorPair<TItem, string?> new(nameof(BitNavBarItem.Title)) The Title field name and selector of the custom input class.
Url BitNameSelectorPair<TItem, string?> new(nameof(BitNavBarItem.Url)) The Url field name and selector of the custom input class.

BitIconInfo properties

Name Type Default value Description
Name string? null Gets or sets the name of the icon.
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.

BitNavBarClassStyles properties

Name Type Default value Description
Root string? null Custom CSS classes/styles for the root element of the BitNavBar.
Container string? null Custom CSS classes/styles for the container of the items of the BitNavBar.
Footer string? null Custom CSS classes/styles for the footer of the BitNavBar, rendered after the items.
Header string? null Custom CSS classes/styles for the header of the BitNavBar, rendered before the items.
Item string? null Custom CSS classes/styles for the item of the BitNavBar.
ItemBadge string? null Custom CSS classes/styles for the badge (or the dot) of the item of the BitNavBar.
ItemIcon string? null Custom CSS classes/styles for the item icon of the BitNavBar.
ItemIconContainer string? null Custom CSS classes/styles for the wrapper of the icon and the badge of the item of the BitNavBar.
ItemText string? null Custom CSS classes/styles for the item text of the BitNavBar.
ItemWrapper string? null Custom CSS classes/styles for the list item wrapping each item of the BitNavBar.
SelectedItem string? null Custom CSS classes/styles for the selected item of the BitNavBar.

BitNavAriaCurrent enum

Name Value Description
Page 0 Represents the current page within a set of pages.
Step 1 Represents the current step within a process.
Location 2 Represents the current location within an environment or context.
Date 3 Represents the current date within a collection of dates.
Time 4 Represents the current time within a set of times.
True 5 Represents the current item within a set.

BitNavItemTemplateRenderMode enum

Name Value Description
Normal 0 Renders the template inside the anchor (or the button) the item is, so the item keeps its click, its focus and its place in the keyboard navigation of the navbar.
Replace 1 Replaces the anchor (or the button) the item is with the template, which is what an item that is a control of its own needs. The template owns its clicks, its focus and its accessible name, and the item is left out of the keyboard navigation of the navbar.

BitNavBarIndicator enum

Name Value Description
None 0 No indicator of its own: the selection is conveyed by the color of the item and, while Filled is enabled, by the fill of the item.
Line 1 A line drawn along the edge of the selected item: its bottom edge in a horizontal navbar and its leading edge in a vertical rail, the way a tab strip marks its current tab.
Pill 2 A pill drawn behind the icon of the selected item, which is how a Material navigation bar marks its current destination. It takes the fill off the item itself, so the pill is the only filled part.

BitAlignment enum

Name Value Description
Start 0 Packs the items at the start of the navbar.
End 1 Packs the items at the end of the navbar.
Center 2 Packs the items in the center of the navbar.
SpaceBetween 3 Spreads the items over the navbar, leaving no space before the first one and after the last one.
SpaceAround 4 Spreads the items over the navbar with equal space around each of them, which is what a horizontal navbar does on its own.
SpaceEvenly 5 Spreads the items over the navbar with equal space between them and at both of its ends.
Baseline 6 Carries no distribution of its own here, so the navbar keeps its default.
Stretch 7 Carries no distribution of its own here, so the navbar keeps its default. Use Justified to have the items fill the navbar.

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.