Topbar
The fixed top navigation bar provides global search, notification access, and the user account dropdown. It is always paired with the sidebar and shifts its left offset when the sidebar collapses.
Anatomy
Parts Reference
| Part | Class | Details |
|---|---|---|
| Container | .topbar | position:fixed, top:0, left:sidebar-width, right:0, height:56px, bg:#fff, border-bottom, z-index:100 |
| Hamburger | icon button | 18px SVG, toggles sidebar. Hover: bg:#F8FAFC |
| Search box | inline flex | bg:#F8FAFC, border, radius:10px, max-width:300px. ⌘K shortcut focuses it. |
| Date range chip | inline flex | Optional. bg:#F8FAFC, border, radius:9px, 11px text. Used on report/dashboard pages. |
| Notification bell | icon button | 17px SVG. Red dot (7px, border:2px solid #fff) when unread notifications exist. |
| User chip | inline flex | 26-28px avatar + name (12px fw-700) + role (10px muted) + chevron. Opens user dropdown. |
| Left offset | left | Equals sidebar width. Transitions with sidebar collapse: 268px → 68px. |
AI Implementation Notes
For AI coding assistants: Topbar is always
position:fixed; top:0; left:[sidebar-width]; right:0; height:56px; z-index:100. Its left value must match the sidebar width and transition simultaneously when the sidebar collapses. The search input triggers on ⌘K/Ctrl+K via a keydown listener. Notification dot is a 7px circle with border:2px solid #fff positioned absolute top-right of the bell button. User chip opens a dropdown menu on click.When to Use
The topbar is a mandatory shell element — every authenticated page must include it alongside the sidebar. It provides global search, notifications, and user account access from any page in the application.
Properties
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
| sidebarWidth | string | required | — | Must match current sidebar width. CSS left offset. Updates when sidebar collapses: 268px → 68px. |
| userName | string | required | — | Current user name displayed in user chip. Initials derived automatically. |
| userRole | string | required | — | Role displayed below name in user chip (10px muted). |
| hasNotifications | boolean | optional | false | Shows red dot on notification bell (7px, border:2px solid #fff). |
| onSearch | function | optional | undefined | Called when user presses Enter in search box. |
Design Decisions
Why does the topbar use backdrop-filter blur instead of a solid background?
The topbar uses background:rgba(255,255,255,0.95) + backdrop-filter:blur(8px). This creates a "frosted glass" effect — when the user scrolls, content appears to slide under the topbar rather than being covered by a hard edge. It reinforces the layered nature of the fixed navigation without completely obscuring content below.
Changelog
v1.0.0July 2026Added
- Fixed positioning with dynamic left offset matching sidebar width
- Global search with Cmd/Ctrl+K shortcut
- Notification bell with unread dot indicator
- User chip with avatar, name, role, and dropdown trigger
States
Default
White bg, border-bottom, left = sidebar-width
With notifications
Red dot on bell icon
Search focused
Search box: indigo border + ring
Accessibility
| Requirement | Implementation |
|---|---|
| role="banner" | Add to <header> element. This is the standard landmark role for the page header. |
| Search landmark | Wrap search input in <search> or add role="search" to the search container. |
| Notification dot | Add aria-label="X unread notifications" to the bell button when dot is visible. |
| Keyboard shortcut | Cmd/Ctrl+K must focus search. Announce keyboard shortcuts via aria-keyshortcuts="Meta+k" on the search input. |
Composition
Allowed
Every authenticated page — always paired with sidebar
Global search input with Cmd+K shortcut
Notification bell with unread count
User chip opening profile dropdown
Forbidden
Auth pages (login, password reset)
Full-page error screens (404, 403)
Multiple topbars on one page
Best Practices
Do
Always update the topbar left offset when the sidebar collapses. Both must transition simultaneously.
A misaligned topbar/sidebar creates a visual glitch that breaks the shell layout.
Don't
Use a fixed pixel value for topbar left that doesn't update when sidebar collapses.
Hardcoded left offset will desync from the sidebar on collapse.
Related Components
Content Rules
Good search placeholder
Search prospects, customers, transactions...
Lists the specific entities searchable. Sets expectations.
Bad search placeholder
Search
Too vague — users don't know what can be searched.
Behavior
| Trigger | Behavior |
|---|---|
| Hamburger click | Toggles sidebar collapse. Updates sidebar width, topbar left offset, and main margin-left simultaneously with 0.35s transition. |
| Cmd/Ctrl+K | Focuses and selects search input. Works globally on any page. |
| Search Enter | Calls onSearch handler with current input value. Default: navigates to search results page. |
| User chip click | Opens user profile dropdown menu below the chip. |
| Scroll | Topbar remains fixed. backdrop-filter:blur(8px) + rgba(255,255,255,0.95) creates frosted glass effect as content scrolls underneath. |