# @diplodoc/tabs-extension
> Tabs plugin for Diplodoc transformer and builder
Latest version **3.10.7** (published 2026-08-17) · MIT license · 0 weekly downloads
## Install
```sh
npm install @diplodoc/tabs-extension
pnpm add @diplodoc/tabs-extension
yarn add @diplodoc/tabs-extension
bun add @diplodoc/tabs-extension
```
## Health
**Score 75/100 (B)** — status: active.
Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.
Warnings: low downloads.
## Facts
| | |
|---|---|
| Version | 3.10.7 |
| Published | 2026-08-17 |
| First published | 2023-07-24 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=24 |
| Dependencies | 0 |
| Unpacked size | 505.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 2 |
| Maintainers | rndnm, robot-dataui-npm, alexey_w100, 3y3, martyanov-av, vsesh, makhnatkin, diplodoc-bot, reazy015, goldserg, separatrix |
## Links
- npm: https://www.npmjs.com/package/@diplodoc/tabs-extension
- Repository: https://github.com/diplodoc-platform/tabs-extension
- Homepage: https://github.com/diplodoc-platform/tabs-extension#readme
- Issues: https://github.com/diplodoc-platform/tabs-extension/issues
- npm.io page: https://npm.io/package/@diplodoc/tabs-extension
## Recent versions
- 3.10.7 (latest) — 2026-08-17
- 3.5.0-beta1 (development) — 2024-10-07
- 3.10.6 — 2026-08-07
- 3.10.5 — 2026-07-27
- 3.10.4 — 2026-07-24
- 3.10.3 — 2026-07-22
- 3.10.2 — 2026-07-06
- 3.10.1 — 2026-05-28
- 3.10.0 — 2026-04-24
- 3.9.0 — 2026-01-28
- 3.8.0 — 2025-12-17
- 3.7.6 — 2025-12-11
- 3.7.5 — 2025-11-18
- 3.7.4 — 2025-11-05
- 3.7.3 — 2025-10-28
- … 42 more at https://npm.io/package/@diplodoc/tabs-extension/versions
## README
**english** | [русский](https://github.com/diplodoc-platform/tabs-extension/blob/master/README.ru.md)
---
[](https://www.npmjs.org/package/@diplodoc/tabs-extension)
[](https://sonarcloud.io/summary/new_code?id=diplodoc-platform_tabs-extension)
[](https://sonarcloud.io/summary/new_code?id=diplodoc-platform_tabs-extension)
[](https://sonarcloud.io/summary/new_code?id=diplodoc-platform_tabs-extension)
[](https://sonarcloud.io/summary/new_code?id=diplodoc-platform_tabs-extension)
[](https://sonarcloud.io/summary/new_code?id=diplodoc-platform_tabs-extension)
# Diplodoc tabs extension
This is an extension of the Diplodoc platform, which allows adding switchable tabs in the documentation.
The extension contains some parts:
- [Prepared runtime](#prepared-runtime)
- [MarkdownIt transform plugin](#markdownit-transform-plugin)
- [Tabs API](#api)
- [React hook for smart control](#react-hook-for-smart-control)
## Quickstart
Attach the plugin to the transformer:
```js
import tabsExtension from '@diplodoc/tabs-extension';
import transform from '@diplodoc/transform';
const {result} = await transform(
`
{% list tabs %}
- Tab 1
- Tab 2
- Tab 3
{% endlist %}
`,
{
plugins: [tabsExtension.transform({bundle: false})],
},
);
```
## Prepared runtime
It is necessary to add `runtime` scripts to make tabs interactive on your page.
You can add assets files which were generated by the [MarkdownIt transform plugin](#markdownit-transform-plugin).
```html
${result.html}
```
Or you can just include runtime's source code in your bundle.
```js
import '@diplodoc/tabs-extension/runtime';
import '@diplodoc/tabs-extension/runtime/styles.css';
```
## MarkdownIt transform plugin
Plugin for [@diplodoc/transform](https://github.com/diplodoc-platform/transform) package.
Options:
- `runtimeJsPath` - name on runtime script which will be exposed in results `script` section.
Default: `_assets/tabs-extension.js`
- `runtimeCssPath` - name on runtime css file which will be exposed in results `style` section.
(Default: `_assets/tabs-extension.css`)
- `bundle` - boolean flag to enable/disable copying of bundled runtime to target directory.
Where target directory is `/`
Default: `true`
- `containerClasses` - additional classes which will be added to tab's container node. It allows to customize the tabs view.
Example: `my-own-class and-other-class`
Default: `undefined`
## API
### Syntax
You can synchronize the opening of tabs between different tabs groups on the page. To do this, you just need to add optional property `group=` in `list tab` command. The active tabs with the same keys in one tabs group will be synchronized.
Example:
```
{% list tabs group=group_1 %}
- Tab 1
- Tab 2
- Tab 3
{% endlist %}
{% list tabs group=group_1 %}
- Tab 1
- Tab 2
- Tab 3
{% endlist %}
```
Additionally, you can use different render modes with:
```
{% list tabs %}
- Tab 1
Text 1.
* You can use list
* And **other** features.
- Tab 2
Text 2.
{% endlist %}
```
The keys for the tabs are generated automatically. They are based on the tab's names using the github anchors style.
You can set your own keys for tabs with this statement:
```
{% list tabs group=group_1 %}
- Tab 1 {#my-tab-1}
- Tab 2 {#my-tab-2}
{% endlist %}
```
## React component for easy installation
```tsx
import {TabsRuntime} from '@diplodoc/tabs-extension/react';
// ...
render() {
return (
<>
);
}
```
## Or you can use React hook for smart control
You can use the React hook to handle active tab changing or to select opened tabs programmatically.
```typeScript
import type { UseDiplodocTabsCallback, Tab } from '@diplodoc/tabs-extension/react';
import React, { useEffect, useCallback } from 'react';
import { useDiplodocTabs } from '@diplodoc/tabs-extension/react';
export const App: React.FC = () => {
// Callback function to handle tab selection
const selectTabHandler = useCallback(
(tab: Tab, currentTabId?: string) => {
const { group, key } = tab;
// Group could be empty
if (group) {
// Handle tab selection in a specific group
console.log(`Selected tab with group: ${group} and key: ${key}`);
} else {
// Handle tab selection without a specific group
console.log(`Selected tab with key: ${key}`);
}
},
[],
);
// Initialize the tabs hook with an optional callback
const {
selectTab,
selectTabById,
configure,
restoreTabs,
getTabsFromLocalStorage,
getTabsFromSearchQuery,
onPageChanged
} = useDiplodocTabs(selectTabHandler);
// useEffect to configure and setup state management
useEffect(() => {
// Configure the tabs when you want
configure({
// Enable saving tabs to local storage or not
saveTabsToLocalStorage: true,
// Enable saving tabs to the URL query state tied to the page
// 'all' - all tabs selection in all pages will be saved in URLSearchQuery
// 'page' (recommended) - all tabs selection in the current page will be saved in URLSearchQuery
// 'none' - no tabs selection will be saved in URLSearchQuery
saveTabsToQueryStateMode: 'page',
});
// Notify the tabs manager that the page has changed
// IMPORTANT: Must be called when page changed, and before restore tabs (to keep saveTabsToQueryStateMode: 'page' working correctly)
onPageChanged();
// Restore tabs from local storage and query state
restoreTabs({
...getTabsFromLocalStorage(), // Get tabs from local storage
// URLSearchQuery is primary before localStorage, because it can be provided
// queryExample: ?tabs=g0_cs,g1_macos_radio
// if not variant (third param) specified, it will be search regular tab (out of the box)
...getTabsFromSearchQuery(), // Get tabs from search query
});
}, [
configure,
restoreTabs,
getTabsFromLocalStorage,
getTabsFromSearchQuery,
onPageChanged
]);
// useEffect to programmatically select tabs
useEffect(() => {
// Select a tab by group and key
selectTab({ group: 'group_1', key: 'my-key' });
// Alternatively, select a tab by key
// selectTabById('my-key-2');
}, [selectTab, selectTabById]);
return (
/* Your component JSX here */
);
}
```
## Documentation
- **For AI agents** — see [AGENTS.md](AGENTS.md) and the guides in [docs/AGENTS/](docs/AGENTS/) (core concepts, dev infrastructure).
## For contributors
Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct, and the process for submitting pull requests to us.
---
_Source: https://npm.io/package/@diplodoc/tabs-extension · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._