Nav Shell

This package contains components to use when displaying UI in the nav shell.

Top-of-page Content

All content at the top of the page should use the PageHeader component. For pages that require tabbed navigation below the page title, use the TabsList and TabLink components.

PageHeader

The PageHeader component is incredibly flexible and can satisfy a wide array of use-cases. In it's simplest form, it will display a page title given text as children.

Simple Example

<PageHeader>Page Title</PageHeader>

However, it can be customized with a number of props, most of which render content in the correct position within the PageHeader component.

Prop	Use
backLink	Renders a back button if provided. Should be a valid to value one would pass to React Router. If a page title is present, the back button will be an icon only. If a page title is not present, the back button will contain text as well.
renderAdditionalTitleContent	Render JSX immediately adjacent to the page title. This is useful for save view selectors and badges.
renderBottomContent	Render JSX below the page title. This should only be used for tabs with TabsList and TabLink.
renderRightContent	Render JSX to the far right of the page title, with space between the title and the rendered content. This is useful for page action buttons such as "Create" and "Export"

Any combination of these props can be used as needed by the particular page design.

Kitchen Sink Example

<PageHeader
  renderRightContent={
    <ButtonGroup>
      <Button variant="neutral" appearance="line">
        Secondary
      </Button>
      <Button variant="neutral" appearance="line">
        Secondary
      </Button>
      <Button>Primary</Button>
    </ButtonGroup>
  }
  renderAdditionalTitleContent={<Badge color="purple" label="Badge" />}
  renderBottomContent={
    <TabList>
      <TabLink to="/path-a">Tab</TabLink>
      <TabLink to="/path-b">Tab</TabLink>
      <TabLink to="/path-c">Tab</TabLink>
      <TabLink to="/path-d">Tab</TabLink>
      <TabLink to="/path-e">Tab</TabLink>
      <TabLink to="/path-f">Tab</TabLink>
    </TabList>
  }
  backLink="/"
>
  Page Title
</PageHeader>

Additional Examples

Title with buttons to right

<PageHeader
  renderRightContent={
    <ButtonGroup>
      <Button variant="neutral" appearance="line">
        Secondary
      </Button>
      <Button variant="neutral" appearance="line">
        Secondary
      </Button>
      <Button>Primary</Button>
    </ButtonGroup>
  }
>
  Page Title
</PageHeader>

Title with back button

<PageHeader backLink="/">Page Title</PageHeader>

Title with bottom tabs

<PageHeader
  renderBottomContent={
    <TabList>
      <TabLink to="/path-a">Tab</TabLink>
      <TabLink to="/path-b">Tab</TabLink>
      <TabLink to="/path-c">Tab</TabLink>
      <TabLink to="/path-d">Tab</TabLink>
      <TabLink to="/path-e">Tab</TabLink>
      <TabLink to="/path-f">Tab</TabLink>
    </TabList>
  }
>
  Page Title
</PageHeader>

TabsList and TabLink

The TabsList and TabLink components should only be used in the renderBottomContent prop of PageHeader. They provide appropriate aria roles and the spacing needed to align with the rest of the page content. TabsList should always wrap TabLink components. TabLink is a React Router Link under the hood so valid to values for the Link component will also work with TabLink. TabLink internally handles applying the underline active state when the to prop matches the current route. TabLink also accepts an optional id prop.

Example

<TabList>
  <TabLink to="/path-a">Tab</TabLink>
  <TabLink to="/path-b">Tab</TabLink>
  <TabLink to="/path-c">Tab</TabLink>
</TabList>

TopNavIconButton

The TopNavIconButton component is used when displaying an icon in the top-right corner of the nav shell. It accepts an onClick handler, an icon to display, and a label.

import { LiveFeedIcon } from '@starlight/svgs'

function MyComponent() {
  const handleClick = () => console.log('Button clicked!')

  return (
    <TopNavIconButton
      action={handleClick}
      icon={LiveFeedIcon}
      label="Live Feed"
    />
  )
}