Nav

The nav renders the tree given to Items as a list of links. Each BitNavItem carries its Text, an optional IconName, Description and Url, and the items nested in its ChildItems turn it into an expandable node. An item with IsEnabled set to false is rendered but neither clickable nor selectable.

By default the nav takes the width its container gives it. FitWidth shrinks it to the width of its widest item, which is what a nav sitting next to other content usually wants, and FullWidth stretches it over the whole container.

FitWidth

FullWidth

The Grouped render type turns every root item into a group header: a full-width button with a bottom border that expands and collapses the group instead of navigating. Only the root level changes; everything below it keeps rendering as ordinary nav items.

An item with IsSeparator renders a horizontal rule in place of a link, which groups the items around it without giving that group a header. It is skipped by the keyboard navigation and reported to assistive technologies as a separator rather than as a nav item.

In the default Automatic mode the nav keeps the selection in sync with the current URL. The Manual mode hands that over to the app: the clicked item becomes the selected one, the initial selection comes from DefaultSelectedItem, and SelectedItem two-way binds the selection so it can be driven from anywhere else on the page.

Basic

Two-Way Bind

IconOnly collapses the nav to a rail of icons: the texts, the descriptions and the expand chevrons are all hidden, so only the icon of each item is left. The text still reaches the pointer as the item's tooltip and the screen reader through the item's accessible name.

SingleExpand turns the nav into an accordion: expanding a branch collapses the one that was open before it, so a deep tree never grows past a single open path. ExpandAll is a no-op while this mode is on, since it would break that rule.

AllExpanded opens every branch of the tree on the first render. NoCollapse goes further and removes the expand/collapse buttons altogether, together with the space they reserve at the start of each item, which is how a nav that is always fully open is rendered.

ReversedChevron moves the expand chevron to the trailing side of the item, and ChevronDownIconName (or ChevronDownIcon, for an external icon library) replaces the icon it renders while keeping its rotation. The indentation is arithmetic: IndentValue is the padding added per level of depth, IndentPadding is the space a childless item reserves in place of the chevron, and IndentReversedPadding replaces it while the chevron is reversed.

ReversedChevron

Custom chevron icon

IndentValue & IndentPadding

HeaderTemplate replaces the content of the group headers in the Grouped render type and ItemTemplate replaces the content of every ordinary item, both receiving the item as their context. The matching HeaderTemplateRenderMode and ItemTemplateRenderMode decide whether the template renders inside the item's own link (Normal) or takes its place entirely (Replace), and the Template of a single item overrides both for that item alone.

Header Template (Grouped)

Item Template

Item Template (Replace)

A reference to the nav exposes its state as methods: ExpandAll and CollapseAll open or close the whole tree (or a single subtree, when given an item), ExpandItem, CollapseItem and ToggleItem drive a single item, IsItemExpanded reports whether one is open, SelectItem selects one without a click, and FocusItem moves the keyboard focus to it, opening the branches it is nested in when it is not on screen yet.

OnItemClick fires for every click on an item, OnSelectItem only when the selection actually changes, and OnItemToggle when a branch is expanded or collapsed. Setting Reselectable makes the select events fire again for an item that is already selected.

In the Automatic mode the nav selects the item whose URL points at the current page. Match sets how those URLs are compared for the whole nav, 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. The comparison ignores the query string, and Exact and Prefix also ignore the letter case and a trailing slash; Wildcard and Regex run the pattern exactly as it was written, so those two tell the letter cases apart and see a trailing slash as a difference. AdditionalUrls gives an item other URLs to light up on. The navs below are all matched against the URL of this page.

Exact (the default)

Prefix

Wildcard

Regex

Match of an item & AdditionalUrls

Color paints the parts that carry the nav's identity: the icons and the border of the selected item. Accent is a separate role that paints the hovered and the selected item: a background, foreground or border role only tints it, so the colorful icon set shows through, while a semantic role fills it and takes its text and icon along. Both accept every value of BitColor, including the background, foreground and border roles that are not listed here.

Primary

Secondary

Tertiary

Info

Success

Warning

SevereWarning

Error

Accent:

Primary

Success

Warning

Error

Besides the built-in icons of IconName, the Icon parameter of an item accepts the CSS classes of any external icon library, such as FontAwesome or Bootstrap Icons, and takes precedence over IconName. The same applies to the ChevronDownIcon of the nav itself.

Size scales the metrics of every part of the nav at once: the height of the items, the size of their text and description, and the height and text of the group headers.

Small

Medium

Large

Style and Class reach the root element, the Style and Class of an item reach the list element of that item, and the Styles and Classes objects reach every part of the nav separately: the root, the item container and its selected variant, the item and its selected variant, the item icon and text, the toggle button and its chevron icon, the description, the group header and its text, and the separator.

Component's Style & Class:

Item's Style & Class:

Styles & Classes:

Setting Dir to Rtl flips the nav and everything it renders: the chevrons, the indentation of the levels and the direction of the arrow keys, so the Right arrow steps out of a branch and the Left arrow steps into it.