# App Header
> A consistently available top-level element of the application interface. It contains a brand logo, application title and app-wide utility actions.

<Callout variant="tip">

Use [Nav Bar component](/components/nav-bar) or [Sidebar Navigation component](/components/sidebar-navigation) to organize the primary navigation experience.

</Callout>

## Import

```js
import { AppHeader } from '@gemini-suite/vera-react';
```

App Header is a compound component that consists of multiple parts:

- `AppHeader.Root`: The main wrapper that contains the header.
- `AppHeader.Logo`: The logo of the application. It can be a wordmark or an icon.
- `AppHeader.Title`: The title of the application.
- `AppHeader.Status`: A container that displays current status or state of the application.
- `AppHeader.ActionList`: The wrapper that contains all the items of the action list.
- `AppHeader.ActionListItem`: The single item that represents one element of the action list.
- `AppHeader.ActionListPopoverContent`: A special component to compose with `Popover.Content` when rendering a nested, stacked `AppHeader.ActionList`.
- `AppHeader.ActionListChevronIcon`: A visual indicator that a list item contains a nested `AppHeader.ActionList`.

## Examples

### Default

`AppHeader` should be globally persistent and include a brand logo or mark followed by the application name in text form.

It can be used to surface certain application-wide actions and other non-primary navigation items. Common use cases include user account menu, link to user documentation or help guide, notification list trigger, settings or configuration link etc.

Use [App Frame component](/components/app-frame) to provide basic structure and host `AppHeader` inside `AppFrame.AppHeader` as in the example below.

```jsx
() => {
  const playgroundFrameRef = React.useRef();

  return (
    <AppFrame.Root
      ref={playgroundFrameRef}
      background="neutralSubtle"
      css={{
        // the following rules are added only to make the demo work in the playground
        // you shouldn't include them in your app
        isolation: 'isolate',
        position: 'relative',
        maxHeight: '60vh'
      }}
    >
      <AppFrame.AppHeader>
        <AppHeader.Root>
          <AppHeader.Logo product="hydraulics" />
          <AppHeader.Title>{'Product name'}</AppHeader.Title>
          <AppHeader.ActionList aria-label="AppHeader actions">
            <Tooltip content="User guide" delay={300}>
              <AppHeader.ActionListItem>
                <SvgIcon iconName="book" />
              </AppHeader.ActionListItem>
            </Tooltip>
            <Drawer.Root>
              <Tooltip content="Settings" delay={300}>
                <Drawer.Trigger
                  as={AppHeader.ActionListItem}
                  onFocus={e => e.preventDefault()}
                >
                  <SvgIcon iconName="settings" />
                </Drawer.Trigger>
              </Tooltip>
              <Drawer.Portal containerRef={playgroundFrameRef}>
                <Drawer.Content
                  css={{
                    // the following override is added only to make the demo
                    // work in the playground
                    position: 'absolute'
                  }}
                  maxWidth="22rem"
                >
                  <Drawer.Header>
                    <Drawer.Title>{'Settings'}</Drawer.Title>
                    <Drawer.Close
                      as={Button}
                      variant="ghost"
                      shape="circle"
                      size="small"
                      withLoneIcon
                      marginLeft="auto"
                    >
                      <SvgIcon iconName="close" size="medium" />
                    </Drawer.Close>
                  </Drawer.Header>
                  <Drawer.Body></Drawer.Body>
                </Drawer.Content>
              </Drawer.Portal>
            </Drawer.Root>
            <Tooltip content="Notifications" delay={300}>
              <AppHeader.ActionListItem>
                <Anchor.Root>
                  <SvgIcon iconName="bell" />
                  <Anchor.Target
                    as={Label}
                    circular
                    color="danger"
                    size="small"
                    inset="-40%"
                  >
                    {'2'}
                  </Anchor.Target>
                </Anchor.Root>
              </AppHeader.ActionListItem>
            </Tooltip>
            <Menu.Root>
              <Menu.Trigger as={AppHeader.ActionListItem}>
                <Avatar.Root of={'Max Mustermann'}>
                  <Avatar.Initials color="accentSubtle" />
                </Avatar.Root>
              </Menu.Trigger>
              <Menu.Content placement={Placement.BOTTOM_RIGHT}>
                <Flex paddingY="spacingS" paddingX="spacingM">
                  <Avatar.Root of={'Max Mustermann'}>
                    <Avatar.Initials color="accentSubtle" />
                  </Avatar.Root>
                  <Box>
                    {'Max Mustermann'}
                    <Text
                      as="div"
                      variant="zeta"
                      color="foregroundNeutralSubtle"
                    >
                      {'max.mustermann@invera-tech.com'}
                    </Text>
                  </Box>
                </Flex>
                <Menu.Separator />
                <Menu.Item startElement={<SvgIcon iconName="mobile" />}>
                  {'Activate MFA'}
                </Menu.Item>
                <Menu.Separator />
                <Menu.Item intent="danger">{'Log Out'}</Menu.Item>
              </Menu.Content>
            </Menu.Root>
          </AppHeader.ActionList>
        </AppHeader.Root>
      </AppFrame.AppHeader>
      <AppFrame.Main
        paddingY={{ '@initial': 'spacingM', '@mqMediumAndUp': 'spacingL' }}
        paddingX="spacingM"
        css={{
          display: 'grid',
          placeItems: 'center'
        }}
      >
        <Text color="foregroundNeutralModerate">{'Main content'}</Text>
      </AppFrame.Main>
    </AppFrame.Root>
  );
};
```

