Tabs
Tabs divide and organize related content, and can be used to navigate between two or more related views within the same parent container.
Examples
Content of tab2
Usage
Do
- Use on content-heavy pages that would otherwise require lots of scrolling to access the different sections
- Keep titles concise (one to two words)
- Make sure the relationship between all tabs within a tab group is clear
- Use for sections of content that sit within the same hierarchical level
- Only place tabs above content they relate to
- Test designs and content without tabs first
- Have only one tab active at a time
Don’t
- Use to link to another page
- Use if it’s possible to display all the content within the tabs at once
- Use to represent steps in a journey
- Use to compare content between tabs
- Display fewer than two tabs
- Nest tabs
Anatomy
- (1) Default 32px tall tab
- (2) Tall 48px tall tab
- (3) Large link size (40px tall)
Icons and badges
Tabs can include icons or badges next to the title to convey more information at a glance.
Related
Developer guidance
- Render additional content into the provided area by using the
renderAdditionalContentprop. The example renders a filter bar, but you can render anything you need into that space - Use a tab provider with your tab bar or tab list to auto-wire it together with your tab content
APIs
TabSize
Compact"compact"
string
32px tall with 14px text
Tall"tall"
string
48px tall with 14px text
LargeLink"large-link"
string
40px tall with 17px text
Orientation
Horizontal
number
Vertical
number
ITabBarProps
ariaLabelInherited From: ITabsProps
string
Aria-label for the tab group
classNameInherited From: ITabsProps
string
Optional root classname for the tabs element.
disableSticky
boolean
If true, do not apply position: sticky to the tab bar.
onSelectedTabChangedrequiredInherited From: ITabsProps
(newTabId: string) => void
Called when the selected tab has changed (through click or keyboard)
orientationflex-columnInherited From: ITabsProps
Determines if we'll render as Flex-Row or Flex-Column
renderAdditionalContent
() => JSX.Element | undefined
Non-tabs content to render in the tab bar, such as filterbar, view actions, etc.
selectedTabIdInherited From: ITabsProps
IReadonlyObservableValue<string> | string
The selected tab's id either as a string or a readonly observable value
tabsClassName
string
Optional root classname for the tabs element.
ITabListProps
ariaLabelInherited From: ITabsProps
string
Aria-label for the tab group
classNameInherited From: ITabsProps
string
Optional root classname for the tabs element.
listSubTitle
string
Subtitle string to render
listTitle
string
Header string to render
onSelectedTabChangedrequiredInherited From: ITabsProps
(newTabId: string) => void
Called when the selected tab has changed (through click or keyboard)
orientationflex-columnInherited From: ITabsProps
Determines if we'll render as Flex-Row or Flex-Column
selectedTabIdInherited From: ITabsProps
IReadonlyObservableValue<string> | string
The selected tab's id either as a string or a readonly observable value
ITabsProps
ariaLabel
string
Aria-label for the tab group
className
string
Optional root classname for the tabs element.
onSelectedTabChangedrequired
(newTabId: string) => void
Called when the selected tab has changed (through click or keyboard)
selectedTabId
IReadonlyObservableValue<string> | string
The selected tab's id either as a string or a readonly observable value
ITabProps
badgeCount
number | IReadonlyObservableValue<number>
Number to display next to the name of the tab in a badge. If a non-numeric value is desired
in the badge, use the renderBadge prop and pass a <TabBadge /> instead.
groupId
string
Matches this Tab to a Group
index
number
Used for aria attributes on tab.
Does not need to be provided when used in the context of a TabBar or Tabs component
isSelected
boolean
Whether or not the tab is appearing as selected.
Does not need to be provided when used in the context of a TabBar or Tabs component
onBeforeTabChange
(ev: React.MouseEvent<HTMLElement> | React.KeyboardEvent<HTMLElement> | null, tabId: string, url?: string) => boolean
Called when the user requests to change to this pivot. If this method return false, the change will be blocked.
onClick
(selectedTabId: string) => void
Handles click/keydown events on the tab.
Does not need to be provided when used in the context of a TabBar or Tabs component
renderBadge
() => React.ReactNode
Used to provide custom content in the badge area of a Tab. If the content is simply a number, use badgeCount instead.
In cases where the Badge should be a standard Pill, but just with text instead of a number, use a TabBadge, like the following:
renderBadge={() => <TabBadge>50+</TabBadge>}
setSize
number
Used for aria attributes on tab.
Does not need to be provided when used in the context of a TabBar or Tabs component
url
string
If provided will use an <a> for the tab as well as allow it to be CTRL-clicked to open in
a new browser tab
ITabBadgeProps
className
string
A custom className to add to the underlying <Pill />.
containsCounttrue
boolean
Whether or not the <Pill /> contains a number.
ITabGroup
id
string
Unique identifier for a TabGroup
name
string
Display name
orderoptional
number
Ordering: Lower = renders first
ITabProviderContext
commandBarItemsoptional
IHeaderCommandBarItem[] | IReadonlyObservableArray<IHeaderCommandBarItem>
A list of commands that should be rendered in the header.
renderContentoptional
() => JSX.Element
Called to render content for the tab
renderFilterBaroptional
(inTabBar: boolean) => JSX.Element | undefined
Called to render content for the filter bar
selectedIdoptional
IReadonlyObservableValue<string> | string
Tracks the selected tab id.
tabs
The current list of all provided tabs (not defined directly as children to the Tabs component)
ITabGroupProviderContext
groups
ITabProviderProps
providersrequired
IReadonlyObservableArray<IVssContributedTab>
selectedTabIdrequired
IReadonlyObservableValue<string> | string
Tracks the selected tab id.
ITabGroupProviderProps
providersrequired
IReadonlyObservableArray<ITabGroup>
IVssContributedTab
badgeCountoptional
number | IReadonlyObservableValue<number>
Number to display next to the name of the tab in a badge. If a non-numeric value is desired
in the badge, use the renderBadge prop and pass a <TabBadge /> instead.
commandBarItemsoptional
IHeaderCommandBarItem[] | IReadonlyObservableArray<IHeaderCommandBarItem>
A list of commands that should be rendered in the header.
fpsRequiredoptional
boolean
If true, use a fast page switch when switching to this pivot (a url must be supplied by the pivot).
groupIdoptional
string
Matches this Tab to a Group
onBeforeTabChangeoptional
(ev: React.MouseEvent<HTMLElement> | React.KeyboardEvent<HTMLElement> | null, tabId: string, url?: string) => boolean
Called when the user requests to change to this pivot. If this method return false, the change will be blocked.
orderoptional
number
Used to sort tabs. Lower order means the tab will be rendered first. If not provided, defaults to 100
renderoptional
() => JSX.Element
Renders content for the tab
renderBadgeoptional
() => React.ReactNode
Used to provide custom content in the badge area of a Tab. If the content is simply a number, use badgeCount instead.
In cases where the Badge should be a standard Pill, but just with text instead of a number, use a TabBadge, like the following:
renderBadge={() => <TabBadge>50+</TabBadge>}
renderFilterBaroptional
(inTabBar: boolean) => JSX.Element | undefined
Renders a filter bar - provides a parameter to determine whether or not this render
is taking place in the tab bar or in the content
routeIdoptional
string
Id of the route to use to compute the url for this pivot
routeValuesoptional
{ [key: string]: string }
Optional route values to use along with the supplied route id when computing this pivot's url
urloptional
IReadonlyObservableValue<string> | string
If provided will use an <a> for the tab as well as allow it to be CTRL-clicked to open in
a new browser tab