QML
← All components

Tooltip

Show a brief hint beside a control when it is hovered or focused.

import Syidax.Core.Tooltip

Supported QML types

TypeDefinition / role
Brief contextual hint anchored to a target on hover or focus.

Learn by example

Previews are images of native Qt runs. Use the buttons below each image to view a result.

01 Basic composition

SyTooltip is a small dark label that floats next to the item it is declared in — declare it inside a button, an icon or a field and that item becomes its anchor.

Qt capture · image
Basic composition · Opened
QML code
import QtQuick
import Syidax.Core

Item {
    implicitWidth: Math.max(360, childrenRect.width)
    implicitHeight: childrenRect.height

    property QtObject settings: QtObject {
        id: storyArgs
        property string content: "Saves the form"
        property string position: "top"
        property string trigger: "hover"
        property bool hideArrow: false
        property int opendelay: 0
        property int closedelay: 0
        property int maxWidth: 320
        property string animation: "none"
    }

    

    Item {
        width: 320
        height: 120
        SyButton {
            anchors.centerIn: parent
            text: "Save"
            SyTooltip { id: exampleControl1; 
                content: storyArgs.content
                position: storyArgs.position
                trigger: storyArgs.trigger
                hideArrow: storyArgs.hideArrow
                opendelay: storyArgs.opendelay
                closedelay: storyArgs.closedelay
                maxWidth: storyArgs.maxWidth
                animation: storyArgs.animation
            }
        }
    }

}

02 position

Compare the configuration and result of position.

Qt capture · image
position · Default
Default execution
QML code
import QtQuick
import Syidax.Core

pragma ComponentBehavior: Bound

Item {
    implicitWidth: Math.max(360, childrenRect.width)
    implicitHeight: childrenRect.height
    id: story
    readonly property var positions: ["topLeft", "top", "topRight", "leftTop", "rightTop", "left", "right", "leftBottom", "rightBottom", "bottomLeft", "bottom", "bottomRight"]

    Item {
        width: 600
        height: 340
        Grid {
            anchors.centerIn: parent
            columns: 3
            columnSpacing: 110
            rowSpacing: 60
            Repeater {
                model: story.positions
                delegate: SyButton {
                    id: cell
                    required property string modelData
                    text: cell.modelData
                    width: 120
                    SyTooltip { content: cell.modelData; position: cell.modelData; trigger: "none"; Component.onCompleted: Qt.callLater(setOpen) }
                }
            }
        }
    }
}

03 trigger

Compare the results of pointer hover, a button click and field focus.

Qt capture · image
trigger · Hover result
QML code
import QtQuick
import Syidax.Core

Item {
    width: 520; height: 180
    Row {
        x: 24; y: 28; spacing: 40
        SyButton {
            id: hoverTarget; text: "hover"
            SyTooltip { id: hoverPopup; position: "bottom"; content: "Shown while the pointer is over the button" }
        }
        SyButton {
            id: clickTarget; text: "click"
            SyTooltip { id: clickPopup; trigger: "click"; position: "bottom"; content: "Shown after clicking the button" }
        }
        FocusScope {
            id: focusAnchor; width: 150; height: focusTarget.height
            SyInput {
                id: focusTarget; placeholder: "focus"; width: parent.width
                SyTooltip { id: focusPopup; anchor: focusAnchor; trigger: "focus"; position: "bottom"; content: "Shown while the field has focus" }
            }
        }
    }
}

04 opendelay · closedelay · maxWidth · hideArrow · animation

Timing and look.

Qt capture · image
opendelay · closedelay · maxWidth · hideArrow · animation · Opened
QML code
import QtQuick
import Syidax.Core

Item {
    implicitWidth: Math.max(360, childrenRect.width)
    implicitHeight: childrenRect.height
    // Focused Gallery routes: keep only the selected API and its prerequisites.
    id: featureStory

    Row {
        spacing: 16
        SyButton { text: "Slow"; SyTooltip { id: featureTarget0; content: "Half a second to open, 300 ms to close"; opendelay: 500; closedelay: 300 } }
        SyButton { text: "Long text"; SyTooltip { id: featureTarget1; content: "The content of this area is being fetched. It stays readable until the spinner masks it."; maxWidth: 220 } }
        SyButton { text: "Plain"; SyTooltip { id: featureTarget2; content: "No arrow, fades in"; hideArrow: true; animation: "fade"; animationSpeed: "slow" } }
    }
}

