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.

Outputtabs.py

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.

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 `writable` `property` ¶

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.

Tabs¶

Clearing tabs¶

Adding tabs¶

Example¶

Reactive Attributes¶

Messages¶

Bindings¶

Component Classes¶

textual.widgets.Tabs class ¶

Parameters

BINDINGS class-attribute ¶

active instance-attribute class-attribute ¶

active_tab property ¶

tab_count property ¶

Cleared class ¶

Parameters

control property ¶

tabs instance-attribute ¶

TabActivated class ¶

TabDisabled class ¶

TabEnabled class ¶

TabError class ¶

TabHidden class ¶

TabMessage class ¶

Parameters

ALLOW_SELECTOR_MATCH instance-attribute class-attribute ¶

control property ¶

tab instance-attribute ¶

tabs instance-attribute ¶

TabShown class ¶

action_next_tab method ¶

action_previous_tab method ¶

add_tab method ¶

Parameters

Returns

Raises

clear method ¶

Returns

disable method ¶

Parameters

Returns

Raises

enable method ¶

Parameters

Returns

Raises

hide method ¶

Parameters

Returns

Raises

remove_tab method ¶

Parameters

Returns

show method ¶

Parameters

Returns

Raises

validate_active method ¶

watch_active method ¶

textual.widgets.Tab class ¶

Parameters

label writable property ¶

label_text property ¶

Clicked class ¶

Disabled class ¶

Enabled class ¶

Relabelled class ¶

TabMessage class ¶

control property ¶

tab instance-attribute ¶

textual.widgets.Tabs `class` ¶

BINDINGS `class-attribute` ¶

active `instance-attribute` `class-attribute` ¶

active_tab `property` ¶

tab_count `property` ¶

Cleared `class` ¶

control `property` ¶

tabs `instance-attribute` ¶

TabActivated `class` ¶

TabDisabled `class` ¶

TabEnabled `class` ¶

TabError `class` ¶

TabHidden `class` ¶

TabMessage `class` ¶

ALLOW_SELECTOR_MATCH `instance-attribute` `class-attribute` ¶

control `property` ¶

tab `instance-attribute` ¶

tabs `instance-attribute` ¶

TabShown `class` ¶

action_next_tab `method` ¶

action_previous_tab `method` ¶

add_tab `method` ¶

clear `method` ¶

disable `method` ¶

enable `method` ¶

hide `method` ¶

remove_tab `method` ¶

show `method` ¶

validate_active `method` ¶

watch_active `method` ¶

textual.widgets.Tab `class` ¶

label `writable` `property` ¶

label_text `property` ¶

Clicked `class` ¶

Disabled `class` ¶

Enabled `class` ¶

Relabelled `class` ¶

TabMessage `class` ¶

control `property` ¶

tab `instance-attribute` ¶