Tabs
Purpose. Tabs display alternative versions of related content within a single page. Use tabs selectively when switching between equivalent content helps readers complete a task. Do not use tabs as a substitute for headings or as a general method for organizing product-specific documentation.
Tabs hide content until readers select the corresponding tab. This can reduce discoverability, make information harder to scan and compare, and introduce accessibility, navigation, and content-reuse challenges.
When to use tabs
Must
- Use headings or separate pages instead of tabs when content represents distinct concepts, features, or tasks that readers need to discover independently.
- Do not use tabs solely to shorten a page or reduce scrolling.
- Do not hide essential prerequisites, warnings, or other information that applies to all readers inside a tab.
- Make product applicability clear in the content itself. Do not rely exclusively on tab labels to identify which product or deployment model the instructions apply to.
Should
- Reserve tabs for short, closely related alternatives that serve the same purpose, such as equivalent code examples in different programming languages.
- Use descriptive, concise tab labels that clearly identify the available alternatives.
- Limit the number of tabs to avoid overwhelming readers or creating navigation problems on smaller screens.
- Consider whether readers need to compare the content. If comparison is important, use headings, adjacent sections, or a comparison table instead.
- Prefer headings when readers are likely to scan, search, bookmark, or link directly to individual sections.
- Use separate pages when product-specific content is substantial, involves different workflows, or requires independent navigation and metadata.
May
- Use tabs for equivalent code examples, platform-specific commands, or short variations of the same procedure when readers generally need only one alternative.
Considerations for discoverability and accessibility
Tabs introduce additional considerations that headings and ordinary document sections generally avoid.
- Discoverability: Readers might overlook inactive tabs and miss relevant information.
- Accessibility: Tab components require appropriate keyboard navigation, focus management, and screen-reader support.
- Navigation: Content in inactive tabs is not immediately visible through ordinary page scrolling. Tabs might also be less discoverable on mobile devices.
- Direct linking: Linking to content within a tab requires the documentation platform to activate the correct tab when the link opens. Headings provide a simpler mechanism for section-level links.
- Search and AI discovery: Depending on implementation, hidden content might not be consistently available to search engines, content extraction tools, or AI retrieval systems. Product context can also be lost when content is extracted without its tab label.
- Content comparison: Readers must switch between tabs to compare information, increasing cognitive effort.
- Printing and exporting: Inactive tab content might be omitted from printed or exported versions unless the platform explicitly supports it.
Improving the visual prominence or linkability of tabs does not eliminate these limitations. Choose the content structure before choosing the presentation component.
Example: Equivalent code samples
Acceptable
Use tabs to present the same API request in different programming languages, such as JavaScript, Python, and cURL.
In this scenario, the tabs provide alternative representations of the same operation. Readers typically need only the example for their preferred language.
Before adding tabs
Consider the following questions:
- Does each tab present an alternative version of the same information, or does it contain independently useful content?
- Would readers benefit from seeing all the content while scrolling or scanning the page?
- Do readers need to compare information across tabs?
- Does each section need a stable, shareable link?
- Would headings or separate pages improve discoverability, navigation, or content reuse?
If the content is independently useful, requires comparison, or needs to be discovered through headings and navigation, prefer headings or separate pages.
See also