Extras
NavPanel
The panel is a permanent column on a wide screen and an off-canvas drawer below the md breakpoint (see DrawerBreakpoint), opened by IsOpen. The Open button above each example only shows on a small screen.
Notes
Usage
Every example is live. Open its code to see exactly what produced the component running underneath.
Basic
Width
Rail
Logo
Search
Selection
Expansion
Custom items
Drawer
Templates
Events
Toggled item:
Public APIs
Grouped
- Home
- Todo
- Terms
StickyEnds
Cascading parameters
Color
External Icons
Size
Style & Class
:root for the whole app or on a panel's Style for one
(the BitNav ones, like --bit-Nav-item-radius, work the same way).
RTL
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.
BitNavPanel CSS variables
| Name | Default value | Description |
|---|---|---|
| --bit-NavPanel-background | --bit-clr-bg-pri | Fill of the panel. Accent paints its content over it. |
| --bit-NavPanel-width | auto | Width of the open panel. The Width parameter wins; FitWidth and FullWidth ignore it. |
| --bit-NavPanel-toggled-width | 96px (64px on the drawer, 48px with NoPad) | Width of the rail. The ToggledWidth parameter wins. |
| --bit-NavPanel-padding | 16px (0 on the drawer) | Inset of the panel. NoPad removes it. |
| --bit-NavPanel-container-padding | 8px | Inset of the content inside the panel. NoPad removes it. |
| --bit-NavPanel-gap | 16px | Space between the header, the search box, the items and the footer. |
| --bit-NavPanel-radius | var(--bit-shp-radius-sheet) | Corner radius of the panel, for a floating sidebar. |
| --bit-NavPanel-border-width | 0 | Width of the rule along the edge the panel turns to the page (the inline end, or the inline start with Placement End). A forced-colors mode always draws it. |
| --bit-NavPanel-border-color | --bit-clr-brd-sec | Color of that rule. |
| --bit-NavPanel-header-icon-size | 38px | Largest width and height of the logo of IconUrl. |
| --bit-NavPanel-shadow | none | Elevation of the column of a wide screen, for a floating panel (with the radius and the border). |
| --bit-NavPanel-drawer-shadow | --bit-shd-sheet | Elevation of the drawer. |
| --bit-NavPanel-overlay-background | --bit-clr-bg-overlay | Fill of the overlay behind the drawer. The overlay sits beside the panel, so set it on an ancestor or :root. |
| --bit-NavPanel-overlay-backdrop-filter | none | Filter over the page behind the overlay, e.g. blur(4px). Set it on an ancestor or :root. |
API
Every parameter, public member, sub-class and enum this component exposes.
BitNavPanel parameters
| Name | Type | Default value | Description |
|---|---|---|---|
| Accent | BitColor? | null | The accent color of the nav panel: it paints the background of the panel and of the hovered and the selected item. |
| AllExpanded | bool | false | Expands all items on first render. |
| AutoFocus | bool | false | Moves the focus onto the search box of the drawer as it opens (or onto the first item of a panel without one) instead of onto the drawer itself, where a modal drawer puts it otherwise. Off by default because focusing an input opens the on-screen keyboard of a touch device. |
| ChevronDownIcon | BitIconInfo? | null | The icon of the chevron-down element of each nav item, for icons of external libraries. It takes precedence over ChevronDownIconName. |
| ChevronDownIconName | string? | null | The custom icon name of the chevron-down element of each nav item. |
| Classes | BitNavPanelClassStyles? | null | Custom CSS classes for different parts of the nav panel. |
| CollapseAriaLabel | string? | null | The default aria-label of the expand/collapse button of an expanded item of the nav. |
| CloseAriaLabel | string? | null | The aria-label and the tooltip of the close button of the nav panel. |
| CloseIcon | BitIconInfo? | null | The icon of the close button of the nav panel. Takes precedence over CloseIconName when both are set. |
| CloseIconName | string? | null | The name of the icon of the close button of the nav panel. |
| Color | BitColor? | null | The general color of the nav. |
| DefaultSelectedItem | TItem? | null | The initially selected item of the nav in manual mode. |
| DrawerBreakpoint | BitNavPanelBreakpoint? | null | The screen width below which the panel turns into an off-canvas drawer opened by IsOpen. Never keeps it a column on every screen and Always makes it a drawer on every screen. The default (null) is Md. |
| EmptyListTemplate | RenderFragment? | null | The custom template for when the search result is empty. |
| EmptyListMessage | string? | null | The custom message for when the search result is empty. |
| ExpandAriaLabel | string? | null | The default aria-label of the expand/collapse button of a collapsed item of the nav. |
| ExpandOnHover | bool | false | Expands the toggled (rail) nav panel back to its full width while the pointer is over it. |
| FitWidth | bool | false | Renders the nav panel with fit-content width. The width is then the items' rather than the panel's, so this is the one mode whose toggle resizes the panel in a single step instead of travelling between the two widths. |
| Footer | RenderFragment? | null | The custom template to render as the footer of the nav panel. |
| FullWidth | bool | false | Renders the nav panel with full (100%) width. |
| Header | RenderFragment? | null | The custom template to render as the header of the nav panel. It replaces the built-in buttons of the header too, so call Toggle / Close from a control of its own. |
| HeaderText | string? | null | The title shown beside the logo in the header - typically the name of the app. It is part of the IconNavUrl link and names it, is hidden in the rail, and keeps the built-in buttons of the header. |
| HeaderTemplate | RenderFragment<TItem>? | null | Used to customize how content inside the group header is rendered. |
| HeaderTemplateRenderMode | BitNavItemTemplateRenderMode | BitNavItemTemplateRenderMode.Normal | The render mode of the custom HeaderTemplate. |
| HideToggle | bool | false | Removes the toggle button. |
| IconAriaLabel | string? | null | The accessible name of the logo in the header of the nav panel: the name of the link an IconNavUrl wraps it in, and the alternative text of the image otherwise. Falls back to AriaLabel and then to a built-in name; beside a HeaderText the title names the link instead. |
| IconNavUrl | string? | null | Renders an anchor wrapping the icon (and the HeaderText) to navigate to the specified url. |
| IconUrl | string? | null | The icon url to show in the header of the nav panel. |
| IndentValue | int | 16 | The indentation value in px for each level of depth of child item. |
| IndentPadding | int | 27 | The width in px of the chevron, which the items without children keep as padding in its place so every text lines up. |
| IndentReversedPadding | int | 4 | The indentation padding in px for items in reversed mode. |
| IsOpen | bool | false | Determines if the nav panel is open while it is an off-canvas drawer (see DrawerBreakpoint). |
| IsToggled | bool | false | Determines if the nav panel is in the toggled state. |
| Items | IList<TItem> | [] | A collection of items to display in the nav panel. |
| ItemTemplate | RenderFragment<TItem>? | null | Used to customize how content inside the item is rendered. |
| ItemTemplateRenderMode | BitNavItemTemplateRenderMode | BitNavItemTemplateRenderMode.Normal | The render mode of the custom ItemTemplate. |
| NameSelectors | BitNavNameSelectors<TItem>? | null | Names and selectors of the custom input type properties. |
| NavClasses | BitNavClassStyles? | null | Custom CSS classes for different parts of the nav component of the nav panel. |
| NavMatch | BitNavMatch? | null | Determines the global URL matching behavior of the nav. |
| NavMode | BitNavMode | BitNavMode.Automatic | Determines how the navigation will be handled. |
| NavStyles | BitNavClassStyles? | null | Custom CSS styles for different parts of the nav component of the nav panel. |
| NoAutoClose | bool | false | Keeps the nav panel open when an item with a URL is clicked, instead of closing it. |
| NoCollapse | bool | false | Keeps every item of the nav expanded and hides its collapse/expand buttons. |
| NoFocusTrap | bool | false | Stops the open drawer of a small screen from taking the focus as it opens and holding it inside itself. The focus is only ever held while the panel covers the page, which is the state its overlay is rendered in. |
| NoOverlay | bool | false | Removes the overlay that is rendered behind the open nav panel in small screens. Without it the drawer no longer covers the page: it stops holding the focus and the page behind it keeps scrolling. |
| NoPad | bool | false | Disables the padded mode of the nav panel. |
| NoRestoreFocus | bool | false | Stops the closing drawer of a small screen from handing the focus back to the element that had it when the drawer opened. Only ever read by a panel that took the focus in the first place: a modal drawer, or one with AutoFocus. |
| NoScrollLock | bool | false | Lets the page behind the open drawer of a small screen keep scrolling. The page is only ever held while the panel covers it, which is the state its overlay is rendered in. |
| NoSearchBox | bool | false | Removes the search box from the nav panel. |
| NoSwipe | bool | false | Disables the swipe gesture that closes the open nav panel in small screens. |
| NoToggle | bool | false | Disables the toggle feature of the nav panel. |
| OnItemClick | EventCallback<TItem> | Event fired up when an item is clicked. | |
| OnItemToggle | EventCallback<TItem> | Callback invoked when a group header is clicked and Expanded or Collapse. | |
| OnSearch | EventCallback<string?> | Callback invoked when the search text of the nav panel changes. | |
| OnSelectItem | EventCallback<TItem> | Callback invoked when an item is selected. | |
| Placement | BitPlacement? | null | The edge the off-canvas drawer of a small screen comes from, and the side it is docked to while it is open. Honours Start and End, which follow the text direction; every other value renders the default Start. It has no effect on a wide screen, where the panel is a column in the normal flow of the page. |
| RenderType | BitNavRenderType | BitNavRenderType.Normal | The way to render nav items. |
| Reselectable | bool | false | Enables recalling the select events when the same item is selected. |
| ReversedChevron | bool | false | Reverses the location of the expander chevron. |
| SearchBoxClasses | BitSearchBoxClassStyles? | null | Custom CSS classes for different parts of the search box of the nav panel. |
| SearchBoxPlaceholder | string? | null | The placeholder of the input element of the search box of the nav panel. |
| SearchBoxStyles | BitSearchBoxClassStyles? | null | Custom CSS styles for different parts of the search box of the nav panel. |
| SearchAnnouncementProvider | Func<int, string?>? | null | Builds the text that the screen reader announces through the live region of the nav panel whenever the search filters the items, in place of the built-in English announcement. The argument is the number of matched items. |
| SearchDebounceTime | int | 500 | The debounce time in milliseconds of the search box of the nav panel. |
| SearchFilter | Func<TItem, string, bool>? | null | The custom function to decide whether an item matches a search term, replacing the default matching over the text, the description and the data of an item. |
| SearchIcon | BitIconInfo? | null | The icon of the button that the collapsed (rail) nav panel shows in place of its search box. Takes precedence over SearchIconName when both are set. |
| SearchIconName | string? | null | The name of the icon of the button that the collapsed (rail) nav panel shows in place of its search box. |
| SearchText | string? | null | The search text of the nav panel that filters its items. |
| SelectedItem | TItem? | null | The selected item of the nav in manual mode. |
| SingleExpand | bool | false | Enables the single-expand mode in the BitNav. |
| ShowCloseButton | bool | false | Renders a close button in the header of the nav panel, on the screens the panel is an off-canvas drawer on. It is the control the toggle button is not: the toggle collapses a permanent panel into a rail, which a drawer that is either open or gone has no state for. |
| Size | BitSize? | null | The size of the nav items. |
| StickyEnds | bool | false | Pins the two ends of the nav panel - the header with its search box, and the footer - in place and scrolls only the items between them, instead of scrolling the whole panel as one. |
| Styles | BitNavPanelClassStyles? | null | Custom CSS styles for different parts of the nav panel. |
| ToggleAriaLabel | string? | null | The aria-label of the toggle button of the nav panel. |
| ToggledWidth | int | 0 | The width of the nav panel in px in its toggled (rail) state. |
| ToggleIcon | BitIconInfo? | null | The icon of the toggle button of the nav panel. It takes precedence over ToggleIconName. |
| ToggleIconName | string? | null | The name of the icon of the toggle button of the nav panel. |
| Top | int | 0 | The top CSS property value of the root element of the nav panel in px. |
| Width | int | 0 | The width of the nav panel in px. It is ignored in the FitWidth and FullWidth modes. |
BitNavPanel public members
| Name | Type | Default value | Description |
|---|---|---|---|
| ClearSearch | Task | Clears the search text of the nav panel, so the whole list of items is shown again. | |
| Close | Task | Closes the nav panel. | |
| CollapseAll | void | Collapses all items of the nav. | |
| CollapseItem | Task | Collapses an item of the nav, and does nothing when it is already collapsed. | |
| ExpandAll | void | Expands all items of the nav in non-SingleExpand mode. | |
| ExpandItem | Task | Expands an item of the nav, and does nothing when it is already expanded. | |
| FocusItem | ValueTask | Moves the focus to an item of the nav, opening the branches it is nested in when it is not rendered yet. | |
| FocusSearchBox | Task | Moves the focus to the search box of the nav panel, opening the panel out of its toggled state first when the search box is not on screen. | |
| IsItemExpanded | bool | Whether an item of the nav is currently expanded. | |
| Open | Task | Opens the nav panel. | |
| SelectItem | Task | Selects an item of the nav programmatically, exactly like a click on that item would in the manual mode. | |
| Toggle | Task | Toggles the nav panel if possible. | |
| ToggleItem | Task | Toggles an item of the nav. |
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. |
BitNavPanelClassStyles properties
| Name | Type | Default value | Description |
|---|---|---|---|
| Overlay | string? | null | Custom CSS classes/styles for the overlay of the BitNavPanel. |
| Root | string? | null | Custom CSS classes/styles for the root element of the BitNavPanel. |
| Toggled | string? | null | Custom CSS classes/styles for the root element of the BitNavPanel when toggled. |
| Container | string? | null | Custom CSS classes/styles for the container of the BitNavPanel. |
| Header | string? | null | Custom CSS classes/styles for the header container of the BitNavPanel. |
| HeaderIcon | string? | null | Custom CSS classes/styles for the header icon of the BitNavPanel. |
| HeaderText | string? | null | Custom CSS classes/styles for the header text (title) of the BitNavPanel. |
| ToggleButton | string? | null | Custom CSS classes/styles for the toggle button of the BitNavPanel. |
| CloseButton | string? | null | Custom CSS classes/styles for the close button of the BitNavPanel. |
| SearchBox | string? | null | Custom CSS classes/styles for the search box of the BitNavPanel. |
| ToggleSearchButton | string? | null | Custom CSS classes/styles for the toggle search button of the BitNavPanel. |
| EmptyListMessage | string? | null | Custom CSS classes/styles for the empty list message of the BitNavPanel. |
| Nav | string? | null | Custom CSS classes/styles for the nav component of the BitNavPanel. |
BitNavNameSelectors<TItem> properties
| Name | Type | Default value | Description |
|---|---|---|---|
| AriaCurrent | BitNameSelectorPair<TItem, BitNavAriaCurrent?> | new(nameof(BitNavItem.AriaCurrent)) | The AriaCurrent field name and selector of the custom input class. |
| AriaLabel | BitNameSelectorPair<TItem, string?> | new(nameof(BitNavItem.AriaLabel)) | The AriaLabel field name and selector of the custom input class. |
| Class | BitNameSelectorPair<TItem, string?> | new(nameof(BitNavItem.Class)) | The Class field name and selector of the custom input class. |
| ChildItems | BitNameSelectorPair<TItem, List<TItem>?> | new(nameof(BitNavItem.ChildItems)) | The ChildItems field name and selector of the custom input class. |
| CollapseAriaLabel | BitNameSelectorPair<TItem, string?> | new(nameof(BitNavItem.CollapseAriaLabel)) | The CollapseAriaLabel field name and selector of the custom input class. |
| Data | BitNameSelectorPair<TItem, object?> | new(nameof(BitNavItem.Data)) | The Data field name and selector of the custom input class. |
| Description | BitNameSelectorPair<TItem, string?> | new(nameof(BitNavItem.Description)) | The Description field name and selector of the custom input class. |
| ExpandAriaLabel | BitNameSelectorPair<TItem, string?> | new(nameof(BitNavItem.ExpandAriaLabel)) | The ExpandAriaLabel field name and selector of the custom input class. |
| ForceAnchor | BitNameSelectorPair<TItem, bool?> | new(nameof(BitNavItem.ForceAnchor)) | The ForceAnchor field name and selector of the custom input class. |
| Icon | BitNameSelectorPair<TItem, BitIconInfo?> | new(nameof(BitNavItem.Icon)) | The Icon field name and selector of the custom input class. |
| IconName | BitNameSelectorPair<TItem, string?> | new(nameof(BitNavItem.IconName)) | The IconName field name and selector of the custom input class. |
| IsDisabled | BitNameSelectorPair<TItem, bool?> | new(nameof(BitNavItem.IsDisabled)) | The IsDisabled field name and selector of the custom input class. |
| IsExpanded | BitNameSelectorPair<TItem, bool?> | new(nameof(BitNavItem.IsExpanded)) | The IsExpanded field name and selector of the custom input class. |
| IsSeparator | BitNameSelectorPair<TItem, bool?> | new(nameof(BitNavItem.IsSeparator)) | The IsSeparator field name and selector of the custom input class. |
| Key | BitNameSelectorPair<TItem, string?> | new(nameof(BitNavItem.Key)) | The Key field name and selector of the custom input class. |
| Match | BitNameSelectorPair<TItem, BitNavMatch?> | new(nameof(BitNavItem.Match)) | The Match field name and selector of the custom input class. |
| Style | BitNameSelectorPair<TItem, string?> | new(nameof(BitNavItem.Style)) | The Style field name and selector of the custom input class. |
| Target | BitNameSelectorPair<TItem, string?> | new(nameof(BitNavItem.Target)) | The Target field name and selector of the custom input class. |
| Template | BitNameSelectorPair<TItem, RenderFragment<TItem>?> | new(nameof(BitNavItem.Template)) | The Template field name and selector of the custom input class. |
| TemplateRenderMode | BitNameSelectorPair<TItem, BitNavItemTemplateRenderMode?> | new(nameof(BitNavItem.TemplateRenderMode)) | The TemplateRenderMode field name and selector of the custom input class. |
| Text | BitNameSelectorPair<TItem, string?> | new(nameof(BitNavItem.Text)) | The Text field name and selector of the custom input class. |
| Title | BitNameSelectorPair<TItem, string?> | new(nameof(BitNavItem.Title)) | The Title field name and selector of the custom input class. |
| Url | BitNameSelectorPair<TItem, string?> | new(nameof(BitNavItem.Url)) | The Url field name and selector of the custom input class. |
| AdditionalUrls | BitNameSelectorPair<TItem, IEnumerable<string>?> | new(nameof(BitNavItem.AdditionalUrls)) | The AdditionalUrls 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. |
BitColor enum
| Name | Value | Description |
|---|---|---|
| Primary | 0 | Info 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.