#Sidebar

A Sidebar is a vertical navigation for a settings screen, an inventory or the sections of an application. One item is the selected one, and your code shows the page for it.

How to add a sidebar:

<ui:VisualElement style="flex-direction: row; flex-grow: 1;">
    <tb:Sidebar name="nav" toggle-shortcut="Ctrl+B">
        <ui:VisualElement class="tb-sidebar__header">
            <ui:Button name="navToggle" text="≡" />
        </ui:VisualElement>
        <tb:SidebarGroup text="Game">
            <tb:SidebarItem name="general" text="General" selected="true" />
            <tb:SidebarItem name="controls" text="Controls" badge="2" />
            <tb:SidebarItem text="Video">
                <tb:SidebarItem name="display" text="Display" />
                <tb:SidebarItem name="quality" text="Quality" />
            </tb:SidebarItem>
        </tb:SidebarGroup>
        <ui:VisualElement class="tb-sidebar__footer">
            <ui:Label text="v1.0" />
        </ui:VisualElement>
    </tb:Sidebar>
    <ui:VisualElement name="pages" style="flex-grow: 1;" />
</ui:VisualElement>

var nav = root.Q<Sidebar>("nav");
nav.ItemSelected += item => ShowPage(item?.name);
root.Q<Button>("navToggle").clicked += nav.Toggle;

// Items from code
var account = new SidebarGroup("Account");
account.Add(new SidebarItem("Profile", profileIcon));
var friends = new SidebarItem("Friends");
friends.Badge.Count = 3;
friends.Badge.Tone = BadgeTone.Accent;
account.Add(friends);
nav.Add(account);
nav.Selected = friends;

Sidebar:

SidebarGroup:

SidebarItem:

• The children of a Sidebar are SidebarItem and SidebarGroup elements. The children of a SidebarGroup are items. The SidebarItem children of an item are its sub-items. Use one level of sub-items.
• A click on an item without sub-items selects it. A click on an item with sub-items expands or collapses it and does not select it.
• A click on the selected item raises nothing.
• A child of the sidebar with the class tb-sidebar__header is the header. A child with the class tb-sidebar__footer is the footer; it stays at the bottom. They can hold any element, such as a logo, a toggle button or a UserAvatar.
• In the icon-only mode, the group labels, the texts, the badges and the sub-items do not show. An item without an icon shows the first letter of its text. A click or Submit on an item with sub-items shows them in a flyout menu beside the item, with the text of the item as the heading. A pick selects the sub-item, and the sidebar stays narrow. A second click closes the flyout. The flyout opens to the right, or to the left for a sidebar on the right side.
• The place of the sidebar comes from its parent. Put it first in a row for the left side, and last with side="Right" for the right side.
• Keyboard and gamepad: Tab goes to the selected item, or to the first one. Up and Down move between the items that show. Right expands an item and Left collapses it. Left on a sub-item goes to its parent. Enter or the Submit button selects the item or expands it. At the first and the last item, Up and Down leave the items as usual. Left and Right on an item with nothing to expand or collapse move the focus as usual, so a gamepad goes from the sidebar to the page.
• The toggle shortcut works while the sidebar is on the panel. It does not run while a text field has the focus.
• A disabled item (enabled="false") shows dimmed, and the arrows pass over it.
• The sidebar does not scroll. For more items than fit, put the groups in a ScrollView child between the header and the footer. The ScrollView scrolls to the item that the arrow keys or Tab focus.

Tips:

• Give each item a name and use it to find the page, so a change of the text or a translation does not break the navigation.
• Give each top-level item an icon when you use the icon-only mode. A letter is only a fallback.
• Use a white image for an icon. The sheet tints it with the text color of the theme.
• Save Collapsed with your settings in CollapsedChanged, and set it again at the start.

#Styling

To make the sidebar wider and fill the selected row with the accent color:

.tb-sidebar { width: 260px; }
.tb-sidebar__item--selected > .tb-sidebar__row { background-color: var(--tb-color-accent); }
.tb-sidebar__item--selected > .tb-sidebar__row .tb-sidebar__text { color: var(--tb-color-accent-text); }