TopBar
The bar over a dashboard's page: search at its start, icon actions and a round create button at its end.
import { TopBar } from "@butteryui/react";Demo
When to use it
Use it for
- The top of an AppShell layout="sidebar", over every page
- App-wide search with a / shortcut, notifications and a create button
Not for
- A page's own title and actions: use PageHeader
- An editor's title bar: use HeaderBar
- A marketing site's bar: use NavBar
Examples
Dashboard top bar
A dashboard's top bar over its page: the search filters the orders, Help shows a tip and New order adds one.
Orders
Order 1042, Corner Café
Guji, 2 kg
Order 1043, Ines Moreau
Decaf Huila, 250 g
Order 1044, Hill Street Bakery
Cerrado, 5 kg
Plain top bar
A top bar with no search: just its actions and the create button.
Variants and states
Search, actions and create
Narrow the page and the icon actions fold into …; the create button stays.
Props
TopBar
| Prop | Type | Default | Description |
|---|---|---|---|
search | ReactNode | The search at the bar's start: a CommandSearch, 360px at rest and 600 while it has focus, or a soft
SearchField with a shortcut, at most 360px. | |
actions | ReactNode | Icon actions at the end, TopBar.Actions, which fold into "…" when they don't fit. | |
create | TopBarCreate | The round create button after the actions. | |
menuLabel | string | "Open navigation" | Names the button that opens the sidebar on a phone. Defaults to "Open navigation". |
moreLabel | string | "More app actions" | Names the button that lists the actions that don't fit. Defaults to "More app actions". |
It also takes ComponentPropsWithRef<"div">.
TopBar.Action
| Prop | Type | Default | Description |
|---|---|---|---|
labelrequired | string | What it does, such as "Notifications". It's the button's name and tooltip, and its menu item once folded. | |
iconrequired | ComponentType<IconComponentProps> | Its icon. | |
onSelectrequired | () => void | Runs it, from the bar or from the "…" menu. | |
dot | boolean | Draws a dot for something new behind it, which its name says too, in the bar and in the "…" menu. | |
priority | number | 0 | Higher stays in the bar longer. Defaults to 0. |
aria-expanded | boolean | Whether what it opens is open, such as the side panel it toggles, read out as the button's state. Leave it out for an action that opens nothing. Folded into "…" it's a plain item, since an expanded menu item reads as an open submenu. |
TopBarCreate
The round create button at the end of a top bar.
| Field | Type | Default | Description |
|---|---|---|---|
labelrequired | string | What it creates, such as "New order". It's the button's name and tooltip. | |
onSelectrequired | () => void | Runs it. | |
icon | ComponentType<IconComponentProps> | Its icon. Defaults to a plus. |
Accessibility
Its icon actions are buttons named by their labels, which their tooltips show; a dot adds ", new" to the name, in the row and in the menu. Actions folded into the menu stay reachable from the More app actions button, which shows a dot and adds ", new" to its name while a folded action has one. On a phone, its first button opens the sidebar, named Open navigation.
| Keys | What they do |
|---|---|
| Enter or Space | Runs the focused icon action or the create button, or opens the sidebar from the menu button a phone shows |
| Enter, Space or Down | Opens the More app actions menu from its button, where Up and Down move, Enter runs an action and Escape closes |
Motion
It doesn't move.
With reduced motion: Nothing changes.
Layout
It fills its column at --bt-h-header (56px) with no edge, padded like the page under it: 16px, 24 from 640px of column and 32 from 1024. The search takes up to 360px and narrows before anything overlaps; the icon actions, 36px round hit areas 4px apart, fold into "…" when they don't fit, and the 28px create button keeps its place at the end.
Related
See it in the roastery demo.