Detailed Description

A passive Material Design 3 notification dot or short label.

Auto chooses Small without valid content and Large otherwise. Nonempty text takes precedence over count. Counts are valid only when finite, nonnegative, integral, and within the safe-integer range; zero displays as 0 and invalid values behave as unset. Counts above Tokens.badge.maximumCount display the maximum followed by +. Both visible and accessible counts use the control locale. Status text longer than four grapheme clusters displays its first three clusters and U+2026. Small suppresses the visible label while retaining the full value in accessibleDescription. Large without content displays an empty large container.

The inherited visible property defaults to true. The default typescale is LabelSmall. Set typescale to another Tokens.typescale value to select its font family, size, weight, tracking, and line height, as with Label. Explicit local font overrides are honored. Large grows to fit the measured label and font instead of capping width. Container and content colors default to the active error/on-error semantic pair. Input is disabled by default so pointer and touch events reach the host beneath the badge. Reenabling Badge is unsupported for passive use; its appearance is independent of enabled and no focus, hover, or wheel interaction is added.

Badges create no accessible or interactive node. Hosts include the full accessibleDescription after the destination name, separated by a comma, while the badge is rendered. Hidden badges contribute no stale information. If an application overrides the host's complete Accessible.name, it must compose badge information itself. There are no automatic live announcements. Supply translated descriptions with correct plural forms and context when a raw value or the generic New notification description is insufficient.

Host badgeContent maps strings to text and numbers to count. badgeNotification requests Small even with content; badgeVisible controls rendering and the default accessible name. These properties default from a Fluid Action when supplied. Hosts own activation and clearing. Change application-owned content/notification bindings when unread state is cleared; Badge never clears caller state.

MD.IconButton {
    text: qsTr("Inbox")
    icon.name: MD.Symbols.mail
    badgeContent: unreadCount
    badgeVisible: unreadCount > 0
    badgeAccessibleDescription: qsTr("%n unread message(s)", "", unreadCount)
    onClicked: unreadCount = 0
}

BadgeOverlay accepts an explicit sibling Item around the actual icon bounds in a shared untransformed coordinate space. Growth keeps the logical leading anchor fixed, layoutMirrored supplies RTL placement, and ancestor clipping applies without automatic repositioning. NavigationRailItem uses an icon overlay when collapsed or icon-only, and a trailing Large badge beside an expanded label. App-bar icon actions always present Small while retaining the full accessible value. TabButton places badges beside inline labels or overlapping stacked and icon-only icons, using the tab-specific spacing and overlap metrics.

Item {
    id: composition
    Item {
        id: iconBounds
        // Set x/y/width/height to the actual icon bounds.
    }
    MD.BadgeOverlay {
        target: iconBounds
        layoutMirrored: host.mirrored
        count: unreadCount
    }
}

See also: BadgeOverlay, IconButton, NavigationRailItem Material badge guidelines.

Definition at line 82 of file Badge.qml.

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

src/controls/qml/components/Badge.qml