Tabs and code groups

Tabs and code groups both let readers switch between versions of the same content. They work best when readers arrive knowing which version they need: their programming language, package manager, operating system, or role. The difference is what changes:

Code groups are for code. Use them when the explanation is the same for everyone and only the code changes, like the same API call in Python, JavaScript, and cURL.
Tabs are for everything else. Use them when the instructions, explanation, or mix of content changes, like setup steps that differ on macOS and Windows.

Code groups: same explanation, different code

Wrap two or more code blocks in <CodeGroup>. Each block needs a title, which becomes its label in the group.

Example of a code group

Install the SDK with your package manager.

<CodeGroup>

```bash npm
npm install @acme/sdk
```

```bash yarn
yarn add @acme/sdk
```

```bash pnpm
pnpm add @acme/sdk
```

</CodeGroup>

npm install @acme/sdk

yarn add @acme/sdk

pnpm add @acme/sdk

The sentence above the group applies to everyone, so it’s written once. Readers pick their package manager and copy one command. The same pattern works for SDK examples:

client = acme.Client(api_key="YOUR_API_KEY")

user = client.users.create(
    name="Ada Lovelace",
    email="ada@example.com"
)

const client = new Acme({ apiKey: "YOUR_API_KEY" });

const user = await client.users.create({
  name: "Ada Lovelace",
  email: "ada@example.com",
});

curl -X POST https://api.example.com/v1/users \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"name": "Ada Lovelace", "email": "ada@example.com"}'

For many languages, add the dropdown prop to <CodeGroup> to show a menu instead of a crowded row of labels.

Tabs: when more than the code changes

Use tabs when a section of the page changes based on the reader’s context, and the change includes instructions or explanation, not just code.

Example of tabs

<Tabs>
  <Tab title="macOS">
    Install the CLI with Homebrew:

    ```bash
    brew install acme-cli
    ```

    If macOS blocks the binary, open **System Settings** > **Privacy & Security** and click **Allow Anyway**.
  </Tab>
  <Tab title="Windows">
    Install the CLI with winget:

    ```powershell
    winget install Acme.CLI
    ```

    Restart your terminal so the `acme` command is on your `PATH`.
  </Tab>
</Tabs>

Each tab carries its own instructions, so a code group wouldn’t be enough. Tabs also work well for:

Authentication methods chosen earlier in a setup flow
A short section that differs for administrators and members
A procedure step that differs by platform

The difference should stay local. If most of the page changes, use views or separate pages instead.

Keep choices in sync

Tabs and code groups on the same page sync by label. If a reader selects Python in one, every other tab group or code group with a Python label switches too, so they only choose once. Labels must match exactly. Python, python, and Python 3 are three different choices. For code groups, the label is the code block’s title, so a block titled create_user.py won’t sync with a tab titled Python. If you want syncing, title your code blocks by language.

Tab groups that sync

<Tabs>
  <Tab title="Python">...</Tab>
  <Tab title="JavaScript">...</Tab>
</Tabs>

<CodeGroup>
```python Python
...
```
```javascript JavaScript
...
```
</CodeGroup>

Use the same labels and order throughout the page. If two tab groups share labels but represent unrelated choices, turn off syncing with sync={false} on <Tabs>.

When tabs get in the way

Don’t use tabs or code groups 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. 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: Conditional content—change a whole page based on the reader’s language, or show different content to people and AI agents.

Overview

Call out important information

Guide users through a process

Share sample code

Present content that varies by environment or stack

Show a comparison of options

Document APIs

Add visual context

Direct users to related content

Use supporting components

Code groups: same explanation, different code

Tabs: when more than the code changes

Keep choices in sync

When tabs get in the way

​Code groups: same explanation, different code

​Tabs: when more than the code changes

​Keep choices in sync

​When tabs get in the way

Code groups: same explanation, different code

Tabs: when more than the code changes

Keep choices in sync

When tabs get in the way