Detailed Description

A Material 3 tab using the native Qt tab selection contract.

Place buttons directly inside TabBar. Qt's attached TabBar.tabBar relationship supplies the owner and effectiveVariant; a standalone button uses Primary. Selection, Action, clicked, checked, enabled, and dynamic-item behavior remain Qt Quick Templates APIs. TabBar describes layout, navigation, and connecting tabs to StackLayout or SwipeView content.

Labels and icons: Primary tabs default to TextUnderIcon and secondary tabs to TextBesideIcon. Secondary icon-and-label content is always inline. TextOnly and IconOnly suppress the corresponding content without reserving its space. Keep labels concise and consistent within a bar; icon-only tabs are exceptional and need an explicit Accessible.name describing their destination.

Long labels are elided on one line by default. Prefer a scrollable bar for longer labels, or set maximumLineCount to 2 to wrap onto two lines before elision. Labels default to the titleSmall type scale; typescale and explicit font overrides customize typography. Natural height grows with font metrics and multiline content. Padding, background size, and insets contribute to implicit size while preserving the minimum interaction target.

MD.TabButton {
    text: qsTr("A longer destination label")
    maximumLineCount: 2
}
 
MD.TabButton {
    icon.name: MD.Symbols.settings
    display: MD.TabButton.IconOnly
    Accessible.name: qsTr("Settings destination")
}

Badges and accessible descriptions: Set badgeContent to a number or string for a count or status badge, or set badgeNotification for a dot. badgeVariant chooses Badge.Small, Badge.Large, or Badge.Auto. Badge properties default from a Fluid Action when supplied. badgeVisible controls rendering, and a badge is shown only when it has valid content or a notification. Badges remain passive and create no separate accessible or interactive node.

Inline badges contribute to a primary indicator's content width. Stacked and icon-only badges overlap the icon without changing that width. Natural size reserves badge paint bounds so overlays remain visible; fixed bars retain equal widths and can scroll when those bounds need more space.

badgeAccessibleDescription supplies a localized full description, included in the default accessible name while the badge is shown. If an application overrides Accessible.name, it must include meaningful badge information itself. Hidden or cleared badges contribute no stale description. Counts above 999 display a localized 999+; status strings longer than four grapheme clusters display their first three clusters followed by an ellipsis.

Applications own notification state and should update or clear it after the related content has been viewed. Badge never clears caller state.

MD.TabBar {
    id: tabs
    property int unreadCount: 12
 
    MD.TabButton { text: qsTr("Overview") }
    MD.TabButton {
        text: qsTr("Messages")
        icon.name: MD.Symbols.mail
        badgeContent: tabs.unreadCount
        badgeVisible: tabs.unreadCount > 0
        badgeAccessibleDescription: qsTr("%n unread message(s)", "", tabs.unreadCount)
        onClicked: tabs.unreadCount = 0
    }
}

Theme and interaction: Container, content, and state-layer colors resolve through attached Style and inherit local or ancestor theme overrides. icon.color overrides the icon independently; disable tintSourceIcon for multicolor source artwork. Disabled destinations remain visible but cannot be focused or activated by the user. Programmatic selection follows the native Qt tab bar contract. Focus remains distinct from selection: arrows move focus, while Space or Enter uses the native press, release, and cancellation lifecycle to activate the destination. Tab and Shift+Tab leave the bar's single tab stop.

See also: TabBar, Badge, Action Material tabs guidelines.

Definition at line 97 of file TabButton.qml.

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

src/controls/qml/components/TabButton.qml