Detailed Description

A Material 3 primary or secondary tab strip.

Tabs organize related views at the same level. Use primary tabs for the main sections of a screen and secondary tabs to divide content within one section. Primary tabs underline the displayed content; secondary tabs underline the full tab. The default variant is Primary and the default layout is Fixed. TabButton describes label, icon, badge, and accessibility customization.

Layout and overflow: Fixed tabs share the available width equally and retain at least 48 by 48 logical-pixel interaction targets. When their targets or badge paint bounds cannot fit, the bar scrolls horizontally. Set layoutMode to Scrollable for natural destination widths and longer labels. Scrollable tabs start after a 52 logical-pixel leading inset, mirrored in right-to-left layouts.

Hidden tabs occupy no layout space. Offscreen tabs remain in the native item model and accessible tree, and focused or selected destinations are revealed without moving external focus. Inherited padding, background implicit size, and insets contribute to the bar's implicit size.

Selection and keyboard interaction: The inherited count, contentModel, currentIndex, currentItem, itemAt(), addItem(), insertItem(), moveItem(), removeItem(), takeItem(), and setCurrentIndex() remain Qt Quick Templates APIs, including native empty, dynamic-item, and out-of-range behavior. Programmatic selection can address disabled or hidden destinations; user activation cannot.

Left and Right move focus in physical order, mirrored in right-to-left layouts, wrapping around available tabs and skipping disabled and hidden destinations. Home and End focus the logical boundaries. Arrow navigation changes focus only; Space or Enter activates the focused tab. The bar has one tab stop at its selected available tab or first available tab. Tab and Shift+Tab leave the tab list.

Connecting content: Bind a StackLayout's currentIndex to the bar so its visible page follows the selected tab. The content container owns its pages; applications should give associated panels meaningful accessible names.

import QtQuick
import QtQuick.Layouts
import Fluid as MD
 
ColumnLayout {
    MD.TabBar {
        id: tabs
        Layout.fillWidth: true
        variant: MD.TabBar.Primary
        layoutMode: MD.TabBar.Fixed
 
        MD.TabButton { text: qsTr("Overview"); icon.name: MD.Symbols.home }
        MD.TabButton { text: qsTr("Updates"); icon.name: MD.Symbols.notifications }
        MD.TabButton { text: qsTr("Saved"); icon.name: MD.Symbols.bookmark }
    }
 
    StackLayout {
        Layout.fillWidth: true
        Layout.fillHeight: true
        currentIndex: tabs.currentIndex
 
        MD.Label { text: qsTr("Overview content") }
        MD.Label { text: qsTr("Updates content") }
        MD.Label { text: qsTr("Saved content") }
    }
}

For swipeable pages, compose Qt Quick Controls SwipeView. Bind the bar's currentIndex to the view and route tab changes through setCurrentIndex() to preserve that binding and synchronize both directions without loops.

import QtQuick
import QtQuick.Controls as QC
import Fluid as MD
 
Column {
    MD.TabBar {
        id: tabs
        anchors.left: parent.left
        anchors.right: parent.right
        currentIndex: pages.currentIndex
 
        MD.TabButton { text: qsTr("Photos") }
        MD.TabButton { text: qsTr("Albums") }
        MD.TabButton { text: qsTr("Shared") }
        onCurrentIndexChanged: pages.setCurrentIndex(currentIndex)
    }
 
    QC.SwipeView {
        id: pages
        clip: true
        width: parent.width
        height: 400
 
        MD.Label { text: qsTr("Photos") }
        MD.Label { text: qsTr("Albums") }
        MD.Label { text: qsTr("Shared") }
    }
}

Surrounding layout and theme: A parent layout can place primary and secondary bars together, constrain their widths, or center a narrower group in a wide region. Use leading alignment instead when the surrounding content calls for a leading group.

import QtQuick.Layouts
import Fluid as MD
 
RowLayout {
    Layout.fillWidth: true
    MD.TabBar {
        Layout.alignment: Qt.AlignHCenter
        Layout.preferredWidth: 520
        Layout.maximumWidth: 680
        variant: MD.TabBar.Primary
        MD.TabButton { text: qsTr("Today") }
        MD.TabButton { text: qsTr("Week") }
        MD.TabButton { text: qsTr("Month") }
    }
}

Tabs inherit the active Fluid Style. Set MD.Style.theme to MD.Style.Light or MD.Style.Dark on a local parent to override the theme for its descendants. Container, indicator, divider, and tab content colors have semantic defaults. Keep app-bar attachment, sticky placement, page padding, and swipe gesture coordination in the surrounding layout. Avoid assigning horizontal swipe gestures to both the page container and a handler over the same area.

See also: TabButton, Badge Material tabs guidelines, Fluid tabs implementation.

Definition at line 145 of file TabBar.qml.

The documentation for this class was generated from the following file:

src/controls/qml/components/TabBar.qml