Page content
Header
Use the header to describe your page or large section of content.
Examples
Usage
Header is a generic component that can be used within a container's uppermost area.
The implementation of the header depends on which component it's added to.
Do
- Use the header to describe a section of content
- Display page-wide actions in the action area
- Use secondary elements or components (secondary text, pills, etc.) to aid in describing what the section is about
- Include call to actions that are relevant to the context of what the header represents
- Include an icon if it helps to identify user-generated content (pull requests, sprints, etc.)
- Consider how the header content will scale in smaller screens
- When using a primary button, it should always be the right-most button in the header
Don't
- Change items in the action area as the page content changes
- Use the header to display content that could be within the page area
- Include more than 1 primary button
- Include more than 3 action buttons, if possible
Anatomy
Default header area
Header area with icon button
Note that icon buttons, when placed at the rightmost side of the action area, appear closer to the border (at 16px instead of 20px).
Header area without bottom padding
Tables, dialogs, and other elements may take advantage of a header area without bottom padding.
Header area with very long title
The header action area is always vertically aligned to the top, even in cases of long and/or multi-line titles.
Header area with back button
Header area with block description
APIs
TitleSize
Medium
number
Large
number
Small
number
IHeaderBreakpointCommandItem
iconPropsoptional
Icon of the Command Bar item to be displayed on the certain breakpoint.
Specify undefined to make icon hidden.
id
string
Id of the Command Bar item specified for the Header.
importantoptional
boolean
Importance of the Command Bar item to be displayed on the certain breakpoint.
Not specifying important will let Header itself decide when to display items
in the overflow area.
If full control is needed to display items in the overflow area, specify important
for each Command Bar item no matter they change between breakpoints or not.
textoptional
string
Text of the Command Bar item to be displayed on the certain breakpoint.
Specify undefined to make text hidden.
IHeaderBreakpoint
breakpoint
number
The header is defined with series of breakpoints. Each of the breakpoints
will have a mappings for the specified Command Bar items.
If a Command Bar item is not changed for any of the breakpoints, then it is not
necessary to include it in the commandBarItems list. However, all the properties
(id, text, iconProps, important) need to be specified for a Command Bar item, if
it changes between breakpoints to have correct visibility for that item.
commandBarItemsoptional
List of Command Bar items, which will have a change for this particular breakpoint.
Id property needs to match the id from the commandBarItems of the Header in order to
get a Command Bar item's visibility updated for a certain breakpoint.
ICustomHeaderProps
className
string
An optional className to pass to the root Header element
separatorfalse
boolean
Whether or not to show a separator after the Header
IHeaderDescriptionProps
className
string
An optional className to pass to the description element
id
string
An optional id used for the descriptions's text. Can be used in conjunction with aria-describedby.
getSafeId() will be called on this value.
IHeaderBackButtonProps
buttonPropsrequired
If these props are provided, the Header will draw a back button before the
header's title. By default this will use a subtle button with the "Back" icon,
but these props can override those choices.
IHeaderIconProps
className
string
An optional className to pass to the icon element
IHeaderTitleProps
ariaLevel
number
An optional aria level to pass to the title element
className
string
An optional className to pass to the title element
id
string
An optional id used for the title's text. Can be used in conjunction with aria-labelledby.
getSafeId() will be called on this value.
IHeaderTitleAreaProps
className
string
An optional className to pass to the title area element
IHeaderTitleRowProps
className
string
An optional className to pass to the title row element
IHeaderProps
backButtonProps
If these props are provided, the Header will draw a back button before the
header's title. By default this will use a subtle button with the "Back" icon,
but these props can override those choices.
buttonCount
number
How many buttons to show in the HeaderCommandBar if there is room. The rest will be sent to overflow if they are not marked as important.
classNameInherited From: ICustomHeaderProps
string
An optional className to pass to the root Header element
commandBarClassName
string
Optional className to pass to the command bar rendered in the Header.
commandBarItems
IReadonlyObservableArray<IHeaderCommandBarItem> | IHeaderCommandBarItem[]
Items to display in the far-right Command Bar
Should influence page-wide state
commandBarMoreButtonId
string
Optional id to assign to the more button within the HeaderCommandBar.
contentClassName
string
Optional className to pass to the Header's content element.
description
React.ReactNode
Secondary text to display in the header, below the title
descriptionClassName
string
Optional className to pass to the description in the Header
descriptionId
string
An optional id used for the descriptions's text. Can be used in conjunction with aria-describedby.
getSafeId() will be called on this value.
headerBreakpoints
A header can be defined with a set of breakpoints. These breakpoints will be used to control
the visibility of the Command Bar items as the space available to the header changes.
separatorfalseInherited From: ICustomHeaderProps
boolean
Whether or not to show a separator after the Header
title
React.ReactNode
Primary text to display in the header
titleAriaLevel
number
Optional aria level to pass to the title in the Header
titleClassName
string
Optional className to pass to the title in the Header
titleIconProps
Props to render the large Title Icon to the left of the Title and Description elements
titleId
string
An optional id used for the title's text. Can be used in conjunction with aria-labelledby.
getSafeId() will be called on this value after it is passed to the <HeaderTitle />
useAriaLabelForOverflow
boolean
Optional boolean to keep icons for header bar but expand to have text for overflow menu