05 setOpen · setClose · close

setOpen() opens the tooltip and setClose() closes it from code, whatever the trigger — both cancel a pending delay timer, and setOpen() still refuses a disabled or readonly anchor.

Qt capture · image
setOpen · setClose · close · Opened
QML code
import QtQuick
import Syidax.Core

Item {
    implicitWidth: Math.max(360, childrenRect.width)
    implicitHeight: childrenRect.height
    // Focused Gallery routes: keep only the selected API and its prerequisites.
    id: featureStory

    Column {
        spacing: 24
        Item {
            width: 560; height: 150
            SyButton {
                x: 24; y: 24
 text: "Save"; SyTooltip { id: tip; content: "Saves the form"; trigger: "none" } }
        }
        Row {
            objectName: "exampleCommands"

            spacing: 8
            SyButton { id: exampleControl1;  visible: true; text: "tip.setOpen()"; variant: "secondary"; size: "small"; onClicked: tip.setOpen() }
            SyButton { id: exampleControl2;  visible: true; text: "tip.setClose()"; variant: "secondary"; size: "small"; onClicked: tip.setClose() }
            SyButton { id: exampleControl3;  visible: true; text: "tip.close()"; variant: "secondary"; size: "small"; onClicked: tip.close() }
        }
        Text {
            text: "tip.isOpen === " + tip.isOpen
            font.family: Theme.monoFontFamily
            font.pixelSize: 12
            color: Theme.semantic.textSubtle
        }
    }
}

06 Click to explain

Click to explain, configured with trigger.

Qt capture · image
Click to explain · Opened
QML code
import QtQuick
import Syidax.Core

Item {
    implicitWidth: Math.max(360, childrenRect.width)
    implicitHeight: childrenRect.height

    property QtObject settings: QtObject {
        id: storyArgs
        property string content: "Saves the form"
        property string position: "top"
        property string trigger: "click"
        property bool hideArrow: false
        property int opendelay: 0
        property int closedelay: 0
        property int maxWidth: 320
        property string animation: "none"
    }

    

    Item {
        width: 320
        height: 120
        SyButton {
            anchors.centerIn: parent
            text: "Save"
            SyTooltip { id: exampleControl1; 
                content: storyArgs.content
                position: storyArgs.position
                trigger: storyArgs.trigger
                hideArrow: storyArgs.hideArrow
                opendelay: storyArgs.opendelay
                closedelay: storyArgs.closedelay
                maxWidth: storyArgs.maxWidth
                animation: storyArgs.animation
            }
        }
    }

}

API 62

Hover or select an item for its QML example and copy button.

Properties

