Patterns / Work header in the top bar
A work's header on one line of the top bar
A page about one piece of work (a project, a prototype, a run) has a lot to say at the top: what it is, its pages, whose it is, how far it has got, how to pause or stop it, and what it has spent. Under the app's bar that is a second header. On a wide screen it fits on the bar itself.
TopBar has three places: start, middle and end. Put the work's name in start. In middle, put PageTabs with variant="pill" for its pages (with --cd-page-tabs-fade set to the bar's chrome, so its scroll fades match the bar), an EntityChip for the organisation, and a StageRing with its stage in words beside it. In end, put Pause, Stop, a UsageMeter with variant="pill" and surface="header", and PersonMenu.
When the bar is narrower than compactAt, TopBar draws compactMiddle instead of middle. Give it the shorter line: the tabs and the stage with its words, without the chip. The bar measures its own width, and it spans the frame, so a docked side panel doesn't narrow it. Your app knows when the panel is open, so it sets compactAt from that: compactAt={panelOpen ? 1240 : 990}.
On a phone there is room for the name, the tabs and two buttons. Below Tailwind's sm the tabs scroll in their own row, and the stage in words, the organisation, the spend, Pause and Stop move into a menu at the end, beside PersonMenu. Stop in the menu opens the same AlertDialog as the button.
The components
- Top barProThe bar: the name at the start, the work's line in the middle, the actions at the end, and `compactMiddle` below `compactAt` (Pro).
- Page tabsProThe work's pages as pills, the current one filled and `aria-current="page"`, with a count where you know one (Pro).
- Entity chipFreeThe organisation the work is for, with the icon and noun your app gives its kind (Pro).
- Stage ringProHow far the work has got, its stage in words beside it through `statusId` (Pro).
- Usage metersProThe spend as a pill on the bar's colour, its figures and level in its name (Pro).
- Alert dialogProStop opens it: what stops, and what can't be undone, before it happens.
- Person menuProThe signed-in person, at the end of the bar (Pro).
See it working
The code
The work's line on the top bar: the full line, the shorter one below compactAt, compactAt raised while your side panel is docked, and a menu for the rest on a phone.
"use client"
import * as React from "react"
import { MoreHorizontal } from "lucide-react"
import { TopBar } from "@/components/candor/top-bar"
import { PageTabs, type PageTabsItem } from "@/components/candor/page-tabs"
import { EntityChip } from "@/components/candor/entity-chip"
import { StageRing } from "@/components/candor/stage-ring"
import { UsageMeter } from "@/components/candor/usage-meters"
import type { Usage } from "@/lib/candor/ops"
import { PersonMenu, type PersonMenuUser } from "@/components/candor/person-menu"
import { Button } from "@/components/candor/ui/button"
import { DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuLabel, DropdownMenuSeparator, DropdownMenuTrigger } from "@/components/candor/ui/dropdown-menu"
import type { StepperStep } from "@/components/candor/ui/stepper"
/** The work the page is about, from your server. Each stage's state is your data. */
type Work = { name: string; org: { id: string; name: string }; stages: StepperStep[]; current: string; stageLine: string; spend: Usage }
export function WorkBar({ work, tabs, page, panelOpen, onStop, onPause, user, onSignOut }: {
work: Work
/** The work's pages, and the one the person is on, from your router. */
tabs: PageTabsItem[]
page: string
/** Whether your side panel is docked: the bar spans the frame, so it doesn't narrow it, and the line collapses sooner. */
panelOpen: boolean
/** Opens your AlertDialog, which says what stops and what can't be undone before it happens. */
onStop: () => void
onPause: () => void
user: PersonMenuUser
onSignOut: () => void
}) {
// The stage ring with its line in words: the ring's colour is never the only way the stage is said.
const stage = (id: string) => (
<span className="flex shrink-0 items-center gap-1.5">
<StageRing stages={work.stages} current={work.current} label="Delivery" size={22} statusId={id} />
<span id={id} className="text-xs whitespace-nowrap text-muted-foreground">{work.stageLine}</span>
</span>
)
// The tabs' scroll fades start from the bar's chrome, not the page's background.
const nav = <PageTabs label="Prototype" variant="pill" tabs={tabs} current={page} className="min-w-0 [--cd-page-tabs-fade:var(--cd-chrome)]" />
return (
<TopBar
compactAt={panelOpen ? 1240 : 990}
start={<span className="truncate text-sm font-semibold">{work.name}</span>}
middle={
<div className="flex min-w-0 items-center gap-3">
{nav}
{/* "org" is your own kind, given its icon and noun once with EntityKindsProvider. */}
<EntityChip entity={{ kind: "org", name: work.org.id, label: work.org.name }} />
{stage("work-stage")}
</div>
}
// Narrower than compactAt: the tabs and the stage stay, the chip goes. On a phone the tabs scroll in their own
// row and the stage is said in the menu below.
compactMiddle={
<div className="flex min-w-0 items-center gap-3">
{nav}
<span className="contents max-sm:hidden">{stage("work-stage-compact")}</span>
</div>
}
end={
<>
<Button variant="outline" size="sm" onClick={onPause} className="max-sm:hidden">Pause</Button>
<Button variant="outline" size="sm" onClick={onStop} className="max-sm:hidden">Stop</Button>
<UsageMeter variant="pill" surface="header" usage={work.spend} className="max-sm:hidden" />
{/* On a phone, what the bar has no room for, in one menu: the stage in words, whose it is, the spend, Pause and Stop. */}
<DropdownMenu>
<DropdownMenuTrigger render={<Button variant="ghost" size="icon" aria-label={`More for ${work.name}`} className="sm:hidden"><MoreHorizontal aria-hidden /></Button>} />
<DropdownMenuContent align="end" className="w-56">
<DropdownMenuLabel>Delivery: {work.stageLine}</DropdownMenuLabel>
<DropdownMenuLabel className="font-normal text-muted-foreground">For {work.org.name}</DropdownMenuLabel>
<div className="px-(--cd-item-px,0.5rem) py-(--cd-item-py,0.375rem)">
<UsageMeter usage={work.spend} className="border-0 p-0" />
</div>
<DropdownMenuSeparator />
<DropdownMenuItem onSelect={onPause}>Pause</DropdownMenuItem>
<DropdownMenuItem onSelect={onStop}>Stop…</DropdownMenuItem>
</DropdownMenuContent>
</DropdownMenu>
<PersonMenu user={user} onSignOut={onSignOut} />
</>
}
/>
)
}
Install
Each component brings in what it depends on. The free ones install as they are; Pro and Premium ones need a licence key.
Good to know
- Stop is never one press on the bar. It opens an AlertDialog that says what stops, what is kept, and what can't be undone, with Cancel focused first.
- The stage ring's colours don't say the stage on their own: keep its line in words beside it, in the shorter line too.
- The tabs are a
navwith a name of their own ("Prototype"), so the banner holds named navigations a screen reader can tell apart. - For finer steps than one
compactAt, make the middle a container (@container) and hide pieces with@max-*variants, least needed first.