# Blazor Toolbar and App Bar

URL: https://flexcoreui.com/demo/toolbar  
Section: Components  
Controls: ToolbarControl, ToolbarButtonControl, ToolbarSeparatorControl, AppBarControl  
Keywords: toolbar, command bar, app bar, title bar, tool buttons

A Blazor toolbar: a row of command buttons with icons, captions users can hide, separators and large tiles, under an app bar that can stay in view.

## Documentation

### Toolbar

| Name | Type | Default | Description |
|---|---|---|---|
| ChildContent | RenderFragment? | null | The items, in a row that wraps when there is not enough room. |
| TrailingContent | RenderFragment? | null | Right-hand area, after the Captions checkbox. It does not shrink or wrap. |
| ShowCaptions | bool? | null | Shows or hides the buttons' Label captions. Null lets the toolbar keep its own state, read from the preference service when there is one and true otherwise; a value wins over that state, so update it from ShowCaptionsChanged. |
| ShowCaptionsToggle | bool | true | Draws the Captions checkbox at the right. Pass false on a toolbar whose items are not ToolbarButtonControls with labels, where the checkbox would hide nothing. |
| CaptionsToggleLabel | string | "Captions" | Text beside the checkbox. |
| PreferenceKey | string? | null | Name for storing the captions setting; Toolbar when blank, so toolbars without a key share one. FlexCore defines no storage or interface: declare and register an Fx.ControlKit.IUserPreferencesService with GetBool(string, string, bool) and PutBool(string, string, bool). The toolbar calls them by reflection with ("Toolbar", "key.Captions", …): a read at start when ShowCaptions is null, a write on every toggle. Without it the setting lasts as long as the component. |
| EffectiveShowCaptions | bool |  | Read-only. ShowCaptions when set, else the toolbar's own state. |
| Role | string | "toolbar" | ARIA role of the root. |
| CssClass | string | string.Empty | Added to fx-toolbar; see the classes below for fx-toolbar--wrap, fx-toolbar--scroll and fx-toolbar--large-tools. |
| (no base class) |  |  | It does not inherit FlexControlBase: there is no Id, Style or Visible, and any other attribute, such as id or aria-label, throws when the page renders. Wrap the toolbar in your own element to style or name it. |

### Button

| Name | Type | Default | Description |
|---|---|---|---|
| Label | string | string.Empty | Caption, in a span that is hidden with the captions. Ignored on screen when ChildContent is set, but still used for the name. |
| IconCss | string | string.Empty | Classes for an aria-hidden icon span before the caption, such as bi bi-save. The span is an 18px box (56px on a Large button), so set the font size of a font icon in your CSS; the examples use 16px with an 18px line height, and 46px on the Large tiles. |
| IconSrc | string | string.Empty | Image address for an icon; wins over IconCss. |
| IconAlt | string | string.Empty | Alt text of the IconSrc image; also the name when there is no Title or Label. |
| Title | string | string.Empty | Tooltip and aria-label; when blank, Label, then IconAlt. |
| ShowTooltip | bool | true | False drops the title tooltip and keeps the aria-label. Ignored while the parent toolbar's captions are off. |
| Vertical | bool | false | Icon above the caption, at least 56px wide. No effect while captions are off. |
| Large | bool | false | A tile at least 110 by 108px with a 56px icon box and a 24px caption. Add Vertical to put the icon above the caption. Keep captions on: with captions off the tile is forced to 30px high and its 56px icon box overflows it. |
| Selected | bool | false | Adds fx-toolbar-btn--selected and aria-pressed="true". The library stylesheet styles it only on Large buttons. |
| Disabled | bool | false | Native disabled, drawn at half opacity. |
| HasDropdown | bool | false | Draws a small arrow after the caption. That is all: no menu opens, so the host renders and positions its own. |
| Dropdown | bool | false | Same as HasDropdown. |
| ChildContent | RenderFragment? | null | Replaces the Label span, and stays visible with captions off. |
| Type | string | "button" | The button's type. |
| ParentToolbar | ToolbarControl? | null | Cascading parameter, set by the surrounding ToolbarControl; it is what forces the tooltip on while captions are off. Null for a button used outside a toolbar. |
| CssClass | string | string.Empty | Added to fx-toolbar-btn. |
| (no base class) |  |  | It does not inherit FlexControlBase; any other attribute, such as id or aria-expanded, throws when the page renders. |

### Events

| Name | Type | Description |
|---|---|---|
| ToolbarControl.ShowCaptionsChanged | bool | When the Captions checkbox is toggled, with the new state; the toolbar also saves it through PreferenceKey. |
| ToolbarButtonControl.OnClick | none | A click, Enter or Space on the button; not raised while Disabled. |

### Separator

| Name | Type | Default | Description |
|---|---|---|---|
| CssClass | string | string.Empty | Added to fx-toolbar-separator. The control takes no other parameter, and any other attribute throws when the page renders. |

### App bar