### Dark

Use `isDarkMode` property to enable dark mode.

```jsx
<AppHeader.Root isDarkMode>
  <AppHeader.Logo product="terrain" />
  <AppHeader.Title>{'Product name'}</AppHeader.Title>
  <AppHeader.Status>
    <Flex gap="spacingXs">
      <HintDot tone="accent" />
      {'Connected'}
    </Flex>
  </AppHeader.Status>
  <AppHeader.ActionList aria-label="Header actions">
    <Tooltip content="Settings" delay={300}>
      <AppHeader.ActionListItem>
        <SvgIcon iconName="settings" />
      </AppHeader.ActionListItem>
    </Tooltip>
    <AppHeader.ActionListItem>
      <Avatar.Root of="Snorre Lauritz">
        <Avatar.Initials />
      </Avatar.Root>
    </AppHeader.ActionListItem>
  </AppHeader.ActionList>
</AppHeader.Root>
```

### With status information

`AppHeader.Status` is a container that can be used to display current status or state to the user (e.g., real-time connection status). Use [Hint Dot component](/components/hint-dot) to indicate the status visually.

```jsx
<AppHeader.Root>
  <AppHeader.Logo product="terrain" />
  <AppHeader.Title>{'Product name'}</AppHeader.Title>
  <AppHeader.Status>
    <Flex gap="spacingXs">
      <HintDot tone="accent" />
      {'Connected'}
    </Flex>
  </AppHeader.Status>
  <AppHeader.ActionList aria-label="Header actions">
    <Tooltip content="Settings" delay={300}>
      <AppHeader.ActionListItem>
        <SvgIcon iconName="settings" />
      </AppHeader.ActionListItem>
    </Tooltip>
    <AppHeader.ActionListItem>
      <Avatar.Root of="Snorre Lauritz">
        <Avatar.Initials />
      </Avatar.Root>
    </AppHeader.ActionListItem>
  </AppHeader.ActionList>
</AppHeader.Root>
```

### Sizes

`AppHeader` comes in two sizes: `small` and `medium`. The default size is `medium`.

