TopBar | Dashforge-UI
Dashforge-UI
DocsStarter Kits
v0.1.0-alpha

TopBar

A responsive application header that coordinates seamlessly with LeftNav. Built on MUI AppBar with intelligent layout shifting, three flexible content slots (left, center, right), and automatic mobile adaptation. Essential for dashboard shells, admin interfaces, and multi-section applications.

Quick Start

Copy & Paste

import { TopBar } from '@dashforge/ui';
import { useState } from 'react';

const [navOpen, setNavOpen] = useState(true);

<TopBar
  navOpen={navOpen}
  navWidthExpanded={280}
  navWidthCollapsed={64}
  left={<Typography variant="h6">My App</Typography>}
  right={<Avatar src="/user.jpg" />}
/>

Examples

Common TopBar patterns and configurations

Basic App Header

Simple header with logo and user avatar

Dashboard
const [navOpen, setNavOpen] = useState(true);

<TopBar
  navOpen={navOpen}
  navWidthExpanded={280}
  navWidthCollapsed={64}
  left={<Typography variant="h6">Dashboard</Typography>}
  right={<Avatar sx={{ width: 32, height: 32 }} />}
/>
With Menu Toggle

Header with navigation menu toggle button

Admin Panel
const [navOpen, setNavOpen] = useState(true);

<TopBar
  navOpen={navOpen}
  navWidthExpanded={280}
  navWidthCollapsed={64}
  left={
    <Stack direction="row" spacing={2} alignItems="center">
      <IconButton onClick={() => setNavOpen(!navOpen)}>
        <MenuIcon />
      </IconButton>
      <Typography variant="h6">Admin Panel</Typography>
    </Stack>
  }
  right={<Avatar sx={{ width: 32, height: 32 }} />}
/>
With Search Bar

Header with centered search functionality

Products
const [navOpen, setNavOpen] = useState(false);

<TopBar
  navOpen={navOpen}
  navWidthExpanded={280}
  navWidthCollapsed={64}
  left={<Typography variant="h6">Products</Typography>}
  center={
    <TextField
      size="small"
      placeholder="Search products..."
      InputProps={{
        startAdornment: (
          <InputAdornment position="start">
            <SearchIcon fontSize="small" />
          </InputAdornment>
        ),
      }}
      sx={{ minWidth: 300 }}
    />
  }
  right={<Avatar sx={{ width: 32, height: 32 }} />}
/>
With Action Icons

Header with notification and settings icons

Workspace
const [navOpen, setNavOpen] = useState(true);

<TopBar
  navOpen={navOpen}
  navWidthExpanded={280}
  navWidthCollapsed={64}
  left={<Typography variant="h6">Workspace</Typography>}
  right={
    <Stack direction="row" spacing={1} alignItems="center">
      <IconButton>
        <Badge badgeContent={3} color="error">
          <NotificationsIcon />
        </Badge>
      </IconButton>
      <IconButton>
        <SettingsIcon />
      </IconButton>
      <Avatar sx={{ width: 32, height: 32 }} />
    </Stack>
  }
/>
Custom Toolbar Height

Header with custom minimum toolbar height

Compact Header
const [navOpen, setNavOpen] = useState(true);

<TopBar
  navOpen={navOpen}
  navWidthExpanded={280}
  navWidthCollapsed={64}
  toolbarMinHeight={{ xs: 56, md: 64 }}
  left={<Typography variant="h6">Compact Header</Typography>}
  right={<Avatar sx={{ width: 28, height: 28 }} />}
/>
Full-Featured Header

Complete header with all slots populated

Enterprise Dashboard
JD
const [navOpen, setNavOpen] = useState(true);

<TopBar
  navOpen={navOpen}
  navWidthExpanded={280}
  navWidthCollapsed={64}
  left={
    <Stack direction="row" spacing={2} alignItems="center">
      <IconButton onClick={() => setNavOpen(!navOpen)}>
        <MenuIcon />
      </IconButton>
      <Typography variant="h6" sx={{ fontWeight: 700 }}>
        Enterprise Dashboard
      </Typography>
    </Stack>
  }
  center={
    <TextField
      size="small"
      placeholder="Global search..."
      InputProps={{
        startAdornment: (
          <InputAdornment position="start">
            <SearchIcon fontSize="small" />
          </InputAdornment>
        ),
      }}
      sx={{ minWidth: 400 }}
    />
  }
  right={
    <Stack direction="row" spacing={1} alignItems="center">
      <IconButton>
        <Badge badgeContent={5} color="error">
          <NotificationsIcon />
        </Badge>
      </IconButton>
      <IconButton>
        <SettingsIcon />
      </IconButton>
      <Avatar sx={{ width: 32, height: 32 }}>JD</Avatar>
    </Stack>
  }
/>

Dashforge Capabilities