| Name | Type | Default | Description |
|---|---|---|---|
| Position | AppBarPosition | AppBarPosition.Static | Written as the header's CSS position; see the values below. |
| Bottom | bool | false | Writes bottom:0 instead of top:0, which matters for Sticky and Fixed. |
| ZIndex | int | 100 | z-index of the header. |
| StartContent | RenderFragment? | null | Left group, items 8px apart. |
| ChildContent | RenderFragment? | null | Middle group; takes the remaining width and centers its content. |
| EndContent | RenderFragment? | null | Right group, items 8px apart. |
| Visible (base) | bool | true | False adds display:none. |
| Enabled / Title / Tag / Data / Parent (base) |  |  | Accepted but not read by the app bar. |
| Id / CssClass / Style (base) | string? | null | On the header.fx-app-bar; Style comes after the position, offset and z-index. |
| (unmatched attributes) | Dictionary<string,object>? | null | Written on the header after its own attributes, so a class passed this way replaces fx-app-bar; use CssClass. id and style are not unmatched: parameter names ignore case, so they bind to Id and Style. |

### Position

| Name | Description |
|---|---|
| Static | In the normal flow; the offset has no effect. |
| Sticky | Scrolls with the content until it reaches the top (or, with Bottom, the bottom) of its nearest scrolling ancestor, then stays there while its parent element is in view. |
| Fixed | Pinned to the top (or bottom) of the viewport across its full width. It takes no room in the flow, so leave space for it. |

### Css

| Name | Description |
|---|---|
| fx-toolbar | Root: a bordered light gray row, at least 44px high, full width, 4px below it. |
| fx-toolbar-items | Holds the items; wraps onto more rows when the toolbar is too narrow. |
| fx-toolbar-trailing | Right-hand block for the Captions checkbox and TrailingContent. |
| fx-toolbar-captions-toggle | The Captions checkbox and its label. |
| fx-toolbar--no-captions | On the root while captions are off; at least 36px high. |
| fx-toolbar--wrap | For CssClass: lets the trailing block drop below the items. |
| fx-toolbar--scroll | For CssClass: scrolls sideways when the content cannot fit, and clips anything that hangs below the toolbar. Items still wrap first. |
| fx-toolbar--large-tools | For CssClass: white, no border or bottom margin, at least 128px high, 12px by 18px padding; for Large buttons. |
| fx-toolbar-btn | A button: no border until hover, at least 32px high, 11px text. |
| fx-toolbar-btn--vertical · --large · --selected | Added by Vertical, Large and Selected. |
| fx-toolbar-btn-icon · fx-toolbar-btn-label · fx-toolbar-btn-arrow | The icon box, the caption span and the HasDropdown arrow. |
| fx-toolbar-icon-pointer · fx-toolbar-icon-text | Two icons drawn in CSS for IconCss on a Large button: an arrow pointer and a serif T. Not used in this page's examples. |
| fx-toolbar-separator | The separator line. |
| fx-app-bar | The app bar's header: the surface color, a bottom border, 8px by 12px padding. |
| fx-app-bar-toolbar | The toolbar inside the app bar. No library rule: it keeps the gray, bordered fx-toolbar look, at least 44px high; the third example clears it with min-height: 0; margin: 0; background: transparent; border: 0;. |
| fx-app-bar-start · fx-app-bar-center · fx-app-bar-end | The three areas. |

## Examples

### Commands

```razor
@using Fx.ControlKit

<SwitchControl @bind-Checked="_vertical" Label="Vertical buttons" />

<div class="tb">
    <ToolbarControl CssClass="fx-toolbar--wrap" ShowCaptions="_captions" ShowCaptionsChanged="on => _captions = on">
        <ChildContent>
            <ToolbarButtonControl Label="Add an hour" IconCss="bi bi-plus-circle" Vertical="_vertical" OnClick="() => Hours(1)" />
            <ToolbarButtonControl Label="Drop an hour" IconCss="bi bi-dash-circle" Vertical="_vertical" Disabled="@(_hours == 2)" OnClick="() => Hours(-1)" />
            <ToolbarButtonControl Label="Save" IconCss="bi bi-save" Vertical="_vertical" Disabled="!_dirty" OnClick="() => _dirty = false" />
            <ToolbarSeparatorControl />
            <ToolbarButtonControl Label="Priority" Title="Priority: put this task at the top of the board" IconCss="bi bi-pin-angle" Vertical="_vertical"
                                  Selected="_priority" OnClick="TogglePriority" />
            <ToolbarButtonControl Label="Web form" IconSrc="images/toolbar-globe.svg" IconAlt="Web form" Vertical="_vertical"
                                  Selected="_source" OnClick="() => _source = !_source" />
            <ToolbarSeparatorControl />
            <ToolbarButtonControl Title="Share" IconCss="bi bi-share" Vertical="_vertical" OnClick="() => _shared++">Share</ToolbarButtonControl>
        </ChildContent>
        <TrailingContent>
            <BadgeControl Text="@Total.ToString("C0")" Variant="BadgeVariant.Info" />
        </TrailingContent>
    </ToolbarControl>
    <div class="tb-task" role="status">
        <strong>WEB-123 Photo gallery for Green Fork Cafe</strong>
        <span>@_hours hours · @Total.ToString("C0")</span>
        @if (_priority) { <BadgeControl Text="Priority" Variant="BadgeVariant.Warning" /> }
        <BadgeControl Text="@(_dirty ? "Unsaved" : "Saved")" Variant="@(_dirty ? BadgeVariant.Warning : BadgeVariant.Success)" />
        @if (_source) { <span class="tb-note">The client asked for it through the web form on Monday.</span> }
        @if (_shared > 0) { <span class="tb-note">Shared with the client @_shared time@(_shared == 1 ? "" : "s").</span> }
    </div>
</div>
```