```jsx
<Flex flow="column">
  <AppHeader.Root>
    <AppHeader.Logo product="proAdm" />
    <AppHeader.Title>{'Product name'}</AppHeader.Title>
    <AppHeader.Status>
      <Flex gap="spacingXs">
        <HintDot tone="accent" />
        {'Status information'}
      </Flex>
    </AppHeader.Status>
    <AppHeader.ActionList aria-label="Header actions">
      <Tooltip content="Settings" delay={300}>
        <AppHeader.ActionListItem>
          <SvgIcon iconName="settings" />
        </AppHeader.ActionListItem>
      </Tooltip>
      <Menu.Root>
        <Menu.Trigger as={AppHeader.ActionListItem}>
          <Avatar.Root of={'Max Mustermann'}>
            <Avatar.Initials />
          </Avatar.Root>
        </Menu.Trigger>
        <Menu.Content placement={Placement.BOTTOM_RIGHT}>
          <Flex paddingY="spacingS" paddingX="spacingM">
            <Avatar.Root of={'Max Mustermann'}>
              <Avatar.Initials />
            </Avatar.Root>
            <Box>
              {'Max Mustermann'}
              <Text as="div" variant="zeta" color="foregroundNeutralSubtle">
                {'max.mustermann@invera-tech.com'}
              </Text>
            </Box>
          </Flex>
          <Menu.Separator />
          <Menu.Item startElement={<SvgIcon iconName="mobile" />}>
            {'Activate MFA'}
          </Menu.Item>
          <Menu.Separator />
          <Menu.Item intent="danger">{'Log Out'}</Menu.Item>
        </Menu.Content>
      </Menu.Root>
    </AppHeader.ActionList>
  </AppHeader.Root>

  <AppHeader.Root size="small">
    <AppHeader.Logo product="proAdm" />
    <AppHeader.Title>{'Product name'}</AppHeader.Title>
    <AppHeader.Status>
      <Flex gap="spacingXs">
        <HintDot tone="accent" />
        {'Status information'}
      </Flex>
    </AppHeader.Status>
    <AppHeader.ActionList aria-label="Header actions">
      <Tooltip content="Settings" size="small" delay={300}>
        <AppHeader.ActionListItem>
          <SvgIcon iconName="settings" />
        </AppHeader.ActionListItem>
      </Tooltip>
      <Menu.Root>
        <Menu.Trigger as={AppHeader.ActionListItem}>
          <Avatar.Root of={'Max Mustermann'} size="small">
            <Avatar.Initials />
          </Avatar.Root>
        </Menu.Trigger>
        <Menu.Content size="small" placement={Placement.BOTTOM_RIGHT}>
          <Flex gap="spacingS" padding="spacingS">
            <Avatar.Root of={'Max Mustermann'}>
              <Avatar.Initials />
            </Avatar.Root>
            <Box>
              {'Max Mustermann'}
              <Text as="div" variant="eta" color="foregroundNeutralSubtle">
                {'max.mustermann@invera-tech.com'}
              </Text>
            </Box>
          </Flex>
          <Menu.Separator />
          <Menu.Item startElement={<SvgIcon iconName="mobile" />}>
            {'Activate MFA'}
          </Menu.Item>
          <Menu.Separator />
          <Menu.Item intent="danger">{'Log Out'}</Menu.Item>
        </Menu.Content>
      </Menu.Root>
    </AppHeader.ActionList>
  </AppHeader.Root>
</Flex>
```

### Actions

Use `AppHeader.ActionList` as a container for one or more `AppHeader.ActionListItem` components to configure application header actions.

By passing the `startElement` prop, you can add icon to each action for clarity. You may also choose to display icon-only items and wrap them with [Tooltip](/components/tooltip).

```jsx
<AppHeader.Root>
  <AppHeader.Logo product="portal" />
  <AppHeader.ActionList aria-label="Header actions">
    <AppHeader.ActionListItem tone="danger">
      {'Emergency stop'}
    </AppHeader.ActionListItem>
    <AppHeader.ActionListItem startElement={<SvgIcon iconName="info" />}>
      Help
    </AppHeader.ActionListItem>
    <AppHeader.ActionListItem
      startElement={<SvgIcon iconName="hide" />}
      isDisabled
    >
      Disabled item
    </AppHeader.ActionListItem>
    <Tooltip content="Icon only" delay={300}>
      <AppHeader.ActionListItem>
        <SvgIcon iconName="settings" />
      </AppHeader.ActionListItem>
    </Tooltip>
  </AppHeader.ActionList>
</AppHeader.Root>
```