Intelligent layout coordination with responsive behavior and flexible content slots

TopBar provides intelligent layout coordination with LeftNav, responsive mobile adaptation, and flexible content slots for building professional application headers.

LeftNav Coordination

Layout

Automatically shifts position and width based on LeftNav state. Smooth transitions when navigation toggles or collapses.

Dynamic width adjustment

Smooth transition animations

Syncs with nav state

<TopBar
  navOpen={navOpen}
  navWidthExpanded={280}
  navWidthCollapsed={64}
  left={<Logo />}
  right={<UserMenu />}
/>

Responsive Behavior

Mobile Ready

Automatically adapts to mobile viewports. Full-width on mobile, coordinated layout on desktop with configurable breakpoint.

Full-width on mobile

Configurable breakpoint threshold

Automatic viewport detection

<TopBar
  navOpen={navOpen}
  navWidthExpanded={280}
  navWidthCollapsed={64}
  breakpoint="lg"
  left={<MenuToggle />}
  right={<Avatar />}
/>

Flexible Content Slots

Composition

Three content slots (left, center, right) for flexible layouts. Compose branding, search, navigation, and user actions as needed.

Left, center, right slots

Accepts any React node

Custom toolbar height

<TopBar
  navOpen={navOpen}
  navWidthExpanded={280}
  navWidthCollapsed={64}
  left={<Logo />}
  center={<SearchBar />}
  right={<UserActions />}
/>

Layout Composition

Real-world application shells with dynamic navigation and responsive layouts

Dashboard Application Shell

Combine TopBar with LeftNav to create a complete dashboard layout. The TopBar automatically adjusts its position and width when the navigation toggles or collapses.

Interactive Demo

Navigation State:

LeftNav (Expanded)

Dashboard
JD

Main Content Area

TopBar automatically adjusts width when navigation toggles

Current Layout State

Navigation: Expanded (280px)

TopBar Width: calc(100% - 280px)

import { TopBar, LeftNav } from '@dashforge/ui';
import { useState } from 'react';

const [navOpen, setNavOpen] = useState(true);

<Box sx={{ display: 'flex', minHeight: '100vh' }}>
  <LeftNav
    open={navOpen}
    widthExpanded={280}
    widthCollapsed={64}
    onToggle={() => setNavOpen(!navOpen)}
  >
    {/* Navigation items */}
  </LeftNav>
  
  <Box sx={{ flexGrow: 1 }}>
    <TopBar
      navOpen={navOpen}
      navWidthExpanded={280}
      navWidthCollapsed={64}
      left={
        <Stack direction="row" spacing={2} alignItems="center">
          <IconButton onClick={() => setNavOpen(!navOpen)}>
            <MenuIcon />
          </IconButton>
          <Typography variant="h6">Dashboard</Typography>
        </Stack>
      }
      right={
        <Stack direction="row" spacing={1} alignItems="center">
          <IconButton>
            <NotificationsIcon />
          </IconButton>
          <Avatar />
        </Stack>
      }
    />
    
    <Box component="main" sx={{ p: 3, mt: 10 }}>
      {/* Page content */}
    </Box>
  </Box>
</Box>

Why it matters

TopBar's coordination with LeftNav eliminates manual layout calculations. The header automatically shifts and resizes when navigation state changes, with smooth transitions for a polished UX.

Responsive Mobile Adaptation

TopBar automatically adapts to mobile viewports. Below the breakpoint threshold, it spans full width and ignores navigation state for optimal mobile UX.

Interactive Demo

Viewport Mode:

LeftNav

Application
JD

Main Content Area

TopBar coordinates with LeftNav on desktop

Current State

Viewport: Desktop (>= lg)

TopBar Width: calc(100% - 280px)

Center Slot: Visible (Search)

import { TopBar } from '@dashforge/ui';
import useMediaQuery from '@mui/material/useMediaQuery';
import { useTheme } from '@mui/material/styles';

const theme = useTheme();
const isMobile = useMediaQuery(theme.breakpoints.down('lg'));

<TopBar
  navOpen={navOpen}
  navWidthExpanded={280}
  navWidthCollapsed={64}
  breakpoint="lg"
  left={
    <Stack direction="row" spacing={2} alignItems="center">
      {isMobile && (
        <IconButton onClick={() => setMobileMenuOpen(true)}>
          <MenuIcon />
        </IconButton>
      )}
      <Typography variant="h6">
        {isMobile ? 'App' : 'Application Name'}
      </Typography>
    </Stack>
  }
  center={!isMobile && <SearchBar />}
  right={
    <Stack direction="row" spacing={1}>
      {!isMobile && (
        <IconButton>
          <NotificationsIcon />
        </IconButton>
      )}
      <Avatar />
    </Stack>
  }
/>

Why it matters

