# tabs

URL: /patitas/api/directives/builtins/tabs/
Section: builtins
Description: Tab directives for tabbed content.

Provides tabbed content sections with full markdown support including
nested directives, code blocks, and admonitions.

Supports two rendering modes:
- "enhanced" (default): JavaScript-based tabs with data-tab-target
- "css_state_machine": URL-driven tabs using :target CSS selector

Tab-Item Options:
:selected: - Whether this tab is initially selected
:icon: - Icon name to show next to tab label
:badge: - Badge text (e.g., "New", "Beta", "Pro")
:disabled: - Mark tab as disabled/unavailable

Example:
:::{tab-set}
:sync: language

:::{tab-item} Python
:icon: python
:selected:

Content for Python tab.
:::

:::{tab-item} JavaScript
:badge: Popular

Content for JavaScript tab.
:::

:::

Thread Safety:
Stateless handlers. Safe for concurrent use across threads.

---

> For a complete page index, fetch /patitas/llms.txt.

Open LLM text
(/patitas/api/directives/builtins/tabs/index.txt)

Share with AI

Ask Claude
(https://claude.ai/new?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpatitas%2Fapi%2Fdirectives%2Fbuiltins%2Ftabs%2Findex.txt)

Ask ChatGPT
(https://chatgpt.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpatitas%2Fapi%2Fdirectives%2Fbuiltins%2Ftabs%2Findex.txt)

Ask Gemini
(https://gemini.google.com/app?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpatitas%2Fapi%2Fdirectives%2Fbuiltins%2Ftabs%2Findex.txt)

Ask Copilot
(https://copilot.microsoft.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpatitas%2Fapi%2Fdirectives%2Fbuiltins%2Ftabs%2Findex.txt)

Module

#
`directives.builtins.tabs`

Tab directives for tabbed content.

Provides tabbed content sections with full markdown support including
nested directives, code blocks, and admonitions.

Supports two rendering modes:

- "enhanced" (default): JavaScript-based tabs with data-tab-target

- "css_state_machine": URL-driven tabs using :target CSS selector

Tab-Item Options:
:selected: - Whether this tab is initially selected
:icon: - Icon name to show next to tab label
:badge: - Badge text (e.g., "New", "Beta", "Pro")
:disabled: - Mark tab as disabled/unavailable

Example:

- Python (#)

- JavaScriptPopular (#)

Content for Python tab.

Content for JavaScript tab.

Thread Safety:

Stateless handlers. Safe for concurrent use across threads.

5Classes1Function

## Classes

`TabItemOptions`

5

▼

Options for tab-item directive.

Bases:

`StyledOptions (/patitas/api/directives/options/#StyledOptions)`

Options for tab-item directive.

#### Attributes

Name
Type
Description

`selected`

`bool`

Whether this tab is initially selected

`icon`

`str | None`

Icon name to show next to tab label

`badge`

`str | None`

Badge text (e.g., "New", "Beta", "Pro")

`disabled`

`bool`

Mark tab as disabled/unavailable

`sync`

`str | None`

—

`TabSetOptions`

3

▼

Options for tab-set directive.

Bases:

`StyledOptions (/patitas/api/directives/options/#StyledOptions)`

Options for tab-set directive.

#### Attributes

Name
Type
Description

`id`

`str | None`

Unique ID for the tab set

`sync`

`str | None`

Sync key for synchronizing tabs across multiple tab-sets

`mode`

`str | None`

Rendering mode - "enhanced" (JS) or "css_state_machine" (URL-driven)

`TabItemData`

6

▼

Data extracted from a rendered tab-item div.

Data extracted from a rendered tab-item div.

#### Attributes

Name
Type
Description

`title`

`str`

—

`selected`

`str`

—

`icon`

`str`

—

`badge`

`str`

—

`disabled`

`str`

—

`content`

`str`

—

`TabItemDirective`

7

▼

Handler for tab-item directive.

Must be inside a tab-set container.

Thread Safety:
Stateless …

Handler for tab-item directive.

Must be inside a tab-set container.

Thread Safety:

```
Stateless handler. Safe for concurrent use.
```

#### Attributes

Name
Type
Description

`names`

`ClassVar[tuple[str, ...]]`

—

`token_type`

`ClassVar[str]`

—

`contract`

`ClassVar[DirectiveContract (/patitas/api/directives/contracts/#DirectiveContract) | None]`

—

`options_class`

`ClassVar[type[TabItemOptions]]`

—

`preserves_raw_content`

`ClassVar[bool]`

—

#### Methods

`parse`

6

`Directive (/patitas/api/nodes/#Directive)[TabItemOptions]`

▼

Build tab-item AST node.

`def parse(self, name: str, title: str | None, options: TabItemOptions, content: str, children: Sequence[Block], location: SourceLocation) -> Directive[TabItemOptions]`

##### Parameters

Name
Type
Description

`name`
`—`

`title`
`—`

`options`
`—`

`content`
`—`

`children`
`—`

`location`
`—`

##### Returns

`Directive (/patitas/api/nodes/#Directive)[TabItemOptions]`

`render`

3

▼

Render tab-item to HTML.

Creates a wrapper div with metadata that the parent t…

`def render(self, node: Directive[TabItemOptions], rendered_children: str, sb: StringBuilder) -> None`

Render tab-item to HTML.

Creates a wrapper div with metadata that the parent tab-set
will parse to build the navigation and panels.

##### Parameters

Name
Type
Description

`node`
`—`

`rendered_children`
`—`

`sb`
`—`

`TabSetDirective`

10

▼

Handler for tab-set container directive.

Contains tab-item children that form a tabbed interface.
…

Handler for tab-set container directive.

Contains tab-item children that form a tabbed interface.

Thread Safety:

```
Stateless handler. Safe for concurrent use.
```

#### Attributes

Name
Type
Description

`names`

`ClassVar[tuple[str, ...]]`

—

`token_type`

`ClassVar[str]`

—

`contract`

`ClassVar[DirectiveContract (/patitas/api/directives/contracts/#DirectiveContract) | None]`

—

`options_class`

`ClassVar[type[TabSetOptions]]`

—

`preserves_raw_content`

`ClassVar[bool]`

—

#### Methods

`parse`

6

`Directive (/patitas/api/nodes/#Directive)[TabSetOptions]`

▼

Build tab-set AST node.

`def parse(self, name: str, title: str | None, options: TabSetOptions, content: str, children: Sequence[Block], location: SourceLocation) -> Directive[TabSetOptions]`

##### Parameters

Name
Type
Description

`name`
`—`

`title`
`—`

`options`
`—`

`content`
`—`

`children`
`—`

`location`
`—`

##### Returns

`Directive (/patitas/api/nodes/#Directive)[TabSetOptions]`

`render`

3

▼

Render tab-set to HTML.

Extracts tab items from rendered children and builds
n…

`def render(self, node: Directive[TabSetOptions], rendered_children: str, sb: StringBuilder) -> None`

Render tab-set to HTML.

Extracts tab items from rendered children and builds
navigation + content panels.

##### Parameters

Name
Type
Description

`node`
`—`

`rendered_children`
`—`

`sb`
`—`

Internal Methods
3

▼

`_render_enhanced`

4

▼

Render JavaScript-enhanced tabs (default mode).

`def _render_enhanced(self, tab_id: str, sync_key: str, matches: list[TabItemData], sb: StringBuilder) -> None`

##### Parameters

Name
Type
Description

`tab_id`
`—`

`sync_key`
`—`

`matches`
`—`

`sb`
`—`

`_render_css_state_machine`

4

▼

Render CSS state machine tabs (URL-driven, no JS required).

`def _render_css_state_machine(self, tab_id: str, sync_key: str, matches: list[TabItemData], sb: StringBuilder) -> None`

##### Parameters

Name
Type
Description

`tab_id`
`—`

`sync_key`
`—`

`matches`
`—`

`sb`
`—`

`_slugify`

1

`str`

▼

Convert text to URL-safe slug.

`def _slugify(self, text: str) -> str`

##### Parameters

Name
Type
Description

`text`
`—`

##### Returns

`str`

## Functions

`_extract_tab_items`

1

`list[TabItemData (/patitas/api/directives/builtins/tabs/#TabItemData)]`

▼

Extract tab-item divs from rendered HTML, handling nested divs correctly.

`def _extract_tab_items(text: str) -> list[TabItemData]`

##### Parameters

Name
Type
Description

`text`
`str`

Rendered HTML containing tab-item divs

##### Returns

`list[TabItemData (/patitas/api/directives/builtins/tabs/#TabItemData)]`