### Responsive header

For small viewport experiences, you can reduce the main `AppHeader.ActionList` to a toggle item that opens [Popover](/components/popover) containing a vertically oriented `AppHeader.ActionList` that displays the full action list.

**App Header** exposes `AppHeader.ActionListPopoverContent` to compose with `Popover.Content` and `AppHeader.ActionListChevronIcon` to visually indicate items with nested action lists.

[Hidden utility](/components/utility/hidden) is used to control the presence of both mobile and desktop navigation experiences based on specified [breakpoints](/tokens/breakpoints).

You may also save space by using `AppHeader.Logo` in a compact icon variant.

<Card
  href="https://next--698f15fa99e7b146f9002f64.chromatic.com/?path=/story//components-appheader--responsive"
  title="See complete example in Storybook"
  actionIcon="externalLink"
/>

```jsx
<AppFrame.Root background="neutralSubtle" css={{ maxHeight: '50vh' }}>
  <AppFrame.AppHeader>
    <AppHeader.Root>
      <AppHeader.Logo product="va" />
      <AppHeader.Title>{'Product name'}</AppHeader.Title>
      <Hidden
        hide={{
          '@initial': false,
          '@mqLargeAndUp': true
        }}
        displayStyle="contents"
      >
        <AppHeader.ActionList aria-label="Header actions">
          <Popover.Root>
            <Popover.Trigger
              as={AppHeader.ActionListItem}
              aria-label="Open collapsed actions"
            >
              <SvgIcon iconName="more" />
            </Popover.Trigger>
            <Popover.Content
              anchorOffset={0}
              as={AppHeader.ActionListPopoverContent}
            >
              <AppHeader.ActionList
                flow="column"
                aria-label="Collapsed actions"
                size="small"
              >
                <AppHeader.ActionListItem
                  startElement={<SvgIcon iconName="info" />}
                >
                  {'Item 1'}
                </AppHeader.ActionListItem>
                <AppHeader.ActionListItem isActive>
                  {'Item 2'}
                </AppHeader.ActionListItem>
                <AppHeader.ActionListItem>{'Item 3'}</AppHeader.ActionListItem>
              </AppHeader.ActionList>
            </Popover.Content>
          </Popover.Root>
          <Menu.Root>
            <Menu.Trigger as={AppHeader.ActionListItem}>
              <Avatar.Root of={'Max Mustermann'}>
                <Avatar.Initials color="accentSubtle" />
              </Avatar.Root>
            </Menu.Trigger>
            <Menu.Content placement={Placement.BOTTOM_RIGHT}>
              <Flex paddingY="spacingS" paddingX="spacingM">
                <Avatar.Root of={'Max Mustermann'}>
                  <Avatar.Initials color="accentSubtle" />
                </Avatar.Root>
                <Box>
                  {'Max Mustermann'}
                  <Text as="div" variant="zeta" color="foregroundNeutralSubtle">
                    {'max.mustermann@invera-tech.com'}
                  </Text>
                </Box>
              </Flex>
              <Menu.Separator />
              <Menu.Item startElement={<SvgIcon iconName="mobile" />}>
                {'Activate MFA'}
              </Menu.Item>
              <Menu.Separator />
              <Menu.Item intent="danger">{'Log Out'}</Menu.Item>
            </Menu.Content>
          </Menu.Root>
        </AppHeader.ActionList>
      </Hidden>
      <Hidden
        hide={{
          '@initial': true,
          '@mqLargeAndUp': false
        }}
        displayStyle="contents"
      >
        <AppHeader.ActionList aria-label="Header actions">
          <AppHeader.ActionListItem startElement={<SvgIcon iconName="info" />}>
            {'Item 1'}
          </AppHeader.ActionListItem>
          <AppHeader.ActionListItem isActive>
            {'Item 2'}
          </AppHeader.ActionListItem>
          <AppHeader.ActionListItem>{'Item 3'}</AppHeader.ActionListItem>
          <Menu.Root>
            <Menu.Trigger as={AppHeader.ActionListItem}>
              <Avatar.Root of={'Max Mustermann'}>
                <Avatar.Initials color="accentSubtle" />
              </Avatar.Root>
            </Menu.Trigger>
            <Menu.Content placement={Placement.BOTTOM_RIGHT}>
              <Flex paddingY="spacingS" paddingX="spacingM">
                <Avatar.Root of={'Max Mustermann'}>
                  <Avatar.Initials color="accentSubtle" />
                </Avatar.Root>
                <Box>
                  {'Max Mustermann'}
                  <Text as="div" variant="zeta" color="foregroundNeutralSubtle">
                    {'max.mustermann@invera-tech.com'}
                  </Text>
                </Box>
              </Flex>
              <Menu.Separator />
              <Menu.Item startElement={<SvgIcon iconName="mobile" />}>
                {'Activate MFA'}
              </Menu.Item>
              <Menu.Separator />
              <Menu.Item intent="danger">{'Log Out'}</Menu.Item>
            </Menu.Content>
          </Menu.Root>
        </AppHeader.ActionList>
      </Hidden>
    </AppHeader.Root>
  </AppFrame.AppHeader>
  <AppFrame.Main
    paddingY={{ '@initial': 'spacingM', '@mqMediumAndUp': 'spacingL' }}
    paddingX="spacingM"
    css={{
      display: 'grid',
      placeItems: 'center'
    }}
  >
    <Text color="foregroundNeutralModerate">{'Main content'}</Text>
  </AppFrame.Main>
</AppFrame.Root>
```