Mobile-first design requires different header layouts. TopBar's automatic viewport adaptation lets you compose conditional content while the component handles layout geometry automatically.

API Reference

Complete props and type definitions

PropTypeDefaultDescription
navOpenboolean-Whether the LeftNav is open/expanded. Required for layout coordination.
navWidthExpandednumber-Width in pixels of LeftNav when expanded. Used to compute desktop margin/width.
navWidthCollapsednumber-Width in pixels of LeftNav when collapsed. Used to compute desktop margin/width.
breakpoint'sm' | 'md' | 'lg' | 'xl'-Breakpoint below which mobile behavior is triggered. On mobile, TopBar ignores nav state and spans full width.
position'fixed' | 'absolute' | 'relative' | 'static' | 'sticky'-AppBar positioning strategy (same as MUI AppBar position prop)
leftReact.ReactNode-Optional left-aligned content slot (e.g., logo, menu toggle, title)
centerReact.ReactNode-Optional center-aligned content slot (e.g., search bar, navigation tabs)
rightReact.ReactNode-Optional right-aligned content slot (e.g., user menu, notifications, actions)
toolbarMinHeight{ xs: number; md: number }-Toolbar minimum height (responsive). Controls the vertical height of the TopBar.
sxSxProps<Theme>-MUI system style overrides for the root AppBar
classNamestring-CSS class name for custom styling
...appBarPropsAppBarProps-All other MUI AppBar props are forwarded to the underlying AppBar component
Type Definitions
TopBarProps
interface TopBarProps extends Omit<AppBarProps, 'position'> {
  navOpen: boolean;
  navWidthExpanded: number;
  navWidthCollapsed: number;
  breakpoint?: 'sm' | 'md' | 'lg' | 'xl';
  position?: AppBarProps['position'];
  left?: ReactNode;
  center?: ReactNode;
  right?: ReactNode;
  toolbarMinHeight?: { xs: number; md: number };
}

Implementation Notes

Technical details and best practices

1

Built on MUI AppBar

TopBar is built on top of MUI AppBar component, inheriting its positioning system, z-index management, and theme integration. The component wraps AppBar with intelligent LeftNav coordination and responsive behavior.

2

LeftNav Coordination

TopBar automatically adjusts its position and width based on LeftNav state. On desktop (>= breakpoint), it shifts right and reduces width when navigation is open. This coordination is handled automatically via navOpen, navWidthExpanded, and navWidthCollapsed props.

3

Responsive Mobile Behavior

Below the breakpoint threshold (default: lg), TopBar spans full width and ignores navigation state. This provides optimal mobile UX where side navigation is typically hidden in a drawer. Use the breakpoint prop to customize this threshold (sm, md, lg, xl).

4

Three Content Slots

TopBar provides three flexible content slots: left (logo, menu toggle), center (search, tabs), and right (user menu, notifications). All slots are optional and accept any React node. Use Stack or Box components to compose multiple elements within a slot.

5

Smooth Transitions

Width and margin transitions are automatic when navigation toggles. The component uses MUI theme transitions (sharp easing, leavingScreen duration) for consistent animation. These transitions are coordinated with LeftNav for synchronized visual feedback.

6

Position Strategy

Default position is "fixed" (stays at top when scrolling). Change to "absolute" for relative positioning, "sticky" for scroll-aware behavior, or "relative"/"static" for document flow. Position prop accepts all standard MUI AppBar position values.

7

Toolbar Height

Customize toolbar height via toolbarMinHeight prop (default: { xs: 68, md: 76 }). Responsive values ensure appropriate heights on mobile and desktop. Adjust this when you need compact headers or when integrating with specific layout requirements.

8

Z-Index Management

TopBar automatically sets z-index to theme.zIndex.drawer + 1 to ensure it appears above navigation drawers. This is handled internally via StyledAppBar. Override via sx prop if you need custom stacking context for modals or overlays.

9

Border Styling

A bottom border is applied automatically using theme.palette.grey[300] (or theme.vars.palette.grey[300] for CSS variables mode). This provides visual separation from content. Customize via sx prop to change border color, width, or remove entirely.

10

Prop Forwarding

All MUI AppBar props are forwarded to the underlying component (except position, which is explicitly typed). This includes color, elevation, className, sx, and event handlers. Use these for advanced customization beyond the component API.

11

Layout Best Practices

When using TopBar with LeftNav, ensure both components receive the same navOpen, navWidthExpanded, and navWidthCollapsed values. This synchronization ensures proper layout coordination. Consider storing these values in shared state or layout context.

12

Content Spacing

The Toolbar uses gap: 2 (16px) between slots for consistent spacing. If you need tighter/wider spacing within a slot, wrap your content in Stack or Box with custom gap values. The component handles slot alignment (left, center, right) automatically.

On This Page