Skip to content

Tabs

Added in version 0.15.0

Displays a number of tab headers which may be activated with a click or navigated with cursor keys.

  • Focusable
  • Container

Construct a Tabs widget with strings or Text objects as positional arguments, which will set the labels in the tabs. Here's an example with three tabs:

def compose(self) -> ComposeResult:
    yield Tabs("First tab", "Second tab", Text.from_markup("[u]Third[/u] tab"))

This will create Tab widgets internally, with auto-incrementing id attributes ("tab-1", "tab-2" etc). You can also supply Tab objects directly in the constructor, which will allow you to explicitly set an id. Here's an example:

def compose(self) -> ComposeResult:
    yield Tabs(
        Tab("First tab", id="one"),
        Tab("Second tab", id="two"),
    )

When the user switches to a tab by clicking or pressing keys, then Tabs will send a Tabs.TabActivated message which contains the tab that was activated. You can then use event.tab.id attribute to perform any related actions.

Clearing tabs

Clear tabs by calling the clear method. Clearing the tabs will send a Tabs.TabActivated message with the tab attribute set to None.

Adding tabs

Tabs may be added dynamically with the add_tab method, which accepts strings, Text, or Tab objects.

Example

The following example adds a Tabs widget above a text label. Press A to add a tab, C to clear the tabs.

TabsApp  AtreidiesDuke Leto AtreidesLady JessicaGurney HalleckBaron Vladimir ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔ Lady Jessica ▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁  A  Add tab  R  Remove active tab  C  Clear tabs 

from textual.app import App, ComposeResult
from textual.widgets import Footer, Label, Tabs

NAMES = [
    "Paul Atreidies",
    "Duke Leto Atreides",
    "Lady Jessica",
    "Gurney Halleck",
    "Baron Vladimir Harkonnen",
    "Glossu Rabban",
    "Chani",
    "Silgar",
]


class TabsApp(App):
    """Demonstrates the Tabs widget."""

    CSS = """
    Tabs {
        dock: top;
    }
    Screen {
        align: center middle;
    }
    Label {
        margin:1 1;
        width: 100%;
        height: 100%;
        background: $panel;
        border: tall $primary;
        content-align: center middle;
    }
    """

    BINDINGS = [
        ("a", "add", "Add tab"),
        ("r", "remove", "Remove active tab"),
        ("c", "clear", "Clear tabs"),
    ]

    def compose(self) -> ComposeResult:
        yield Tabs(NAMES[0])
        yield Label()
        yield Footer()

    def on_mount(self) -> None:
        """Focus the tabs when the app starts."""
        self.query_one(Tabs).focus()

    def on_tabs_tab_activated(self, event: Tabs.TabActivated) -> None:
        """Handle TabActivated message sent by Tabs."""
        label = self.query_one(Label)
        if event.tab is None:
            # When the tabs are cleared, event.tab will be None
            label.visible = False
        else:
            label.visible = True
            label.update(event.tab.label)

    def action_add(self) -> None:
        """Add a new tab."""
        tabs = self.query_one(Tabs)
        # Cycle the names
        NAMES[:] = [*NAMES[1:], NAMES[0]]
        tabs.add_tab(NAMES[0])

    def action_remove(self) -> None:
        """Remove active tab."""
        tabs = self.query_one(Tabs)
        active_tab = tabs.active_tab
        if active_tab is not None:
            tabs.remove_tab(active_tab.id)

    def action_clear(self) -> None:
        """Clear the tabs."""
        self.query_one(Tabs).clear()


if __name__ == "__main__":
    app = TabsApp()
    app.run()

Reactive Attributes

Name Type Default Description
active str "" The ID of the active tab. Set this attribute to a tab ID to change the active tab.

Messages

Bindings

The Tabs widget defines the following bindings:

Key(s) Description
left Move to the previous tab.
right Move to the next tab.

Component Classes

This widget has no component classes.


textual.widgets.Tabs class

def __init__(
    self,
    *tabs,
    active=None,
    name=None,
    id=None,
    classes=None,
    disabled=False
):

Bases: Widget

A row of tabs.

Parameters
Parameter Default Description
*tabs
Tab | TextType
()

Positional argument should be explicit Tab objects, or a str or Text.

active
str | None
None

ID of the tab which should be active on start.

name
str | None
None

Optional name for the input widget.

id
str | None
None

Optional ID for the widget.

classes
str | None
None

Optional initial classes for the widget.

disabled
bool
False

Whether the input is disabled or not.

BINDINGS class-attribute

BINDINGS: list[BindingType] = [
    Binding(
        "left", "previous_tab", "Previous tab", show=False
    ),
    Binding("right", "next_tab", "Next tab", show=False),
]
Key(s) Description
left Move to the previous tab.
right Move to the next tab.

active instance-attribute class-attribute

active: reactive[str] = reactive('', init=False)

The ID of the active tab, or empty string if none are active.

active_tab property

active_tab: Tab | None

The currently active tab, or None if there are no active tabs.

tab_count property

tab_count: int

Total number of tabs.

Cleared class

def __init__(self, tabs):

Bases: Message

Sent when there are no active tabs.