### With routing

`AppHeader.ActionListItem` can be rendered as `a` tag or a custom `Link` component, making the integration with routing package such as [React Router](https://reactrouter.com/en/main)​ easy.

<Card
  href="/components/sidebar-navigation#with-routing"
  title="See Sidebar Navigation with React Router for a detailed guide"
  actionIcon="arrowRight"
/>

---

## API Reference

### AppHeader.Root

| Name   | Type                  | Default    | Description                                                                                                                                                                                                                                  | Required |
| ------ | --------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `css`  | `StitchesCss`         |            | Apply styles directly to a component in a similar way how you would define inline styles. Vera uses [Stitches](https://stitches.dev/) under the hood with a fully-typed API and support for features like tokens, media queries or variants. |          |
| `size` | `"small" \| "medium"` | `"medium"` | The size of the header.                                                                                                                                                                                                                      |          |

### AppHeader.Logo

| Name      | Type                                                      | Default      | Description                                                                                                                                                                                                                                                                                  | Required |
| --------- | --------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `as`      | `keyof JSX.IntrinsicElements \| React.ComponentType<any>` | `div`        | Change the component to a different HTML tag or custom component. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node.   For more details, read our [Composition](/get-started/composition#polymorphism) guide. |          |
| `css`     | `StitchesCss`                                             |              | Apply styles directly to a component in a similar way how you would define inline styles. Vera uses [Stitches](https://stitches.dev/) under the hood with a fully-typed API and support for features like tokens, media queries or variants.                                                 |          |
| `label`   | `string`                                                  |              | The `aria-label` of the Logo element to use for screen readers.                                                                                                                                                                                                                              |          |
| `variant` | `"wordmark" \| "icon"`                                    | `"wordmark"` | Visual variant of the logo.                                                                                                                                                                                                                                                                  |          |

### AppHeader.Title

| Name  | Type                                                      | Default | Description                                                                                                                                                                                                                                                                                  | Required |
| ----- | --------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `as`  | `keyof JSX.IntrinsicElements \| React.ComponentType<any>` | `h1`    | Change the component to a different HTML tag or custom component. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node.   For more details, read our [Composition](/get-started/composition#polymorphism) guide. |          |
| `css` | `StitchesCss`                                             |         | Apply styles directly to a component in a similar way how you would define inline styles. Vera uses [Stitches](https://stitches.dev/) under the hood with a fully-typed API and support for features like tokens, media queries or variants.                                                 |          |

### AppHeader.Status

| Name  | Type                                                      | Default | Description                                                                                                                                                                                                                                                                                  | Required |
| ----- | --------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `as`  | `keyof JSX.IntrinsicElements \| React.ComponentType<any>` | `div`   | Change the component to a different HTML tag or custom component. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node.   For more details, read our [Composition](/get-started/composition#polymorphism) guide. |          |
| `css` | `StitchesCss`                                             |         | Apply styles directly to a component in a similar way how you would define inline styles. Vera uses [Stitches](https://stitches.dev/) under the hood with a fully-typed API and support for features like tokens, media queries or variants.                                                 |          |

### AppHeader.ActionList

| Name   | Type                  | Default    | Description                                                                                                                                                                                                                                  | Required |
| ------ | --------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `css`  | `StitchesCss`         |            | Apply styles directly to a component in a similar way how you would define inline styles. Vera uses [Stitches](https://stitches.dev/) under the hood with a fully-typed API and support for features like tokens, media queries or variants. |          |
| `size` | `"small" \| "medium"` | `"medium"` | The size of the action list.                                                                                                                                                                                                                 |          |
| `flow` | `"row" \| "column"`   | `"row"`    | The direction in which items of the action list flow.                                                                                                                                                                                        |          |

### AppHeader.ActionListItem

| Name           | Type                                                      | Default  | Description                                                                                                                                                                                                                                                                                  | Required |
| -------------- | --------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `as`           | `keyof JSX.IntrinsicElements \| React.ComponentType<any>` | `button` | Change the component to a different HTML tag or custom component. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node.   For more details, read our [Composition](/get-started/composition#polymorphism) guide. |          |
| `css`          | `StitchesCss`                                             |          | Apply styles directly to a component in a similar way how you would define inline styles. Vera uses [Stitches](https://stitches.dev/) under the hood with a fully-typed API and support for features like tokens, media queries or variants.                                                 |          |
| `startElement` | `React.ReactElement`                                      |          | `ReactElement` to render to the left of the item's children.                                                                                                                                                                                                                                 |          |
| `endElement`   | `React.ReactElement`                                      |          | `ReactElement` to render to the right of the item's children.                                                                                                                                                                                                                                |          |
| `isActive`     | `boolean`                                                 | `false`  | When `true`, the item is shown in an active state. `aria-current` attribute is set to `page` to indicate that the item represents the current page.                                                                                                                                          |          |
| `isDisabled`   | `boolean`                                                 | `false`  | When `true`, the item is disabled.                                                                                                                                                                                                                                                           |          |
| `tone`         | `"danger"`                                                |          | When value is `danger`, the item is highlighted in red.                                                                                                                                                                                                                                      |          |

### AppHeader.ActionListPopoverContent

| Name  | Type          | Default | Description                                                                                                                                                                                                                                  | Required |
| ----- | ------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `css` | `StitchesCss` |         | Apply styles directly to a component in a similar way how you would define inline styles. Vera uses [Stitches](https://stitches.dev/) under the hood with a fully-typed API and support for features like tokens, media queries or variants. |          |

### AppHeader.ActionListChevronIcon

| Name  | Type          | Default | Description                                                                                                                                                                                                                                  | Required |
| ----- | ------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `css` | `StitchesCss` |         | Apply styles directly to a component in a similar way how you would define inline styles. Vera uses [Stitches](https://stitches.dev/) under the hood with a fully-typed API and support for features like tokens, media queries or variants. |          |