1# popup
2
3>  **NOTE**
4>
5>  This component is supported since API version 4. Updates will be marked with a superscript to indicate their earliest API version.
6
7 The **\<popup>** component is used to display a pop-up to offer instructions after a user clicks a bound component or calls the specific API.
8
9## Required Permissions
10
11None
12
13
14## Child Components
15
16This component supports only one child component.<sup>5+</sup>
17
18
19## Attributes
20
21In addition to the [universal attributes](js-components-common-attributes.md), the following attributes are supported.
22
23| Name| Type| Default Value| Mandatory| Description|
24| -------- | -------- | -------- | -------- | -------- |
25| target | string | - | Yes| ID of the target element. Dynamic switch is not supported.|
26| placement | string | bottom | No| Position of the pop-up relative to the target element. Available values are as follows:<br>- **left**: on the left of the target element.<br>- **right**: on the right of the target element.<br>- **top**: at the top of the target element;<br>- **bottom**: at the bottom of the target element.<br>- **topLeft**: in the upper left corner of the target element.<br>- **topRight**: in the upper right corner of the target element.<br>- **bottomLeft**: in the lower left corner of the target element.<br>- **bottomRight**: in the lower right corner of the target element.|
27| keepalive<sup>5+</sup> | boolean | false | No| Whether to retain this pop-up. **true**: The pop-up does not disappear when users tap other areas or switch the page. To hide the pop-up, call the **hide** method.<br>**false**: The pop-up disappears when users tap other areas or switch the page.|
28| clickable<sup>5+</sup> | boolean | true | No| Whether to display the pop-up when the user clicks the target element. If this attribute is set to **false**, the pop-up can be triggered only by an API call.|
29| arrowoffset<sup>5+</sup> | &lt;length&gt; | 0 | No| Offset of the pop-up arrow. By default, the arrow is centered. A positive value means that the arrow moves along the language direction (LTR or RTL), and a negative value means that the arrow moves along the opposite direction of the language direction.|
30
31>  **NOTE**
32>
33> The **focusable** attribute is not supported.
34
35
36## Styles
37
38In addition to the [universal styles](js-components-common-styles.md), the following styles are supported.
39
40| Name| Type| Default Value| Mandatory| Description|
41| -------- | -------- | -------- | -------- | -------- |
42| mask-color | &lt;color&gt; | - | No| Color configuration of the mask layer. By default, the mask layer is completely transparent.|
43
44>  **NOTE**
45>
46> Position-related styles are not supported.
47
48
49## Events
50
51In addition to the [universal events](js-components-common-events.md), the following events are supported.
52
53| Name| Parameter| Description|
54| -------- | -------- | -------- |
55| visibilitychange | { visibility: boolean } | Triggered when a pop-up appears or disappears.|
56
57
58## Methods
59
60The following methods are supported.
61
62| Name| Parameter| Description|
63| -------- | -------- | -------- |
64| show<sup>5+</sup> | - | Shows the pop-up.|
65| hide<sup>5+</sup> | - | Hides the pop-up.|
66
67>  **NOTE**
68> 1. Attributes and styles of a **\<popup>** component cannot be dynamically updated.
69>
70> 2. Margins of a pop-up take effect depending on its position relative to the target element. For example, if the pop-up is below the target element, only **margin-top** takes effect; if the pop-up displays on the upper left of the target element, only **margin-bottom** and **margin-right** take effect.
71>
72> 3. Styles set for the four borders of a pop-up must be the same. If they are different and the border radius is **0**, the first configured border style (in the sequence of left, top, right, and bottom) takes effect. Otherwise, the **border** attribute does not take effect.
73>
74> 4. The click event bound to the target element of a pop-up does not take effect.
75
76
77## Example
78
79```html
80<!-- xxx.hml -->
81<div class="container">
82  <text id="text">Click to show the pop-up</text>
83  <!-- popup supports single child of any type5+ -->
84  <popup id="popup" class="popup" target="text" placement="top" keepalive="true" clickable="true"
85    arrowoffset="100px" onvisibilitychange="visibilitychange" onclick="hidepopup">
86    <text class="text">Text content of the pop-up</text>
87  </popup>
88  <button class="button" onclick="showpopup">Click to show the pop-up</button>
89</div>
90```
91
92```css
93/* xxx.css */
94.container {
95  flex-direction: column;
96  align-items: center;
97  padding-top: 200px;
98}
99.popup {
100  mask-color: gray;
101}
102.text {
103  color: white;
104}
105.button {
106  width: 220px;
107  height: 70px;
108  margin-top: 50px;
109}
110```
111
112```js
113// xxx.js
114import promptAction from '@ohos.promptAction'
115export default {
116  visibilitychange(e) {
117    promptAction.showToast({
118      message: 'visibility change visibility: ' + e.visibility,
119        duration: 3000
120    });
121  },
122  showpopup() {
123    this.$element("popup").show();
124  },
125  hidepopup() {
126    this.$element("popup").hide();
127  }
128}
129```
130
131![en-us_image_0000001178886129](figures/en-us_image_0000001178886129.png)
132