## Usage

The `<PageHeader />` component contains breadcrumbs, a heading, a divider, and optional actions. It's ideal for pages with singular actions like adding a new page, editing an existing one, or viewing detailed information.

You can further customise the `<PageHeader />` component by adding features to better suit different use-cases. The table below provides more context on when and how to use these customisations:

<Box paddingBottom="medium">

| Properties           | When to use                                                                                                                                                                                                                                                           |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| With actions         | Global actions that apply to the entire page can be placed in the PageHeader. To learn more about these actions, refer to the [actions guide](#with-actions).                                                                                                         |
| With avatar          | Avatars can be paired with the heading for primary elements like user or company profiles. You can add it as contextual info when it is used as a secondary information.                                                                                              |
| With contextual info | Contextual information in the PageHeader comprises secondary details such as tags, badges, labels, avatar, links, etc. All contextual items are configured through the `contextualItems` array. Read [contextual info guide](#with-contextual-info) for more details. |
| With tabs            | Tabs allow users to navigate between different views within the same context. Read [tabs guide](#with-tabs) for more details.                                                                                                                                         |

</Box>

```tsx live
const [actionsToggled, setActionsToggled] = useState(false);
const [avatarToggled, setAvatarToggled] = useState(false);
const [contextualItemsToggled, setContextualItemsToggled] = useState(false);
const [tabsToggled, setTabsToggled] = useState(false);
const [executionText, setExecutionText] = useState('');

const actions: PageHeaderAction[] = [
  {
    type: 'button',
    icon: AddIcon,
    label: 'Action 1',
    tone: 'neutral',
    onClick: () => setExecutionText('Action 1'),
  },
  {
    type: 'button',
    icon: AddIcon,
    label: 'Action 2',
    tone: 'neutral',
    onClick: () => setExecutionText('Action 2'),
  },
];

const breadcrumbs: BreadcrumbsProps = { crumbs: [{ label: 'Parent page', href: '#' }, { label: 'Current page' }] };

const items: ContextualItem[] = [
  { type: 'node', label: 'Label', value: 'Value' },
  { type: 'badge', label: 'Status', tone: 'positive' },
  { type: 'tag', label: 'Category', weight: 'outlined' },
];

const tabs: NavigationalTabItemProps[] = [
  {
    href: '#',
    isCurrentPage: true,
    label: 'Tab 1',
  },
  {
    href: '#',
    label: 'Tab 2',
  },
  {
    href: '#',
    label: 'Tab 3',
  },
  {
    href: '#',
    label: 'Tab 4',
  },
  {
    href: '#',
    label: 'Tab 5',
  },
  {
    href: '#',
    label: 'Tab 6',
  },
];

return (
  <Flex flex={1} flexDirection="column" gap="medium">
    <PlaygroundCard>
      <Flex flexDirection="column" gap="xsmall">
        <Toggle toggled={actionsToggled} size="small" onClick={setActionsToggled} label="Actions" />
        <Toggle toggled={avatarToggled} size="small" onClick={setAvatarToggled} label="Avatar" />
        <Toggle
          toggled={contextualItemsToggled}
          size="small"
          onClick={setContextualItemsToggled}
          label="Contextual info"
        />
        <Toggle toggled={tabsToggled} size="small" onClick={setTabsToggled} label="Tabs" />
      </Flex>
    </PlaygroundCard>
    <PageHeader
      actions={actionsToggled ? actions : undefined}
      avatar={avatarToggled ? { src: 'https://i.pravatar.cc/150?img=1' } : undefined}
      breadcrumbs={breadcrumbs}
      contextualItems={contextualItemsToggled ? items : undefined}
      heading="Page title"
      tabs={tabsToggled ? tabs : undefined}
    />
    {actionsToggled && <ResponseBlock prefix="Latest executed action:" value={executionText} />}
  </Flex>
);
```

## With actions

Global actions that apply to the entire page can be placed in the PageHeader. Actions use the `<ActionsGroup />` component.

<Box paddingBottom="medium">
  <Notice tone="informative">

    - Only the first 3 actions are rendered - any additional actions are ignored.
    - Each action can be either a `Button` or `ActionsDropdown`.
    - Default actions use the "Neutral tone with left icon button" variant.
    - Add new action uses the "Primary tone with left icon button" variant.
    - A maximum of one Primary or Critical action can be used.
    - Do not use "Ghost button" variant or "Standalone links" as actions.

  </Notice>
</Box>

```tsx live
const [actionValue, setActionValue] = useState('single-action');
const [executionText, setExecutionText] = useState('');

const actions: PageHeaderAction[] =
  actionValue === 'single-action'
    ? [
        {
          type: 'button',
          icon: UploadIcon,
          label: 'Export PDF',
          tone: 'neutral',
          onClick: () => setExecutionText('Export PDF'),
        },
      ]
    : [
        {
          type: 'button',
          icon: AddIcon,
          label: 'Add new',
          onClick: () => setExecutionText('Add new'),
        },
        {
          type: 'button',
          icon: DownloadIcon,
          label: 'Import',
          tone: 'neutral',
          onClick: () => setExecutionText('Import'),
        },
        {
          type: 'actionsDropdown',
          actions: [
            {
              icon: UploadIcon,
              label: 'Export',
              tone: 'neutral',
              onClick: () => setExecutionText('Export'),
            },
            {
              icon: MailIcon,
              label: 'Notify users',
              tone: 'neutral',
              onClick: () => setExecutionText('Notify users'),
            },
            {
              icon: AdministrationIcon,
              label: 'Auto-generate numbers',
              tone: 'neutral',
              onClick: () => setExecutionText('Auto-generate numbers'),
            },
          ],
        },
      ];

const breadcrumbs: BreadcrumbsProps = {
  crumbs:
    actionValue === 'single-action'
      ? [{ label: 'Home', href: '#' }, { label: 'Performance' }]
      : [
          { label: 'Administration', href: '#' },
          { label: actionValue === 'three-or-less-actions' ? 'Skills' : 'Users' },
        ],
};

const items = [
  { label: 'Single action', value: 'single-action' },
  { label: 'Three or less actions', value: 'three-or-less-actions' },
  { label: 'More than three actions', value: 'more-than-three-actions' },
];

return (
  <Flex flex={1} flexDirection="column" gap="medium">
    <PlaygroundCard>
      <Box width="20rem">
        <SelectInput
          isClearable={false}
          items={items}
          onChange={(item) => setActionValue(item?.value || 'single-action')}
          value={items.find(({ value }) => actionValue === value)}
        />
      </Box>
    </PlaygroundCard>
    <PageHeader
      actions={actionValue === 'three-or-less-actions' ? actions.slice(0, 3) : actions}
      breadcrumbs={breadcrumbs}
      heading={
        actionValue === 'single-action'
          ? 'Performance Appraisal FY24'
          : actionValue === 'three-or-less-actions'
            ? 'Skills'
            : 'Users'
      }
    />
    <ResponseBlock prefix="Latest executed action:" value={executionText} />
  </Flex>
);
```

## With contextual info

Contextual information can be incorporated below the heading. This space allows for the utilisation of the elements such as small-sized text, standalone links, link buttons, icons, tags, badges, or avatars, depending on the specific use case.

Badges can be used to convey status, while tags are used to highlight the most pertinent information. Each contextual item supports different variants and can be combined to create rich contextual information using the `contextualItems` array.

<Box paddingBottom="medium">
  <Notice tone="informative">

    - Do not use more than one tag or badge in the contextual info.
    - When using multiple "Link" or "Text" contextual info, ensure consistency by choosing any one of the following formats: Label & Link/Value, Icon & Link/Value, or Link only/Value only. Do not mix different formats within the same PageHeader.
    - Icons should only be used when it is adding essential value and having a strong association with the label. Icons should not be used just as decoration. Moreover, avoid mixing text-only labels and icon-only labels within the same group to prevent unnecessary clutter and ensure ease of information scanning.

  </Notice>
</Box>

```tsx live
const [avatarToggled, setAvatarToggled] = useState(false);
const [badgeToggled, setBadgeToggled] = useState(true);
const [buttonToggled, setButtonToggled] = useState(false);
const [buttonValue, setButtonValue] = useState('label-button');
const [executionText, setExecutionText] = useState('');
const [linkToggled, setLinkToggled] = useState(false);
const [linkValue, setLinkValue] = useState('label-link');
const [tagToggled, setTagToggled] = useState(false);
const [textToggled, setTextToggled] = useState(false);
const [textValue, setTextValue] = useState('label-value');

const breadcrumbs: BreadcrumbsProps = {
  crumbs: [{ label: 'Parent page', href: '#' }, { label: 'Current page' }],
};

const contextualItems: ContextualItem[] = (() => {
  const items: ContextualItem[] = [];

  if (badgeToggled) {
    items.push({
      type: 'badge',
      label: 'Neutral',
      tone: 'neutral',
    });
  }

  if (tagToggled) {
    items.push({
      type: 'tag',
      label: 'Label',
      weight: 'outlined',
    });
  }

  if (avatarToggled) {
    items.push({
      type: 'avatar',
      name: 'Jane Doe',
      src: 'https://i.pravatar.cc/150?img=1',
    });
  }

  if (textToggled) {
    items.push(
      textValue === 'value'
        ? { type: 'node', value: 'Value' }
        : textValue === 'icon-value'
          ? { type: 'node', icon: LocationIcon, value: 'Value' }
          : { type: 'node', label: 'Label', value: 'Value' }
    );
  }

  if (linkToggled) {
    items.push(
      linkValue === 'link'
        ? { type: 'link', href: '#', value: 'Link' }
        : linkValue === 'icon-link'
          ? { type: 'link', href: '#', icon: MailIcon, value: 'Link' }
          : { type: 'link', href: '#', label: 'Label', value: 'Link' }
    );
  }

  if (buttonToggled) {
    items.push(
      buttonValue === 'button'
        ? {
            type: 'button',
            onClick: () => setExecutionText('Link Button 3 Clicked!'),
            value: 'Link Button',
          }
        : buttonValue === 'icon-button'
          ? {
              type: 'button',
              onClick: () => setExecutionText('Link Button 2 Clicked!'),
              icon: LocationIcon,
              value: 'Link Button',
            }
          : {
              type: 'button',
              onClick: () => setExecutionText('Link Button 1 Clicked!'),
              label: 'Label',
              value: 'Link Button',
            }
    );
  }

  return items;
})();

return (
  <Flex flexDirection="column" gap="medium">
    <PlaygroundCard>
      <Flex flexDirection="column" gap="xsmall">
        <Toggle toggled={avatarToggled} size="small" onClick={setAvatarToggled} label="Avatar" />
        <Toggle toggled={badgeToggled} size="small" onClick={setBadgeToggled} label="Badge" />
        <Toggle toggled={linkToggled} size="small" onClick={setLinkToggled} label="Link" />
        {linkToggled && (
          <Box paddingLeft="xxlarge">
            <RadioGroup
              horizontal
              keepSpaceForMessage={false}
              onInputChange={setLinkValue}
              size="small"
              value={linkValue}
            >
              <Radio value="label-link">Label & link</Radio>
              <Radio value="icon-link">Icon & link</Radio>
              <Radio value="link">Link only</Radio>
            </RadioGroup>
          </Box>
        )}
        <Toggle toggled={buttonToggled} size="small" onClick={setButtonToggled} label="Link Button" />
        {buttonToggled && (
          <Box paddingLeft="xxlarge">
            <RadioGroup
              horizontal
              keepSpaceForMessage={false}
              onInputChange={setButtonValue}
              size="small"
              value={buttonValue}
            >
              <Radio value="label-button">Label & link button</Radio>
              <Radio value="icon-button">Icon & link button</Radio>
              <Radio value="button">Link button only</Radio>
            </RadioGroup>
          </Box>
        )}
        <Toggle toggled={tagToggled} size="small" onClick={setTagToggled} label="Tag" />
        <Toggle toggled={textToggled} size="small" onClick={setTextToggled} label="Text" />
        {textToggled && (
          <Box paddingLeft="xxlarge">
            <RadioGroup
              horizontal
              keepSpaceForMessage={false}
              onInputChange={setTextValue}
              size="small"
              value={textValue}
            >
              <Radio value="label-value">Label & value</Radio>
              <Radio value="icon-value">Icon & value</Radio>
              <Radio value="value">Value only</Radio>
            </RadioGroup>
          </Box>
        )}
      </Flex>
    </PlaygroundCard>
    <PageHeader breadcrumbs={breadcrumbs} contextualItems={contextualItems} heading="Page title" />
    {buttonToggled && <ResponseBlock prefix="Latest executed action:" value={executionText} />}
  </Flex>
);
```

## With tabs

The PageHeader includes support for navigational tabs. Enable this functionality by passing an array of `NavigationalTabItemProps` from [Tabs](/packages/tabs/#navigational-tabs) as `tabs`.

```tsx live
const hashValue = window.location.hash.split('#')[1];
const defaultTab = ['api-management', 'webhooks', 'notifications'].includes(hashValue) ? hashValue : 'integrations';

const [currentTab, setCurrentTab] = useState(defaultTab);

const tabs: NavigationalTabItemProps[] = [
  {
    href: '#integrations',
    isCurrentPage: !['api-management', 'webhooks', 'notifications'].includes(currentTab),
    label: 'Integrations',
  },
  {
    href: '#api-management',
    isCurrentPage: currentTab === 'api-management',
    label: 'API Management',
  },
  {
    href: '#webhooks',
    isCurrentPage: currentTab === 'webhooks',
    label: 'Webhooks',
  },
  {
    href: '#notifications',
    isCurrentPage: currentTab === 'notifications',
    label: 'Notifications',
  },
];

const currentLabel = tabs.find(({ isCurrentPage }) => isCurrentPage)?.label || 'Integrations';

const breadcrumbs: BreadcrumbsProps = {
  crumbs: [{ label: 'Administration', href: '#' }, { label: 'Audit log', href: '#' }, { label: currentLabel }],
};

const hashChangeHandler = () => setCurrentTab(window.location.hash.split('#')[1] || 'integrations');

useEffect(() => {
  window.addEventListener('hashchange', hashChangeHandler);
  return () => {
    window.removeEventListener('hashchange', hashChangeHandler);
  };
}, []);

return (
  <Flex flexDirection="column">
    <PageHeader breadcrumbs={breadcrumbs} heading="Audit log" tabs={tabs} />
    <Flex
      alignItems="center"
      justifyContent="center"
      padding="xlarge"
      borderStyle="dashed"
      borderWidth="thin"
      borderColor="neutralSubtle"
      fontFamily="mono"
    >
      {currentLabel}
    </Flex>
  </Flex>
);
```

When tabs are used, the layout spans the entire width of the container. The divider extends from the left edge to the right edge of the container.

<Box as="img" src="/images/page-header-tabs-example.png" alt="" />

## Page heading

### Adding a new page

When adding a new page/record, the PageHeader should display the appropriate heading to indicate the action being taken. The heading will be "Add," followed by the specific page/record name. For instance, if you're adding a new category, the heading should display "Add category." If you're adding a new external training entry, it should read "Add external training." This ensures clarity for users regarding the type of content they are creating.

```tsx live
const breadcrumbs: BreadcrumbsProps = {
  crumbs: [
    { label: 'Administration', href: '#' },
    { label: 'Learning', href: '#' },
    { label: 'Category', href: '#' },
    { label: 'Add category' },
  ],
};

return (
  <>
    <PageHeader breadcrumbs={breadcrumbs} heading="Add category" />
    <Flex flexDirection="column" padding={{ large: 'xxlarge', small: 'large', xsmall: 'medium' }}>
      <Field label="Category name" required>
        <TextInput />
      </Field>
      <Field label="Category description">
        <TextAreaInput />
      </Field>
      <Flex gap="small">
        <Button label="Save" />
        <Button label="Cancel" tone="neutral" />
      </Flex>
    </Flex>
  </>
);
```

### Viewing or editing a page

If the page is for viewing or editing purposes, do not add "Edit" in the heading. The heading will be the category name, for example, "Alpha accreditation program," as shown below.

```tsx live
const [name, setName] = useState('Alpha accreditation program');

const breadcrumbs: BreadcrumbsProps = {
  crumbs: [
    { label: 'Administration', href: '#' },
    { label: 'Learning', href: '#' },
    { label: 'Category', href: '#' },
    { label: 'Alpha accreditation program' },
  ],
};

const description =
  'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Phasellus augue felis, porta eget ultricies at, iaculis ultricies sapien. Duis ac sapien neque.';

return (
  <>
    <PageHeader breadcrumbs={breadcrumbs} heading="Alpha accreditation program" />
    <Flex flexDirection="column" padding={{ large: 'xxlarge', small: 'large', xsmall: 'medium' }}>
      <Field label="Category name" required>
        <TextInput onChange={({ target }) => setName(target.value)} value={name} />
      </Field>
      <Field label="Category description">
        <TextAreaInput defaultValue={description} />
      </Field>
      <Flex gap="small">
        <Button label="Save" />
        <Button label="Cancel" tone="neutral" />
      </Flex>
    </Flex>
  </>
);
```

Helps users understand what the content of the page is about. The PageHeader should always be at the top of a page.

PageHeader

Accessibility

Responsive layouts

Tokens

Foundations

a11y

Accordion

Actions

AddressInput

AppLayout

Avatar

Badge

Blanket

Breadcrumbs

BulkActionBar

Button

Card

Checkbox

Core

DateDropdown

DateInput

Divider

EmptyState

Field

Fieldset

FileInput

Filtering

Flex

Grid

Heading

Icon

Illustration

Link

List

Loading

Modal

Notice

Pagination

PhoneInput

Popover

Radio

RailTrack

RichTextEditor

ScrollWrap

SearchInput

SelectDropdown

SelectInput

ShowMore

Table

Tabs

Text

TextAreaInput

TextInput

Toast

Toggle

Tooltip

Utils

Utils - NextJS

Components

Forms

Search

Tables

Patterns

Introduction

Product tone and voice

Capitalisation

Date and time

Inclusive design

Content

Welcome to EDS

Start designing

Start developing

Contributing

Releases

The EDS way

Coding style guide

Guide to Pendo

Setting up the EDS repo

Creating a new component

Automated testing

PR and changeset process

Publishing snapshots

Publishing packages

Monorepo tools

Team resources