We use essential cookies for the website to function, as well as analytics cookies for analyzing and creating statistics of the website performance. To agree to the use of analytics cookies, click "Accept All". You can manage your preferences at any time by clicking "Cookie Settings" on the footer. More Information.

Cookie Settings
Only Essential Cookies
Accept All
MaterialsConsole

HarmonyOS

输入关键字搜索
HMS Core
AppGallery Connect
HUAWEI HiAI
CTRL+K
Advanced filters
API versionAll
DeviceAll
Atomic service APIsNot filter by this
ReferencesApplication FrameworkArkUIArkTS ComponentsUniversal EventsInteraction Response EventsHover Event

Hover Event

Phone12+PC/2in113+Tablet12+TV19+Wearable18+
Last updated: 2026-09-08 08:15
Content overview
Expand

A hover event is triggered when the cursor slides over a component or when a stylus hovers and moves over the screen.

NOTE
  • The initial APIs of this module are supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version.
  • Currently, only an external mouse device, stylus, or touchpad can be used to trigger a hover event.

onHover

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

onHover(event: (isHover: boolean, event: HoverEvent) => void): T

Triggered when the mouse pointer or stylus enters or leaves the component.

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

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Expand
Name Type Mandatory Description
event (isHover: boolean, event: HoverEvent) => void Yes

Callback for mouse or stylus hover status.

event: event bubbling control and coordinates of the hover position; available since API version 11.

isHover: whether the mouse pointer or stylus is hovering over the component. true: The mouse pointer or stylus has entered the component. false: The mouse pointer or stylus has left the component.

Return value

Expand
Type Description
T Current component.

onHoverMove15+

Phone15+PC/2in115+Tablet15+TV19+Wearable18+

onHoverMove(event: Callback<HoverEvent>): T

Triggered when a stylus hovers over the component.

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

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Expand
Name Type Mandatory Description
event Callback<HoverEvent> Yes Callback that controls event bubbling blocking and obtains the stylus hover position coordinates.

Return value

Expand
Type Description
T Current component.

HoverEvent10+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

Inherits from BaseEvent.

System capability: SystemCapability.ArkUI.ArkUI.Full

Expand
Name Type Read Only Optional Description
x15+ number No Yes

X coordinate of the cursor or stylus position in the component coordinate system based on the current component.

Unit: vp.

Atomic service API: This API can be used in atomic services since API version 15.
y15+ number No Yes

Y coordinate of the cursor or stylus position in the component coordinate system based on the current component.

Unit: vp.

Atomic service API: This API can be used in atomic services since API version 15.
windowX15+ number No Yes

X coordinate of the cursor or stylus position in the coordinate system of the current application window.

Unit: vp.

Atomic service API: This API can be used in atomic services since API version 15.
windowY15+ number No Yes

Y coordinate of the cursor or stylus position in the coordinate system of the current application window.

Unit: vp.

Atomic service API: This API can be used in atomic services since API version 15.
displayX15+ number No Yes

X coordinate of the cursor or stylus position in the coordinate system of the current screen window.

Unit: vp.

Atomic service API: This API can be used in atomic services since API version 15.
displayY15+ number No Yes

Y coordinate of the cursor or stylus position in the coordinate system of the current screen window.

Unit: vp.

Atomic service API: This API can be used in atomic services since API version 15.
stopPropagation () => void No No

Disables event bubbling propagation.

Atomic service API: This API can be used in atomic services since API version 11.
globalDisplayX20+ number No Yes

X coordinate of the cursor or stylus position in the global coordinate system.

Unit: vp.

Value range: [0, +∞).

Atomic service API: This API can be used in atomic services since API version 20.
globalDisplayY20+ number No Yes

Y coordinate of the cursor or stylus position in the global coordinate system.

Unit: vp.

Value range: [0, +∞).

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

Example

Example 1: Using onHover

This example demonstrates how to set the onHover event on a button. When the mouse or stylus hovers over the button, the event is triggered to dynamically change the text content and background color of the button.

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. @Entry
  3. @Component
  4. struct HoverEventExample {
  5.   @State hoverText: string = 'no hover';
  6.   @State color: Color = Color.Blue;
  7. 

  8.   build() {
  9.     Column({ space: 20 }) {
  10.       Button(this.hoverText, { type: ButtonType.Capsule })
  11.         .width(180).height(80)
  12.         .backgroundColor(this.color)
  13.         .onHover((isHover: boolean, event: HoverEvent) => {
  14.           // Use the onHover event to dynamically change the text content and background color of a button when the mouse pointer or stylus is hovered on it.
  15.           // Use event.sourceTool to determine whether the device is a mouse device or stylus.
  16.           if (isHover) {
  17.             if (event.sourceTool == SourceTool.Pen) {
  18.               this.hoverText = 'pen hover';
  19.               this.color = Color.Pink;
  20.             } else if (event.sourceTool == SourceTool.MOUSE) {
  21.               this.hoverText = 'mouse hover';
  22.               this.color = Color.Red;
  23.             }
  24.           } else {
  25.             this.hoverText = 'no hover';
  26.             this.color = Color.Blue;
  27.           }
  28.         })
  29.     }.padding({ top: 30 }).width('100%')
  30.   }
  31. }

Diagrams:

The figure below shows how the button looks in the non-hovered state.

The figure below shows how the button looks when a stylus hovers on it.

Example 2: Using onHoverMove

This example demonstrates how to configure the onHoverMove event on a button, available since API version 15. When a stylus hovers over the button, the UI displays the current stylus position.

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. @Entry
  3. @Component
  4. struct OnHoverMoveEventExample {
  5.   @State hoverMoveText: string = '';
  6. 

  7.   build() {
  8.     Column({ space: 20 }) {
  9.       Button('onHoverMove', { type: ButtonType.Capsule })
  10.         .width(180).height(80)
  11.         .onHoverMove((event: HoverEvent) => {
  12.           this.hoverMoveText = 'onHoverMove:\nXY = (' + event.x + ', ' + event.y + ')' +
  13.                                '\nwindowXY = (' + event.windowX + ', ' + event.windowY + ')' +
  14.                                '\ndisplayXY = (' + event.displayX + ', ' + event.displayY + ')';
  15.         })
  16. 

  17.       Text(this.hoverMoveText)
  18.     }.padding({ top: 30 }).width('100%')
  19.   }
  20. }

Diagrams:

When a stylus hovers over a button, the UI continuously updates to show the position of the stylus tip.

Focus Event
Component Keyboard Shortcut Event
English
©2026 HUAWEI Developers. All rights reserved.
Terms of Use
Statement About HUAWEI Developers and Privacy
Cookies
Cookie Settings
Open-Source Software Notice