PropertyTypeDefaultDescription
string""The text; n breaks lines.
string"top""top" · "topLeft" · "topRight" · "bottom" · "bottomLeft" · "bottomRight" · "left" · "leftTop" · "leftBottom" · "right" · "rightTop" · "rightBottom".
string"hover""hover" · "click" · "focus" · "none".
int0Milliseconds before opening / closing after the trigger event.
int0Milliseconds before opening / closing after the trigger event.
int320Maximum text width in pixels, also limited by the window. Long help wraps automatically; 0 explicitly disables wrapping.
boolfalseDrop the arrow (the tooltip then sits 4 px from the anchor instead of 10 px).
boolfalseNever closes by itself; only setClose() / close().
string"none""none" · "fade"; speed "x-fast" · "fast" · "medium" · "slow" · "x-slow".
string"fast""none" · "fade"; speed "x-fast" · "fast" · "medium" · "slow" · "x-slow".
Itemthe item it is declared inThe item it follows; resolved to the nearest ancestor with hovered within three levels.
bool (read-only)—The tooltip is visible.
string (read-only)—The side after flipping: top · bottom · left · right, optionally -start / -end.
bool!hideArrowThe base popup's arrow switch; bound to hideArrow.
colortooltip tokensThe surface look; override only for a custom style.
colortransparentThe surface look; override only for a custom style.
real2The surface look; override only for a custom style.
boolfalseThe surface look; override only for a custom style.
real10 / 4Base popup geometry: distance to the anchor, side flipping, anchor-width matching.
booltrueBase popup geometry: distance to the anchor, side flipping, anchor-width matching.
boolfalseBase popup geometry: distance to the anchor, side flipping, anchor-width matching.
read-only—The resolved speed, the current side, whether the anchor accepts opening, the anchor's rectangle in overlay coordinates.
read-only—The resolved speed, the current side, whether the anchor accepts opening, the anchor's rectangle in overlay coordinates.
read-only—The resolved speed, the current side, whether the anchor accepts opening, the anchor's rectangle in overlay coordinates.
read-only—The resolved speed, the current side, whether the anchor accepts opening, the anchor's rectangle in overlay coordinates.

Methods

MethodDescription
Cancels pending delays and opens, whatever the trigger — unless the anchor is disabled / readonly / not enabled.
Cancels pending delays and closes, even when sticky.
The base popup's close: hides at once and cancels a pending opendelay (as Escape and an outside press do).
The base popup's open: opens even on a non-interactive anchor; no delay.
setClose() when open, otherwise a trigger-style open request (delays and anchor checks apply).
Re-computes the placement; called automatically on anchor, size and window changes.

Signals

ItemBehavior / conditions
Emitted just before the popup is shown.
Emitted after the popup finishes its enter transition.
Emitted just before the popup is hidden.
Emitted after the popup finishes its exit transition.
Property notification emitted when visible changes.
Property notification emitted when isOpen changes.

Behavior

ItemBehavior / conditions
The item it follows; resolved to the nearest ancestor with hovered within three levels.
Interactive anchor — the tooltip opens only while the anchor is enabled and neither disabled nor readonly is true on it.
Cancels pending delays and opens, whatever the trigger — unless the anchor is disabled / readonly / not enabled.
"hover" · "click" · "focus" · "none".
trigger — hover: opens on pointer enter, closes on leave; while the pointer is on the tooltip itself a pending close is held (useful with closedelay). Delays — opendelay / closedelay in ms; an opposite event during a pending delay cancels it.
Cancels pending delays and closes, even when sticky.
The base popup's open: opens even on a non-interactive anchor; no delay.
setClose() when open, otherwise a trigger-style open request (delays and anchor checks apply).
Delays — opendelay / closedelay in ms; an opposite event during a pending delay cancels it.
The base popup's close: hides at once and cancels a pending opendelay (as Escape and an outside press do).
Never closes by itself; only setClose() / close().
"top" · "topLeft" · "topRight" · "bottom" · "bottomLeft" · "bottomRight" · "left" · "leftTop" · "leftBottom" · "right" · "rightTop" · "rightBottom".
The side after flipping: top · bottom · left · right, optionally -start / -end.
The text; n breaks lines.
Maximum text width in pixels, also limited by the window. Long help wraps automatically; 0 explicitly disables wrapping.
Drop the arrow (the tooltip then sits 4 px from the anchor instead of 10 px).
Animation — animation: "fade" (any name other than "none" fades) runs opacity transitions on open and close over animationMs; none under Theme.reducedMotion.
Animation — animation: "fade" (any name other than "none" fades) runs opacity transitions on open and close over animationMs; none under Theme.reducedMotion.
The tooltip is visible.
State — isOpen is the popup's visible.
Emitted just before the popup is shown.
Emitted after the popup finishes its enter transition.
Emitted just before the popup is hidden.
Emitted after the popup finishes its exit transition.

Keyboard

ItemBehavior / conditions
SyPopover for content with items, SyPopconfirm for a question with buttons, SyInlineMessage for field feedback; SyButton and SyIcon as typical anchors.