This can occur when Tabs are cleared, if all tabs are hidden, or if the currently active tab is unset.

Parameters
Parameter Default Description
tabs
Tabs
required

The tabs widget.

control property

control: Tabs

The tabs widget which was cleared.

This is an alias for Cleared.tabs which is used by the on decorator.

tabs instance-attribute

tabs: Tabs = tabs

The tabs widget which was cleared.

TabActivated class

Bases: TabMessage

Sent when a new tab is activated.

TabDisabled class

Bases: TabMessage

Sent when a tab is disabled.

TabEnabled class

Bases: TabMessage

Sent when a tab is enabled.

TabError class

Bases: Exception

Exception raised when there is an error relating to tabs.

TabHidden class

Bases: TabMessage

Sent when a tab is hidden.

TabMessage class

def __init__(self, tabs, tab):

Bases: Message

Parent class for all messages that have to do with a specific tab.

Parameters
Parameter Default Description
tabs
Tabs
required

The Tabs widget.

tab
Tab
required

The tab that is the object of this message.

ALLOW_SELECTOR_MATCH instance-attribute class-attribute

ALLOW_SELECTOR_MATCH = {'tab'}

Additional message attributes that can be used with the on decorator.

control property

control: Tabs

The tabs widget containing the tab that is the object of this message.

This is an alias for the attribute tabs and is used by the on decorator.

tab instance-attribute

tab: Tab = tab

The tab that is the object of this message.

tabs instance-attribute

tabs: Tabs = tabs

The tabs widget containing the tab.

TabShown class

Bases: TabMessage

Sent when a tab is shown.

action_next_tab method

def action_next_tab(self):

Make the next tab active.

action_previous_tab method

def action_previous_tab(self):

Make the previous tab active.

add_tab method

def add_tab(self, tab, *, before=None, after=None):

Add a new tab to the end of the tab list.

Parameters
Parameter Default Description
tab
Tab | str | Text
required

A new tab object, or a label (str or Text).

before
Tab | str | None
None

Optional tab or tab ID to add the tab before.

after
Tab | str | None
None

Optional tab or tab ID to add the tab after.

Returns
Type Description
AwaitComplete

An optionally awaitable object that waits for the tab to be mounted and internal state to be fully updated to reflect the new tab.

Raises
Type Description
Tabs.TabError

If there is a problem with the addition request.

Note

Only one of before or after can be provided. If both are provided a Tabs.TabError will be raised.

clear method

def clear(self):

Clear all the tabs.

Returns
Type Description
AwaitComplete

An awaitable object that waits for the tabs to be removed.

disable method

def disable(self, tab_id):

Disable the indicated tab.

Parameters
Parameter Default Description
tab_id
str
required

The ID of the Tab to disable.

Returns
Type Description
Tab

The Tab that was targeted.

Raises
Type Description
TabError

If there are any issues with the request.

enable method

def enable(self, tab_id):

Enable the indicated tab.

Parameters
Parameter Default Description
tab_id
str
required

The ID of the Tab to enable.

Returns
Type Description
Tab

The Tab that was targeted.

Raises
Type Description
TabError

If there are any issues with the request.

hide method

def hide(self, tab_id):

Hide the indicated tab.

Parameters
Parameter Default Description
tab_id
str
required

The ID of the Tab to hide.

Returns
Type Description
Tab

The Tab that was targeted.

Raises
Type Description
TabError

If there are any issues with the request.

remove_tab method

def remove_tab(self, tab_or_id):

Remove a tab.

Parameters
Parameter Default Description
tab_or_id
Tab | str | None
required

The Tab to remove or its id.

Returns
Type Description
AwaitComplete

An optionally awaitable object that waits for the tab to be removed.

show method

def show(self, tab_id):

Show the indicated tab.

Parameters
Parameter Default Description
tab_id
str
required

The ID of the Tab to show.

Returns
Type Description
Tab

The Tab that was targeted.

Raises
Type Description
TabError

If there are any issues with the request.

validate_active method

def validate_active(self, active):

Check id assigned to active attribute is a valid tab.

watch_active method

def watch_active(self, previously_active, active):

Handle a change to the active tab.


textual.widgets.Tab class

def __init__(
    self, label, *, id=None, classes=None, disabled=False
):

Bases: Static

A Widget to manage a single tab within a Tabs widget.

Parameters
Parameter Default Description
label
TextType
required

The label to use in the tab.

id
str | None
None

Optional ID for the widget.

classes
str | None
None

Space separated list of class names.

disabled
bool
False

Whether the tab is disabled or not.

label property writable

label: Text

The label for the tab.

label_text property

label_text: str

Undecorated text of the label.

Clicked class

Bases: TabMessage

A tab was clicked.

Disabled class

Bases: TabMessage

A tab was disabled.

Enabled class

Bases: TabMessage

A tab was enabled.

Relabelled class

Bases: TabMessage

A tab was relabelled.

TabMessage class

Bases: Message

Tab-related messages.

These are mostly intended for internal use when interacting with Tabs.

control property

control: Tab

The tab that is the object of this message.

This is an alias for the attribute tab and is used by the on decorator.

tab instance-attribute

tab: Tab

The tab that is the object of this message.