Skip to main content
Tabs let readers switch between versions of the same content. They work best when readers arrive knowing which version they need: their operating system, package manager, programming language, or role. If readers need to study the options before choosing, keep the options visible. Tabs separate known paths. They make it harder to compare options because readers have to switch between them.

​
Use tabs for a local variation

Tabs are a good fit when one part of a page changes but the surrounding explanation still applies to everyone.
Example of tabs
Someone using npm can go straight to the relevant command. The instruction that applies to everyone stays outside the tabs. Tabs also work well for:
  • Operating system variations such as macOS, Windows, and Linux
  • SDK examples in Python, Node.js, and Ruby
  • Authentication methods chosen earlier in a setup flow
  • A short section that differs for administrators and members
The difference should stay local. If most of the page changes, use views or separate pages instead.

​
Keep tab choices consistent

When tab groups on a page share a title, selecting that title updates the other groups too. If a reader selects Python once, the rest of the page can follow that choice. Titles must match exactly. Python, python, and Python 3 are three different selections.
Tab groups that sync
Use the same labels and order throughout the page so readers don’t have to reinterpret each group. If two groups happen to share labels but represent unrelated choices, disable syncing:
Tabs with syncing disabled

​
When tabs get in the way

Don’t use tabs for options readers need to compare. Switching back and forth makes differences harder to see. Use a table, columns, or short sections instead. Don’t bury a recommendation in tabs. If one option is right for most readers, recommend it before showing the alternatives. Don’t use tabs to make a page look shorter. Required instructions should stay visible, and a procedure with substantially different paths is usually easier to follow as separate guides. Long rows of tabs can also become difficult to scan, especially on smaller screens. For a large set of language examples, consider a <CodeGroup> with the dropdown prop. Finally, don’t repeat a distinction the site navigation already makes. If administrators and members have separate sections, role-based tabs inside those pages are a sign that the content may be in the wrong place.
Next up: Code groups for multi-language examples — How code groups handle the specific case of showing the same code in multiple languages.