Tabs
Docusaurus provides <Tabs>
components that you can use thanks to MDX:
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
<Tabs>
<TabItem value="apple" label="Apple" default>
This is an apple ๐
</TabItem>
<TabItem value="orange" label="Orange">
This is an orange ๐
</TabItem>
<TabItem value="banana" label="Banana">
This is a banana ๐
</TabItem>
</Tabs>
- Apple
- Orange
- Banana
It is also possible to provide values
and defaultValue
props to Tabs
:
<Tabs
defaultValue="apple"
values={[
{label: 'Apple', value: 'apple'},
{label: 'Orange', value: 'orange'},
{label: 'Banana', value: 'banana'},
]}>
<TabItem value="apple">This is an apple ๐</TabItem>
<TabItem value="orange">This is an orange ๐</TabItem>
<TabItem value="banana">This is a banana ๐</TabItem>
</Tabs>
- Apple
- Orange
- Banana
Tabs
props take precedence over the TabItem
props:
<Tabs
defaultValue="apple"
values={[
{label: 'Apple 1', value: 'apple'},
{label: 'Orange 1', value: 'orange'},
{label: 'Banana 1', value: 'banana'},
]}>
<TabItem value="apple" label="Apple 2">
This is an apple ๐
</TabItem>
<TabItem value="orange" label="Orange 2">
This is an orange ๐
</TabItem>
<TabItem value="banana" label="Banana 2" default>
This is a banana ๐
</TabItem>
</Tabs>
- Apple 1
- Orange 1
- Banana 1
tip
By default, all tabs are rendered eagerly during the build process, and search engines can index hidden tabs.
It is possible to only render the default tab with <Tabs lazy />
.
Displaying a default tab
The first tab is displayed by default, and to override this behavior, you can specify a default tab by adding default
to one of the tab items. You can also set the defaultValue
prop of the Tabs
component to the label value of your choice. For example, in the example above, either setting default
for the value="apple"
tab or setting defaultValue="apple"
for the tabs forces the "Apple" tab to be open by default.
Docusaurus will throw an error if a defaultValue
is provided for the Tabs
but it refers to an non-existing value. If you want none of the tabs to be shown by default, use defaultValue={null}
.
Syncing tab choices
You may want choices of the same kind of tabs to sync with each other. For example, you might want to provide different instructions for users on Windows vs users on macOS, and you want to changing all OS-specific instructions tabs in one click. To achieve that, you can give all related tabs the same groupId
prop. Note that doing this will persist the choice in localStorage
and all <Tab>
instances with the same groupId
will update automatically when the value of one of them is changed. Note that groupID
are globally-namespaced.
<Tabs groupId="operating-systems">
<TabItem value="win" label="Windows">Use Ctrl + C to copy.</TabItem>
<TabItem value="mac" label="MacOS">Use Command + C to copy.</TabItem>
</Tabs>
<Tabs groupId="operating-systems">
<TabItem value="win" label="Windows">Use Ctrl + V to paste.</TabItem>
<TabItem value="mac" label="MacOS">Use Command + V to paste.</TabItem>
</Tabs>
- Windows
- MacOS
- Windows
- MacOS
For all tab groups that have the same groupId
, the possible values do not need to be the same. If one tab group with chooses an value that does not exist in another tab group with the same groupId
, the tab group with the missing value won't change its tab. You can see that from the following example. Try to select Linux, and the above tab groups doesn't change.
<Tabs groupId="operating-systems">
<TabItem value="win" label="Windows">
I am Windows.
</TabItem>
<TabItem value="mac" label="MacOS">
I am macOS.
</TabItem>
<TabItem value="linux" label="Linux">
I am Linux.
</TabItem>
</Tabs>
- Windows
- MacOS
- Linux
Tab choices with different groupId
s will not interfere with each other:
<Tabs groupId="operating-systems">
<TabItem value="win" label="Windows">Windows in windows.</TabItem>
<TabItem value="mac" label="MacOS">macOS is macOS.</TabItem>
</Tabs>
<Tabs groupId="non-mac-operating-systems">
<TabItem value="win" label="Windows">Windows is windows.</TabItem>
<TabItem value="unix" label="Unix">Unix is unix.</TabItem>
</Tabs>
- Windows
- MacOS
- Windows
- Unix
Customizing tabs
You might want to customize the appearance of certain set of tabs. To do that you can pass the string in className
prop and the specified CSS class will be added to the Tabs
component:
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
<Tabs className="unique-tabs">
<TabItem value="Apple">This is an apple ๐</TabItem>
<TabItem value="Orange">This is an orange ๐</TabItem>
<TabItem value="Banana">This is a banana ๐</TabItem>
</Tabs>;
- Apple
- Orange
- Banana