Nav

The nav renders the tree given to Items. A BitNavItem carries its Text, IconName, Description and Url; ChildItems make it expandable, and IsDisabled set to true disables it.

By default the nav takes the width of its container. FitWidth shrinks it to its widest item, and FullWidth stretches it over the whole container.

FitWidth

FullWidth

The Grouped render type turns the root items into group headers that expand and collapse their group instead of navigating. An item with IsSeparator draws a rule instead, grouping the items around it without a header; the keyboard skips it.

Grouped

Separator

The default Automatic mode selects the item that matches the current URL. The Manual mode leaves the selection to the app: a click selects, DefaultSelectedItem sets the initial item and @bind-SelectedItem keeps it in sync.

Basic

Two-Way Bind

IconOnly reduces the nav to a rail of icons. The text of each item stays available as its tooltip and as its accessible name.

SingleExpand keeps a single branch open at a time, like an accordion (ExpandAll does nothing in this mode). AllExpanded opens every branch on the first render. NoCollapse keeps every branch open and removes the chevrons with the space they reserve; a Grouped header then becomes a plain label.

SingleExpand

NoCollapse

ReversedChevron moves the chevron to the end of the item, and ChevronDownIconName (or ChevronDownIcon for an external library) replaces its icon. IndentValue is the padding added per level, IndentPadding the width of the chevron, which a childless item keeps in its place, and IndentReversedPadding replaces it while the chevron is reversed.

ReversedChevron

Custom chevron icon

IndentValue & IndentPadding

ItemTemplate and HeaderTemplate (Grouped) render the content of every item and group header. Their ItemTemplateRenderMode / HeaderTemplateRenderMode render the template inside the item's own link (Normal) or in its place (Replace), and the Template of a single item overrides both. A Normal template sits inside a link or a button, so keep controls (a checkbox, a button) out of it.

Header Template (Grouped)

Item Template

Item Template (Replace)

A reference to the nav drives it: ExpandAll / CollapseAll (the whole tree or one subtree), ExpandItem, CollapseItem, ToggleItem, IsItemExpanded, SelectItem, and FocusItem, which opens the path to an item before focusing it.

OnItemClick fires on every click, OnSelectItem when the selection changes, and OnItemToggle when a branch opens or closes. Reselectable fires the select events again for the item that is already selected.

In the Automatic mode the item whose URL matches the current page is selected. Match sets the rule for the whole nav, and the Match of an item overrides it: Exact, Prefix, Wildcard (? is one character but /, * any run of them, ** anything) or Regex. The query string is ignored, and Exact and Prefix also ignore the letter case and a trailing slash. AdditionalUrls gives an item more URLs to light up on. The navs below match the URL of this page.

Exact (the default)

Prefix

Wildcard

Regex

Match of an item & AdditionalUrls

The nav is a nav landmark: name it with AriaLabel when a page has more than one. The selected item carries aria-current (its AriaCurrent picks the value), a Description is announced as the item's description, and a parent reports aria-expanded. A parent without a URL toggles on a click anywhere on it; a parent with one navigates, so its chevron becomes a button of its own, named by ExpandAriaLabel / CollapseAriaLabel.

Keyboard: Tab moves between the items, ↑ ↓ Home End walk the visible ones, → opens a branch and then steps into it, ← closes it and then steps out, * opens every sibling, and typing jumps to the next item starting with it. Collapse Navs: the branch that holds the current page takes the look of the selection, so the reader never loses it.

BitParams hands a BitNavParams to every nav under it, as a default rather than an override: a nav that sets a parameter itself keeps its own value. What the nav is generic over (the items, the selection, the templates, the name selectors and the events) stays on each nav, so one cascade serves all three APIs.

Color paints the icons and the bar of the selected item. Accent paints the hovered and the selected item: a background, foreground or border role tints it, while a semantic role fills it and recolors what it holds.

Primary

Secondary

Tertiary

Info

Success

Warning

SevereWarning

Error

Accent:

Primary

Success

Warning

Error

Icon takes the CSS classes of an external icon library (FontAwesome, Bootstrap Icons, ...) and wins over IconName; ChevronDownIcon does the same for the chevron.

Size scales the height, text, icon, chevron and description of the items, and the height and text of the group headers.

Small

Medium

Large

Style and Class reach the root, the Style and Class of an item its list element, and Styles and Classes each part of the nav. The public CSS variables re-skin it without a selector; they inherit, so set them on an instance, on an ancestor or on :root. They restyle the default, not a choice: an explicit Color, Accent or Size wins over the variables for what it sets.

Component's Style & Class:

Item's Style & Class:

Styles & Classes:

CSS variables:

Dir set to Rtl mirrors the nav, its indentation and the arrow keys: → steps out of a branch and ← steps into it.