目录

Tooltip Control

You can bind a floating tooltip to a component. The tooltip automatically appears when a pointer hovers over the component and disappears when the pointer moves away.

  • This API is supported since API version 19. Newly added content in later versions is marked with a superscript to indicate the version in which it was introduced.

  • The APIs of this module can be used only in the stage model.

  • Tips control depends on the device being able to trigger hover events. Tips control cannot be used on hardware devices that cannot trigger hover events.

bindTips

bindTips(message: TipsMessageType, options?: TipsOptions): T

Binds a tooltip to the component.

When the enabled universal attribute of the component bound with bindTips is set to false, the tooltip can still be displayed.

Atomic service API: This API can be used in atomic services since API version 19.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name Type Mandatory Description
message TipsMessageType Mandatory Content of the tooltip.
options TipsOptions No

Parameters of the tooltip.

Default value:

{

appearingTime: 700,

disappearingTime: 300,

appearingTimeWithContinuousOperation: 300,

disappearingTimeWithContinuousOperation: 0, enableArrow: true,

arrowPointPosition: ArrowPointPosition.CENTER,

arrowWidth: 16,arrowHeight: 8,

showAtAnchor: TipsAnchorType.TARGET

}

Return value

Type Description
T Current component.

TipsOptions

Defines the parameters of the tooltip.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name Type Read-Only Optional Description
appearingTime number No Yes

Delay before the tooltip appears. The maximum delay is 4000 ms. Values exceeding 4000 ms are capped at 4000 ms.

Default value: 700.

Unit: ms.

Atomic service API: This API can be used in atomic services since API version 19.
disappearingTime number No Yes

Delay before the tooltip disappears. The maximum delay is 4000 ms. Values exceeding 4000 ms are capped at 4000 ms.

Default value: 300.

Unit: ms.

Atomic service API: This API can be used in atomic services since API version 19.
appearingTimeWithContinuousOperation number No Yes

Delay before the tooltip appears when multiple tooltips are displayed consecutively. The maximum delay is 4000 ms. Values exceeding 4000 ms are capped at 4000 ms.

Default value: 300.

Unit: ms.

Atomic service API: This API can be used in atomic services since API version 19.
disappearingTimeWithContinuousOperation number No Yes

Delay before the tooltip disappears when multiple tooltips are displayed consecutively. The maximum delay is 4000 ms. Values exceeding 4000 ms are capped at 4000 ms.

Default value: 0.

Unit: ms.

Atomic service API: This API can be used in atomic services since API version 19.
enableArrow boolean No Yes

Whether to display the tooltip arrow.

Default value: true.

true: yes. false: no.

NOTE

If the available space on the screen is insufficient, the tooltip will cover part of the component and the arrow will not be displayed.

Atomic service API: This API can be used in atomic services since API version 19.
arrowPointPosition ArrowPointPosition No Yes

Position of the tooltip arrow relative to the parent component. The bubble arrow has three optional positions in the vertical and horizontal directions: Start, Center, and End. All positions are within the parent component area, and do not exceed the boundary of the parent component or cover the rounded corner area.

Default value: ArrowPointPosition.CENTER

Atomic service API: This API can be used in atomic services since API version 19.
arrowWidth Dimension No Yes

Width of the tooltip arrow. If the set width exceeds the length of the edge minus twice the tooltip's corner radius, the arrow is not drawn.

Default value: 16.

Unit: vp.

NOTE

Percentage values are not supported.

Atomic service API: This API can be used in atomic services since API version 19.
arrowHeight Dimension No Yes

Height of the tooltip arrow.

Default value: 8.

Unit: vp.

NOTE

Percentage values are not supported.

Atomic service API: This API can be used in atomic services since API version 19.
showAtAnchor20+ TipsAnchorType No Yes

Anchor type of the tooltip.

Default value: TipsAnchorType.TARGET.

NOTE

If the anchor type of the tooltip is TipsAnchorType.CURSOR, the tooltip does not display an arrow.

Atomic service API: This API can be used in atomic services since API version 20.
systemMaterial SystemUiMaterial No Yes

System material of the tooltip.

Default value: undefined, which clears the material effect set by this API.

NOTE

Different system materials have different effects on attributes. This API affects background color backgroundColor, border color borderColor, border width borderWidth, and shadow shadow. When a system material is set, the preceding APIs do not take effect.

Since: 26.0.0

Model restriction: This API can be used only in the stage model.

Atomic service API: This API can be used in atomic services since API version 26.0.0.

TipsMessageType

type TipsMessageType = ResourceStr | StyledString

Defines the type of the tooltip message.

Atomic service API: This API can be used in atomic services since API version 19.

System capability: SystemCapability.ArkUI.ArkUI.Full

Type Description
ResourceStr Type used to represent the types that can be used by input parameters of the string type.
StyledString Styled string.

Example

You can preview how this component looks on a real device, but not in DevEco Studio Previewer.

[h2]Example 1: Binding a Tooltip

This example shows how to bind a tooltip to a button using bindTips.

// xxx.ets
@Entry
@Component
struct TipsExample {
  build() {
    Flex({ direction: FlexDirection.Column }) {
      Button('Hover Tips')
        .bindTips("Tips", {
          appearingTime: 700,
          disappearingTime: 300,
          appearingTimeWithContinuousOperation: 300,
          disappearingTimeWithContinuousOperation: 0,
          enableArrow: true,
        })
        .position({ x: 100, y: 250 })
    }.width('100%').padding({ top: 5 })
  }
}

[h2]Example 2: Displaying and Hiding Multiple Tooltips

This example demonstrates how to configure multiple tooltips to appear and disappear in sequence using bindTips.

// xxx.ets

@Entry
@Component
struct TipsExample {
  build() {
    Flex({ direction: FlexDirection.Column }) {
      Button('Hover Tips')
        .bindTips("Tips", {
          appearingTime: 700,
          disappearingTime: 300,
          appearingTimeWithContinuousOperation: 300,
          disappearingTimeWithContinuousOperation: 0,
          enableArrow: true,
        })
        .position({ x: 100, y: 250 })

      Button('Hover Tips')
        .bindTips("Tips", {
          appearingTime: 700,
          disappearingTime: 300,
          appearingTimeWithContinuousOperation: 300,
          disappearingTimeWithContinuousOperation: 0,
          enableArrow: true,
        })
        .position({ x: 100, y: 350 })


    }.width('100%').padding({ top: 5 })
  }
}

[h2]Example 3: Setting the System Material Effect of a Tooltip

This example implements the system material effect of bindTips by setting the systemMaterial attribute in TipsOptions.

Since API version 26.0.0, the systemMaterial attribute is added to TipsOptions.

// xxx.ets
import { uiMaterial } from '@kit.ArkUI';

@Entry
@Component
struct TipsExample {
  build() {
    Flex({ direction: FlexDirection.Column }) {
      Button('Hover Tips')
        .bindTips("Tooltip Test", {
          // Control whether to set the system material.
          systemMaterial: new uiMaterial.ImmersiveMaterial({
            style: uiMaterial.ImmersiveStyle.THIN
          })
        })
        .position({ x: 100, y: 300 })
    }.width('100%').padding({ top: 5 })
    // Replace it with the actual resource file.
    .backgroundImage($r("app.media.img"))
    .backgroundImageSize({width: '100%', height: '100%'})
  }
}

When the system material is not set:

After the system material is set: