TopNavigation

The <TopNavigation> is a component that provides a consistent, accessible navigation bar at the top of an application. It uses a three-slot layout with start, middle, and end sections, giving you full control over how navigation links, and user actions are arranged.

Anatomy

The <TopNavigation> component uses a compound component pattern with three slots arranged in a CSS grid layout.

• Container: The outer <header> element that holds the three-column grid layout.
• Start: The left-aligned slot, should be used for the side navigation toggle.
• Middle: The flexible center slot, rendered as a <nav> element. Commonly holds breadcrumbs, or a search field.
• End: The right-aligned slot, also rendered as a <nav> element. Typically contains utility actions such as user menus, notifications, or settings.

Appearance

The appearance of a component can be customized using the variant and size props. These props adjust the visual style and dimensions of the component, available values are based on the active theme.

Usage

The <TopNavigation> component organizes the top-level navigation of an application into three distinct sections. Place sidebar toggle in <TopNavigation.Start>, breadcrumbs in <TopNavigation.Middle>, and utility actions like user menus in <TopNavigation.End>.

Centering content in the middle slot

Some layouts call for centered content in the navigation bar, such as a search field. Use the alignX prop on <TopNavigation.Middle> to horizontally center its content within the available space. Note that alignX only applies to the Middle slot — Start and End are always aligned to their respective edges.

import { PanelRightClose } from 'lucide-react';import { Button, SearchField, TopNavigation } from '@marigold/components';export default () => (  <TopNavigation>    <TopNavigation.Start>      <Button variant="icon">        <PanelRightClose />      </Button>    </TopNavigation.Start>    <TopNavigation.Middle aria-label="Search" alignX="center">      <SearchField placeholder="Search..." />    </TopNavigation.Middle>    <TopNavigation.End>      <Button variant="secondary" size="small">        Sign in      </Button>    </TopNavigation.End>  </TopNavigation>);

Sticky navigation

By default, <TopNavigation> sticks to the top of the viewport when users scroll, ensuring persistent access to navigation. This is the most common behavior for application shells.

If the navigation bar is not needed while scrolling (e.g., on compact pages where content fits within the viewport), you can disable sticky behavior by setting sticky={false}.

import { PanelRightClose } from 'lucide-react';import {  Breadcrumbs,  Button,  Stack,  Text,  TopNavigation,} from '@marigold/components';export default () => (  <div style={{ height: '300px', overflow: 'auto' }}>    <TopNavigation>      <TopNavigation.Start>        <Button variant="icon">          <PanelRightClose />        </Button>      </TopNavigation.Start>      <TopNavigation.Middle>        <Breadcrumbs>          <Breadcrumbs.Item href="#">Home</Breadcrumbs.Item>          <Breadcrumbs.Item href="#">Events</Breadcrumbs.Item>          <Breadcrumbs.Item href="#">Event Details</Breadcrumbs.Item>        </Breadcrumbs>      </TopNavigation.Middle>      <TopNavigation.End>        <Button variant="secondary" size="small">          Sign in        </Button>      </TopNavigation.End>    </TopNavigation>    <div style={{ padding: '2rem' }}>      <Stack space={4}>        <Text weight="bold" size="xl">          Summer Festival        </Text>        <Text>          Scroll this container to see the navigation stick to the top. The          sticky behavior ensures users always have access to navigation, even          when browsing long pages of content.        </Text>        <Text>          Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do          eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad          minim veniam, quis nostrud exercitation ullamco laboris nisi ut          aliquip ex ea commodo consequat. Duis aute irure dolor in          reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla          pariatur.        </Text>        <Text>          Excepteur sint occaecat cupidatat non proident, sunt in culpa qui          officia deserunt mollit anim id est laborum. Sed ut perspiciatis unde          omnis iste natus error sit voluptatem accusantium doloremque          laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore          veritatis et quasi architecto beatae vitae dicta sunt explicabo.        </Text>      </Stack>    </div>  </div>);

Combining with Sidebar

For applications with multiple levels of navigation, combine <TopNavigation> with the Sidebar component to follow the recommended L-Shape layout structure. The top bar handles opening the sidebar and hosting global utility actions, while the Sidebar provides contextual navigation within each section.

The <TopNavigation.Middle> slot adapts to your application's navigation model. We recommend using it for Breadcrumbs to give users a clear trail back to parent sections, or for a search field to provide quick access to content across the application. This flexibility lets the <TopNavigation> and <Sidebar> work as complementary layers — the top bar orients users globally, while the Sidebar guides them locally within the current section.

Mobile Navigation

Mobile navigation should prioritize simplicity. Reduce the number of visible items and use progressive disclosure to keep the interface focused.

The <TopNavigation> itself does not handle responsive behavior — the components placed inside it are responsible for adapting to different screen sizes. On small screens:

• Collapse non-essential items: Hide labels and show icon-only actions. Use useResponsiveValue() or useSmallScreen() to control visibility at each breakpoint.
• Breadcrumbs: Use fewer segments on small screens. The Breadcrumbs component supports collapsing via the maxVisibleItems prop.

Accessibility

The <TopNavigation> renders a semantic <header> element, while <TopNavigation.Middle> and <TopNavigation.End> each render a <nav> landmark. When both are present, screen readers detect multiple navigation landmarks, so provide distinct aria-label values to help users differentiate them (e.g., "Main navigation" vs "User actions").

Props

TopNavigation

TopNavigation.Start

TopNavigation.Middle

TopNavigation.End

Alternative components

• Tabs: If you only need tab-based navigation without a full navigation bar layout, use Tabs directly.

• Breadcrumbs: For displaying hierarchical navigation paths that can be placed inside or outside of a TopNavigation.