• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Hover Event
2
3A hover event is triggered when the cursor slides over a component or when a stylus hovers and moves over the screen.
4
5>  **NOTE**
6>
7>  - The APIs of this module are supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version.
8>  - Currently, only an external mouse device, stylus, or touchpad can be used to trigger a hover event.
9
10## onHover
11
12onHover(event: (isHover: boolean, event: HoverEvent) => void): T
13
14Triggered when the mouse pointer or stylus enters or leaves the component.
15
16**Atomic service API**: This API can be used in atomic services since API version 11.
17
18**System capability**: SystemCapability.ArkUI.ArkUI.Full
19
20**Parameters**
21
22| Name             | Type                               | Mandatory| Description                                                        |
23| ------------------- | ----------------------------------- | ---- | ------------------------------------------------------------ |
24| isHover             | boolean                             | Yes  | Whether the mouse pointer or stylus is hovering over the component. The value **true** means that the mouse pointer or stylus enters the component, and **false** means that the mouse pointer or stylus leaves the component.|
25| event<sup>11+</sup> | [HoverEvent](#hoverevent11) | Yes  | Event bubbling.                                      |
26
27**Return value**
28
29| Type| Description|
30| -------- | -------- |
31| T | Current component.|
32
33## HoverEvent<sup>11+</sup>
34
35Inherits from [BaseEvent](ts-gesture-customize-judge.md#baseevent).
36
37**Atomic service API**: This API can be used in atomic services since API version 11.
38
39**System capability**: SystemCapability.ArkUI.ArkUI.Full
40
41| Name             | Type      | Description     |
42| --------------- | ---------- | ------- |
43| stopPropagation | () => void | Stops the event from bubbling upwards or downwards.|
44
45## Example
46
47This example demonstrates how to set a hover event on a button. When the mouse or stylus hovers over the button, the **onHover** event is triggered to dynamically change the text content and background color of the button.
48
49```ts
50// xxx.ets
51@Entry
52@Component
53struct HoverEventExample {
54  @State hoverText: string = 'no hover';
55  @State color: Color = Color.Blue;
56
57  build() {
58    Column({ space: 20 }) {
59      Button(this.hoverText)
60        .width(180).height(80)
61        .backgroundColor(this.color)
62        .onHover((isHover: boolean, event: HoverEvent) => {
63          // 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.
64          // Use event.sourceTool to determine whether the device is a mouse device or stylus.
65          if (isHover) {
66            if (event.sourceTool == SourceTool.Pen) {
67              this.hoverText = 'pen hover';
68              this.color = Color.Pink;
69            } else if (event.sourceTool == SourceTool.MOUSE) {
70              this.hoverText = 'mouse hover';
71              this.color = Color.Red;
72            }
73          } else {
74            this.hoverText = 'no hover';
75            this.color = Color.Blue;
76          }
77        })
78    }.padding({ top: 30 }).width('100%')
79  }
80}
81```
82
83Diagrams:
84
85The figure below shows how the button looks when not hovered:
86
87 ![nohover](figures/no-hover.png)
88
89The figure below shows how the button looks like when a stylus hovers on it.
90
91 ![penhover](figures/pen-hover.png)
92