```csharp
// Commands
private bool _captions = true, _vertical, _priority, _dirty, _source;
private int _hours = 3, _shared;
private decimal Total => 95 * _hours;
private void Hours(int change)
{
    _hours += change;
    _dirty = true;
}
private void TogglePriority()
{
    _priority = !_priority;
    _dirty = true;
}
```

### Tiles

```razor
@using Fx.ControlKit

<div class="tools">
    <ToolbarControl CssClass="fx-toolbar--large-tools" ShowCaptionsToggle="false">
        @foreach (var label in _labels)
        {
            <ToolbarButtonControl Large="true" Vertical="true" Label="@label.Name" IconCss="@label.Icon"
                                  Selected="@(_label == label)" OnClick="() => _label = label" />
        }
    </ToolbarControl>
    <p class="tb-status" role="status">@_label.Name: @string.Join(", ", _label.Tasks)</p>
</div>
```

```csharp
// Tiles
private sealed record TaskLabel(string Name, string Icon, string[] Tasks);
private static readonly TaskLabel[] _labels =
{
    new("Design", "bi bi-palette", new[] { "WEB-101 Style guide", "WEB-102 Logo refresh" }),
    new("Frontend", "bi bi-code-slash", new[] { "WEB-117 Order form", "WEB-123 Photo gallery" }),
    new("Content", "bi bi-card-text", new[] { "WEB-121 Menu copy", "WEB-122 About page" }),
};
private TaskLabel _label = _labels[0];
```

### App bar

```razor
@using Fx.ControlKit
@using Fx.ControlKit.Layout

<SwitchControl @bind-Checked="_sticky" Label="Sticky app bar" />

<div class="qd">
    <AppBarControl Position="@(_sticky ? AppBarPosition.Sticky : AppBarPosition.Static)">
        <StartContent><SvgIconControl Name="document" Size="20px" /><strong>QA desk</strong></StartContent>
        <ChildContent><span class="qd-sub">Website relaunch · WEB-@(_task) · Hermione Ranger</span></ChildContent>
        <EndContent><BadgeControl Text="@(_deskDirty ? "Unsaved" : "Saved")" Variant="@(_deskDirty ? BadgeVariant.Warning : BadgeVariant.Success)" /></EndContent>
    </AppBarControl>
    <ToolbarControl CaptionsToggleLabel="Button text">
        <ToolbarButtonControl Label="New task" IconCss="bi bi-file-earmark-plus" OnClick="NewTask" />
        <ToolbarButtonControl Label="Save" IconCss="bi bi-save" Disabled="!_deskDirty" OnClick="SaveTask" />
        <ToolbarSeparatorControl />
        <span class="qd-export">
            <ToolbarButtonControl Label="Export" IconCss="bi bi-box-arrow-up" HasDropdown="true"
                                  OnClick="() => _exportOpen = !_exportOpen" />
            @if (_exportOpen)
            {
                <div class="qd-backdrop" @onclick="() => _exportOpen = false"></div>
                <div class="qd-menu">
                    <ButtonControl CssClass="qd-menu-item" OnClick='() => Desk("Export › PDF report")'>PDF report</ButtonControl>
                    <ButtonControl CssClass="qd-menu-item" OnClick='() => Desk("Export › CSV checklist")'>CSV checklist</ButtonControl>
                </div>
            }
        </span>
        <ToolbarButtonControl Label="Print" IconCss="bi bi-printer" OnClick='() => Desk("Print")' />
    </ToolbarControl>
    <p class="tb-status" role="status">Last action: @_deskLast</p>
    <div class="qd-label">QA notes, task WEB-@(_task)</div>
    <TextBoxControl @bind-Value="_notes" @bind-Value:after="MarkDirty" UpdateOnInput="true" Multiline="true" Rows="10" Width="100%" aria-label="QA notes" />
</div>
```

```csharp
// App bar
private bool _sticky = true, _exportOpen, _deskDirty;
private int _task = 123;
private string _deskLast = "none yet";
private string _notes = "Checked WEB-123 on Thursday: the photo gallery on a phone and a laptop, Sprint 8 build.\nCaptions wrap onto a second line on narrow screens.\nPhotos have no alt text; asked Luna Goodlove for the wording.";
private void Desk(string action)
{
    _exportOpen = false;
    _deskLast = action;
}
private void NewTask()
{
    Desk("New task");
    _task++;
    _notes = "";
    _deskDirty = true;
}
private void SaveTask()
{
    Desk("Save");
    _deskDirty = false;
}
private void MarkDirty() => _deskDirty = true;
```

