1# Popup Control 2 3You can bind a popup to a component, specifying its content, interaction logic, and visibility. 4 5> **NOTE** 6> 7> - This attribute is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. 8> 9> - The visibility of the popup is returned through the **onStateChange** event callback. There is no strong mapping between the visibility and the creation or destruction of the component. 10 11## bindPopup 12 13bindPopup(show: boolean, popup: PopupOptions | CustomPopupOptions) 14 15Binds a popup to the component. 16 17**Atomic service API**: This API can be used in atomic services since API version 11. 18 19**System capability**: SystemCapability.ArkUI.ArkUI.Full 20 21**Parameters** 22 23| Name| Type | Mandatory| Description | 24| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 25| show | boolean | Yes | Whether to show the popup. The default value is **false**, indicating that the popup is hidden. The popup can be displayed only after the entire page is fully constructed. Therefore, to avoid incorrect display positions and shapes, do not set this parameter to **true** while the page is still being constructed. Since API version 13, this parameter supports two-way binding through the [!! syntax](../../../ui/state-management/arkts-new-binding.md#two-way-binding-between-built-in-component-parameters).| 26| popup | [PopupOptions](#popupoptions) \| [CustomPopupOptions](#custompopupoptions8)<sup>8+</sup> | Yes | Parameters of the popup. | 27 28## PopupOptions 29 30**System capability**: SystemCapability.ArkUI.ArkUI.Full 31 32| Name | Type | Mandatory| Description | 33| ------------------------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 34| message | string | Yes | Content of the popup message.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 35| placementOnTop<sup>(deprecated)</sup> | boolean | No | Whether to display the popup above the component. The default value is **false**.<br>**NOTE**<br>This API is deprecated since API version 10. You are advised to use **placement** instead.| 36| primaryButton | {<br>value: string,<br>action: () => void<br>} | No | Primary button.<br>**value**: text of the primary button in the popup.<br>**action**: callback for clicking the primary button.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 37| secondaryButton | {<br>value: string,<br>action: () => void<br>} | No | Secondary button.<br>**value**: text of the secondary button in the popup.<br>**action**: callback for clicking the secondary button.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 38| onStateChange | (event: { isVisible: boolean }) => void | No | Callback for the popup status change event. The parameter **isVisible** indicates whether the popup is visible.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 39| arrowOffset<sup>9+</sup> | [Length](ts-types.md#length) | No | Offset of the popup arrow relative to the popup. When the arrow is at the top or bottom of the popup: The value **0** indicates that the arrow is located on the leftmost, and any other value indicates the distance from the arrow to the leftmost; the arrow is centered by default. When the arrow is on the left or right side of the popup: The value indicates the distance from the arrow to the top; the arrow is centered by default. When the popup is displayed on either edge of the screen, it will automatically deviate leftward or rightward to stay within the safe area. When the value is 0, the arrow always points to the bound component.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 40| showInSubWindow<sup>9+</sup> | boolean | No | Whether to show the popup in the subwindow. The value **true** means to show the popup in the subwindow, and **false** means to show the popup in the main window.<br>Default value: **false**<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 41| mask<sup>10+</sup> | boolean \| { color : [ResourceColor](ts-types.md#resourcecolor) }| No | Whether to apply a mask to the popup. The value **true** means to apply a transparent mask to the popup, **false** means not to apply a mask to the popup, and a color value means to apply a mask in the corresponding color to the popup.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 42| messageOptions<sup>10+</sup> | [PopupMessageOptions](#popupmessageoptions10) | No | Parameters of the popup message.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 43| targetSpace<sup>10+</sup> | [Length](ts-types.md#length) | No | Space between the popup and the target.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 44| placement<sup>10+</sup> | [Placement](ts-appendix-enums.md#placement8) | No | Position of the popup relative to the target. The default value is **Placement.Bottom**.<br>If both **placementOnTop** and **placement** are set, the latter prevails.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 45| offset<sup>10+</sup> | [Position](ts-types.md#position) | No | Offset of the popup relative to the display position specified by **placement**.<br>**NOTE**<br>This parameter cannot be set in percentage.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 46| enableArrow<sup>10+</sup> | boolean | No | Whether to display the arrow.<br>Default value: **true**<br>**NOTE**<br>If the available space on the screen is insufficient, the popup will cover part of the component and the arrow will not be displayed.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 47| popupColor<sup>11+</sup> | [Color](ts-appendix-enums.md#color) \| string \| number \| [Resource](ts-types.md#resource) | No | Color of the popup. To remove the background blur, set **backgroundBlurStyle** to **BlurStyle.NONE**.<br>Default value: [TRANSPARENT](ts-appendix-enums.md#color) plus[COMPONENT_ULTRA_THICK](ts-universal-attributes-background.md#blurstyle9)<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 48| autoCancel<sup>11+</sup> | boolean | No | Whether to automatically dismiss the popup when an operation is performed on the page.<br>Default value: **true**<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 49| width<sup>11+</sup> | [Dimension](ts-types.md#dimension10) | No | Width of the popup.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 50| arrowPointPosition<sup>11+</sup> | [ArrowPointPosition](ts-appendix-enums.md#arrowpointposition11) | No | Position of the popup arrow relative to its parent component. Available positions are **Start**, **Center**, and **End**, in both vertical and horizontal directions. All these positions are within the parent component area.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 51| arrowWidth<sup>11+</sup> | [Dimension](ts-types.md#dimension10) | No | Arrow thickness. If the arrow thickness exceeds the length of the edge minus twice the size of the popup rounded corner, the arrow is not drawn.<br>Default value: **16**<br>Unit: vp<br>**NOTE**<br>This parameter cannot be set in percentage.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 52| arrowHeight<sup>11+</sup> | [Dimension](ts-types.md#dimension10) | No | Arrow height.<br>Default value: **8**<br>Unit: vp<br>**NOTE**<br>This parameter cannot be set in percentage.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 53| radius<sup>11+</sup> | [Dimension](ts-types.md#dimension10) | No | Rounded corner radius of the popup.<br>Default value: **20**<br>Unit: vp<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 54| shadow<sup>11+</sup> | [ShadowOptions](ts-universal-attributes-image-effect.md#shadowoptions) \| [ShadowStyle](ts-universal-attributes-image-effect.md#shadowstyle10) | No | Popup shadow.<br>Default value: **ShadowStyle.OUTER_DEFAULT_MD**<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 55| backgroundBlurStyle<sup>11+</sup> | [BlurStyle](ts-universal-attributes-background.md#blurstyle9) | No| Background blur style of the popup.<br>Default value: **BlurStyle.COMPONENT_ULTRA_THICK**<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 56| transition<sup>12+</sup> | [TransitionEffect](ts-transition-animation-component.md#transitioneffect10) | No| Transition effect for the entrance and exit of the popup.<br>**NOTE**<br>1. If this parameter is not set, the default effect is used.<br>2. Touching the Back button during the entrance animation pauses the entrance animation and starts the exit animation. The final effect is one obtained after the curves of the entrance and exit animations are combined.<br>3. Touching the Back button during the exit animation does not affect the animation playback. The Back button does not respond.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 57| onWillDismiss<sup>12+</sup> | boolean \| Callback\<([DismissPopupAction](#dismisspopupaction12))> | No | Whether to perform dismissal event interception and interception callback. The default value is **true**.<br>1. If this parameter is set to **false**, the system does not respond to the dismissal event initiated by touching the Back button, swiping left or right on the screen, or pressing the Esc key; and the system dismisses the popup only when **show** is set to **false**. If this parameter is set to **true**, the system responds to the dismissal event as expected.<br>2. If this parameter is set to a function, the dismissal event is intercepted and the callback function is executed.<br>**NOTE**<br>No more **onWillDismiss** callback is allowed in an **onWillDismiss** callback.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 58| followTransformOfTarget<sup>13+</sup> | boolean | No | Whether the popup adjusts its position to follow transformations (like rotation or scaling) applied to its host component or the host component's parent container.<br>Default value: **false**<br>**Atomic service API**: This API can be used in atomic services since API version 13.| 59| keyboardAvoidMode<sup>15+</sup> | [KeyboardAvoidMode](ts-types.md#keyboardavoidmode12) | No | Whether to avoid the soft keyboard. By default, the popup does not avoid the soft keyboard. When configured to avoid the soft keyboard, if the popup display space is insufficient, the display mode of the popup changes from being centered over the parent component to being translated and covering the parent component.. In addition, if the popup arrow does not point to the host, the arrow will not be displayed.<br>Default value: **KeyboardAvoidMode.NONE**<br>**Atomic service API**: This API can be used in atomic services since API version 15.| 60| enableHoverMode<sup>18+</sup>| boolean | No | Whether to enable the hover mode. If the click position of the popup component is in the crease area in the hover state, the popup component does not respond to the hover state. Default value: **false**, indicating that the popup does not respond in hover mode<br>**NOTE**<br>The menu responds in hover mode when **enableHoverMode** is set to **true** and does not when **enableHoverMode** is set to **false** or an invalid value or is not set at all.<br>**Atomic service API**: This API can be used in atomic services since API version 18.| 61 62## PopupMessageOptions<sup>10+</sup> 63 64**Atomic service API**: This API can be used in atomic services since API version 11. 65 66**System capability**: SystemCapability.ArkUI.ArkUI.Full 67 68| Name | Type | Mandatory|Description | 69| --------- | ------------------------------------------ | ---- | ------------------------------------------------------------ | 70| textColor | [ResourceColor](ts-types.md#resourcecolor) | No | Text color of the popup message. | 71| font | [Font](ts-types.md#font) | No | Font settings of the popup message.<br>**NOTE**<br>Setting **family** is not supported.| 72 73## DismissPopupAction<sup>12+</sup> 74 75**Atomic service API**: This API can be used in atomic services since API version 12. 76 77**System capability**: SystemCapability.ArkUI.ArkUI.Full 78 79| Name | Type | Mandatory| Description | 80| ------- | ----------------------------------------- | ---- | --------------------------------------------------------------- | 81| dismiss | function | Yes | Callback for dismissing the popup. This API is called only when the popup needs to be exited.| 82| reason | [DismissReason](#dismissreason12)| Yes | Reason why the popup cannot be dismissed. | 83 84## DismissReason<sup>12+</sup> 85 86**System capability**: SystemCapability.ArkUI.ArkUI.Full 87 88| Name | Description | 89| ------------- | ------------------ | 90| PRESS_BACK | Touching the Back button. | 91| TOUCH_OUTSIDE | Touching anywhere outside of the popup.| 92 93## CustomPopupOptions<sup>8+</sup> 94 95**System capability**: SystemCapability.ArkUI.ArkUI.Full 96 97| Name | Type | Mandatory | Description | 98| ---------------------------- | ---------------------------------------- | ---- | ---------------------------------------- | 99| builder | [CustomBuilder](ts-types.md#custombuilder8) | Yes | Popup builder.<br>**NOTE**<br>The **popup** attribute is a universal attribute. A custom popup does not support display of another popup. The **position** attribute cannot be used for the first-layer container in the builder. If the **position** attribute is used, the popup will not be displayed. If a custom component is used in the builder, the **aboutToAppear** and **aboutToDisappear** lifecycle callbacks of the custom component are irrelevant to the visibility of the popup. As such, the lifecycle of the custom component cannot be used to determine whether the popup is displayed or not.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 100| placement | [Placement](ts-appendix-enums.md#placement8) | No | Preferred position of the popup. If the set position is insufficient for holding the popup, it will be automatically adjusted.<br>Default value: **Placement.Bottom**<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 101| popupColor | number \| [Color](ts-types.md#color) \| string \| [Resource](ts-types.md#resource) | No | Color of the popup. To remove the background blur, set **backgroundBlurStyle** to **BlurStyle.NONE**.<br>The default value varies by API version.<br>API version 10: **'#4d4d4d'**<br>API version 11 and later: [TRANSPARENT](ts-appendix-enums.md#color) plus [COMPONENT_ULTRA_THICK](ts-universal-attributes-background.md#blurstyle9)<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 102| enableArrow | boolean | No | Whether to display an arrow.<br>Since API version 9, if the position set for the popup is not large enough, the arrow will not be displayed. For example, if **placement** is set to **Left**, but the popup height (80 vp) is less than the sum of the arrow width (32 vp) and diameter of popup rounded corner (48 vp), the arrow will not be displayed.<br>Default value: **true**<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 103| autoCancel | boolean | No | Whether to automatically dismiss the popup when an operation is performed on the page.<br>Default value: **true**<br>**NOTE**<br>To enable the popup to disappear upon a click on it, place a layout component in the builder, place the **\<Popup>** component in the layout component, and modify the value of the **bindPopup** variable (show: boolean) in the **onClick** event of the layout component.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 104| onStateChange | (event: { isVisible: boolean }) => void | No | Callback for the popup status change event. The parameter **isVisible** indicates whether the popup is visible.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 105| arrowOffset<sup>9+</sup> | [Length](ts-types.md#length) | No | Offset of the popup arrow relative to the popup. When the arrow is at the top or bottom of the popup: The value **0** indicates that the arrow is located on the leftmost, and any other value indicates the distance from the arrow to the leftmost; the arrow is centered by default. When the arrow is on the left or right side of the popup: The value indicates the distance from the arrow to the top; the arrow is centered by default. When the popup is displayed on either edge of the screen, it will automatically deviate leftward or rightward to stay within the safe area. When the value is 0, the arrow always points to the bound component.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 106| showInSubWindow<sup>9+</sup> | boolean | No | Whether to show the popup in the subwindow. The value **true** means to show the popup in the subwindow, and **false** means to show the popup in the main window.<br>Default value: **false**<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 107| maskColor<sup>(deprecated)</sup> | [Resource](ts-types.md#resource) \| string \| number \| [Color](ts-types.md#color) | No | Color of the popup mask.<br>**NOTE**<br>This parameter is deprecated since API version 10. You are advised to use **mask** instead.| 108| mask<sup>10+</sup> | boolean \| { color : [ResourceColor](ts-types.md#resourcecolor) }| No | Whether to apply a mask to the popup. The value **true** means to apply a transparent mask to the popup, **false** means not to apply a mask to the popup, and a color value means to apply a mask in the corresponding color to the popup.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 109| targetSpace<sup>10+</sup> | [Length](ts-types.md#length) | No | Space between the popup and the target.<br>**Atomic service API**: This API can be used in atomic services since API version 11. | 110| offset<sup>10+</sup> | [Position](ts-types.md#position) | No | Offset of the popup relative to the display position specified by **placement**.<br>**NOTE**<br>This parameter cannot be set in percentage.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 111| width<sup>11+</sup> | [Dimension](ts-types.md#dimension10) | No| Width of the popup.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 112| arrowPointPosition<sup>11+</sup> | [ArrowPointPosition](ts-appendix-enums.md#arrowpointposition11) | No| Position of the popup arrow relative to its parent component. Available positions are **Start**, **Center**, and **End**, in both vertical and horizontal directions. All these positions are within the parent component area.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 113| arrowWidth<sup>11+</sup> | [Dimension](ts-types.md#dimension10) | No | Arrow thickness. If the arrow thickness exceeds the length of the edge minus twice the size of the popup rounded corner, the arrow is not drawn.<br>Default value: **16**<br>Unit: vp<br>**NOTE**<br>This parameter cannot be set in percentage.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 114| arrowHeight<sup>11+</sup> | [Dimension](ts-types.md#dimension10) | No | Arrow height.<br>Default value: **8**<br>Unit: vp<br>**NOTE**<br>This parameter cannot be set in percentage.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 115| radius<sup>11+</sup> | [Dimension](ts-types.md#dimension10) | No | Rounded corner radius of the popup.<br>Default value: **20**<br>Unit: vp<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 116| shadow<sup>11+</sup> | [ShadowOptions](ts-universal-attributes-image-effect.md#shadowoptions) \| [ShadowStyle](ts-universal-attributes-image-effect.md#shadowstyle10) | No | Popup shadow.<br>Default value: **ShadowStyle.OUTER_DEFAULT_MD**<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 117| backgroundBlurStyle<sup>11+</sup> | [BlurStyle](ts-universal-attributes-background.md#blurstyle9) | No| Background blur style of the popup.<br>Default value: **BlurStyle.COMPONENT_ULTRA_THICK**<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 118| focusable<sup>11+</sup> | boolean | No| Whether the popup obtains focus when displayed.<br>Default value: **false**<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 119| transition<sup>12+</sup> | [TransitionEffect](ts-transition-animation-component.md#transitioneffect10) | No| Transition effect for the entrance and exit of the popup.<br>**NOTE**<br>1. If this parameter is not set, the default effect is used.<br>2. Touching the Back button during the entrance animation pauses the entrance animation and starts the exit animation. The final effect is one obtained after the curves of the entrance and exit animations are combined.<br>3. Touching the Back button during the exit animation does not affect the animation playback. The Back button does not respond.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 120| onWillDismiss<sup>12+</sup> | boolean \| Callback\<([DismissPopupAction](#dismisspopupaction12))> | No | Whether to perform dismissal event interception and interception callback. The default value is **true**.<br>1. If this parameter is set to **false**, the system does not respond to the dismissal event initiated by touching the Back button, swiping left or right on the screen, or pressing the Esc key; and the system dismisses the popup only when **show** is set to **false**. If this parameter is set to **true**, the system responds to the dismissal event as expected.<br>2. If this parameter is set to a function, the dismissal event is intercepted and the callback function is executed.<br>**NOTE**<br>No more **onWillDismiss** callback is allowed in an **onWillDismiss** callback.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 121| followTransformOfTarget<sup>13+</sup> | boolean | No | Whether the popup adjusts its position to follow transformations (like rotation or scaling) applied to its host component or the host component's parent container.<br>Default value: **false**<br>**Atomic service API**: This API can be used in atomic services since API version 13.| 122| keyboardAvoidMode<sup>15+</sup> | [KeyboardAvoidMode](ts-types.md#keyboardavoidmode12) | No | Whether to avoid the soft keyboard. By default, the popup does not avoid the soft keyboard. When configured to avoid the soft keyboard, if the popup display space is insufficient, the display mode of the popup changes from being centered over the parent component to being translated and covering the parent component.. In addition, if the popup arrow does not point to the host, the arrow will not be displayed.<br>Default value: **KeyboardAvoidMode.NONE**<br>**Atomic service API**: This API can be used in atomic services since API version 15.| 123|enableHoverMode<sup>18+</sup> | boolean | No | Whether to enable the hover mode. If the click position of the popup component is in the crease area in the hover state, the popup component does not respond to the hover state. Default value: **false**, indicating that the popup does not respond in hover mode<br>**NOTE**<br>The popup responds in hover mode when **enableHoverMode** is set to **true** and does not when **enableHoverMode** is set to **false** or an invalid value or is not set at all.<br>**Atomic service API**: This API can be used in atomic services since API version 18.| 124 125## PopupCommonOptions<sup>18+</sup> 126 127Parameters of the popup. Use the [getPromptAction()](../js-apis-arkui-UIContext.md#getpromptaction) API in [UIContext](../js-apis-arkui-UIContext.md#uicontext) to obtain a [PromptAction](../js-apis-arkui-UIContext.md#promptaction) object. Then, use this object to call [openPopup](../js-apis-arkui-UIContext.md#openpopup18) and [updatePopup](../js-apis-arkui-UIContext.md#updatepopup18), where the properties of the **options** parameter are defined as follows. 128 129**Atomic service API**: This API can be used in atomic services since API version 18. 130 131**System capability**: SystemCapability.ArkUI.ArkUI.Full 132 133| Name | Type | Mandatory | Description | 134| ---------------------------- | ---------------------------------------- | ---- | ---------------------------------------- | 135| placement | [Placement](ts-appendix-enums.md#placement8) | No | Preferred position of the popup. If the set position is insufficient for holding the popup, it will be automatically adjusted.<br>Default value: **Placement.Bottom**| 136| popupColor | [ResourceColor](ts-types.md#resourcecolor) | No | Color of the popup. To remove the background blur, set **backgroundBlurStyle** to **BlurStyle.NONE**. Default value: [TRANSPARENT](ts-appendix-enums.md#color) plus[COMPONENT_ULTRA_THICK](ts-universal-attributes-background.md#blurstyle9)| 137| enableArrow | boolean | No | Whether to display an arrow.<br>If the position set for the popup is not large enough, the arrow will not be displayed. For example, if **placement** is set to **Left**, but the popup height (80 vp) is less than the sum of the arrow width (32 vp) and diameter of popup rounded corner (48 vp), the arrow will not be displayed.<br>Default value: **true**| 138| autoCancel | boolean | No | Whether to automatically dismiss the popup when an operation is performed on the page.<br>Default value: **true**| 139| onStateChange | [PopupStateChangeCallback](#popupstatechangecallback18) | No | Callback invoked when the popup state changes.<br>**NOTE**<br>The settings cannot be updated through [updatePopup](../js-apis-arkui-UIContext.md#updatepopup18).| 140| arrowOffset | [Length](ts-types.md#length) | No | Offset of the popup arrow relative to the popup. When the arrow is at the top or bottom of the popup: The value **0** indicates that the arrow is located on the leftmost, and any other value indicates the distance from the arrow to the leftmost; the arrow is centered by default. When the arrow is on the left or right side of the popup: The value indicates the distance from the arrow to the top; the arrow is centered by default. When the popup is displayed on either edge of the screen, it will automatically deviate leftward or rightward to stay within the safe area. When the value is 0, the arrow always points to the bound component.| 141| showInSubWindow | boolean | No | Whether to show the popup in the subwindow. The value **true** means to show the popup in the subwindow, and **false** means to show the popup in the main window.<br>Default value: **false**<br>**NOTE**<br>The settings cannot be updated through [updatePopup](../js-apis-arkui-UIContext.md#updatepopup18).| 142| mask | boolean \| [PopupMaskType](#popupmasktype18) | No | Whether to apply a mask to the popup. The value **true** means to apply a transparent mask to the popup, **false** means not to apply a mask to the popup, and a value of the PopupMaskType type means to apply a mask in the specified color to the popup.| 143| targetSpace | [Length](ts-types.md#length) | No | Space between the popup and the target.| 144| offset | [Position](ts-types.md#position) | No | Offset of the popup relative to the display position specified by **placement**.<br>**NOTE**<br>This parameter cannot be set in percentage.| 145| width | [Dimension](ts-types.md#dimension10) | No| Width of the popup.| 146| arrowPointPosition | [ArrowPointPosition](ts-appendix-enums.md#arrowpointposition11) | No| Position of the popup arrow relative to its parent component. Available positions are **Start**, **Center**, and **End**, in both vertical and horizontal directions. All these positions are within the parent component area.| 147| arrowWidth | [Dimension](ts-types.md#dimension10) | No | Arrow thickness. If the arrow thickness exceeds the length of the edge minus twice the size of the popup rounded corner, the arrow is not drawn.<br>Default value: **16**<br>Unit: vp<br>**NOTE**<br>This parameter cannot be set in percentage.| 148| arrowHeight | [Dimension](ts-types.md#dimension10) | No | Arrow height.<br>Default value: **8**<br>Unit: vp<br>**NOTE**<br>This parameter cannot be set in percentage.| 149| radius | [Dimension](ts-types.md#dimension10) | No | Rounded corner radius of the popup.<br>Default value: **20**<br>Unit: vp| 150| shadow | [ShadowOptions](ts-universal-attributes-image-effect.md#shadowoptions) \| [ShadowStyle](ts-universal-attributes-image-effect.md#shadowstyle10) | No | Popup shadow.<br>Default value: **ShadowStyle.OUTER_DEFAULT_MD**| 151| backgroundBlurStyle | [BlurStyle](ts-universal-attributes-background.md#blurstyle9) | No| Background blur style of the popup.<br>Default value: **BlurStyle.COMPONENT_ULTRA_THICK**| 152| focusable | boolean | No| Whether the popup obtains focus when displayed.<br>Default value: **false**<br>**NOTE**<br>The settings cannot be updated through [updatePopup](../js-apis-arkui-UIContext.md#updatepopup18).| 153| transition | [TransitionEffect](ts-transition-animation-component.md#transitioneffect10) | No| Transition effect for the entrance and exit of the popup.<br>**NOTE**<br>1. If this parameter is not set, the default effect is used.<br>2. Touching the Back button during the entrance animation pauses the entrance animation and starts the exit animation. The final effect is one obtained after the curves of the entrance and exit animations are combined.<br>3. Touching the Back button during the exit animation does not affect the animation playback. The Back button does not respond.<br>4. The settings cannot be updated through [updatePopup](../js-apis-arkui-UIContext.md#updatepopup18).| 154| onWillDismiss | boolean\|Callback<[DismissPopupAction](#dismisspopupaction12)> | No | Whether to perform dismissal event interception and interception callback. The default value is **true**.<br>1. If this parameter is set to **false**, the system does not respond to the dismissal event initiated by touching the Back button, swiping left or right on the screen, or pressing the Esc key; and the system dismisses the popup only when **show** is set to **false**. If this parameter is set to **true**, the system responds to the dismissal event as expected.<br>2. If this parameter is set to a function, the dismissal event is intercepted and the callback function is executed.<br>**NOTE**<br>1. Nesting **onWillDismiss** callbacks is not allowed.<br>2. The settings cannot be updated through [updatePopup](../js-apis-arkui-UIContext.md#updatepopup18).| 155| followTransformOfTarget | boolean | No | Whether the popup adjusts its position to follow transformations (like rotation or scaling) applied to its host component or the host component's parent container.<br>Default value: **false**| 156|enableHoverMode | boolean | No | Whether to enable the hover mode. If the click position of the popup component is in the crease area in the hover state, the popup component does not respond to the hover state. Default value: **false**, indicating that the popup does not respond in hover mode<br>**NOTE**<br>The popup responds in hover mode when **enableHoverMode** is set to **true** and does not when **enableHoverMode** is set to **false** or an invalid value or is not set at all.| 157 158## PopupStateChangeParam<sup>18+</sup> 159 160Describes the display state of a popup. 161 162**Atomic service API**: This API can be used in atomic services since API version 18. 163 164**System capability**: SystemCapability.ArkUI.ArkUI.Full 165 166| Name | Type | Mandatory| Description | 167| --------- | ------------------------------------------ | ---- | ------------------------------------------------------------ | 168| isVisible | boolean | Yes | Display state of the popup. | 169 170## PopupStateChangeCallback<sup>18+</sup> 171 172Represents the callback invoked when the popup state changes. 173 174type PopupStateChangeCallback = (event: PopupStateChangeParam) => void; 175 176**Atomic service API**: This API can be used in atomic services since API version 18. 177 178**System capability**: SystemCapability.ArkUI.ArkUI.Full 179 180**Parameters** 181 182| Name | Type | Mandatory| Description | 183| --------- | ------------------------------------------ | ---- | ------------------------------------------------------------ | 184| event | [PopupStateChangeParam](#popupstatechangeparam18) | Yes | Display state of the popup. | 185 186## PopupMaskType<sup>18+</sup> 187 188Describes the color of the mask. 189 190**Atomic service API**: This API can be used in atomic services since API version 18. 191 192**System capability**: SystemCapability.ArkUI.ArkUI.Full 193 194| Name | Type | Mandatory| Description | 195| --------- | ------------------------------------------ | ---- | ------------------------------------------------------------ | 196| color | [ResourceColor](ts-types.md#resourcecolor) | Yes | Color of the mask. | 197 198## Example 199 200### Example 1: Displaying Different Types of Popups 201 202This example showcases how to use the **bindPopup** API to configure and display popups of PopupOptions and CustomPopupOptions types. 203 204```ts 205// xxx.ets 206@Entry 207@Component 208struct PopupExample { 209 @State handlePopup: boolean = false; 210 @State customPopup: boolean = false; 211 212 // Popup builder 213 @Builder popupBuilder() { 214 Row({ space: 2 }) { 215 Image($r("app.media.icon")).width(24).height(24).margin({ left: -5 }) 216 Text('Custom Popup').fontSize(10) 217 }.width(100).height(50).padding(5) 218 } 219 220 build() { 221 Flex({ direction: FlexDirection.Column }) { 222 // PopupOptions for setting the popup 223 Button('PopupOptions') 224 .onClick(() => { 225 this.handlePopup = !this.handlePopup; 226 }) 227 .bindPopup(this.handlePopup, { 228 message: 'This is a popup with PopupOptions', 229 placementOnTop: true, 230 showInSubWindow:false, 231 // Set the popup to avoid the soft keyboard. 232 keyboardAvoidMode: KeyboardAvoidMode.DEFAULT, 233 primaryButton: { 234 value: 'confirm', 235 action: () => { 236 this.handlePopup = !this.handlePopup; 237 console.info('confirm Button click'); 238 } 239 }, 240 // Secondary button 241 secondaryButton: { 242 value: 'cancel', 243 action: () => { 244 this.handlePopup = !this.handlePopup; 245 console.info('cancel Button click'); 246 } 247 }, 248 onStateChange: (e) => { 249 console.info(JSON.stringify(e.isVisible)) 250 if (!e.isVisible) { 251 this.handlePopup = false; 252 } 253 } 254 }) 255 .position({ x: 100, y: 150 }) 256 257 258 // CustomPopupOptions for setting the popup 259 Button('CustomPopupOptions') 260 .onClick(() => { 261 this.customPopup = !this.customPopup; 262 }) 263 .bindPopup(this.customPopup, { 264 builder: this.popupBuilder, 265 placement: Placement.Top, 266 mask: {color:'#33000000'}, 267 popupColor: Color.Yellow, 268 enableArrow: true, 269 // Set the popup to avoid the soft keyboard. 270 keyboardAvoidMode: KeyboardAvoidMode.DEFAULT, 271 showInSubWindow: false, 272 onStateChange: (e) => { 273 if (!e.isVisible) { 274 this.customPopup = false; 275 } 276 } 277 }) 278 .position({ x: 80, y: 300 }) 279 }.width('100%').padding({ top: 5 }) 280 } 281} 282``` 283 284 285 286### Example 2: Setting the Popup Text Style 287 288This example shows how to use the **bindPopup** API to display a popup with custom **messageOptions** settings. 289 290```ts 291// xxx.ets 292 293@Entry 294@Component 295struct PopupExample { 296 @State handlePopup: boolean = false; 297 298 build() { 299 Column({ space: 100 }) { 300 Button('PopupOptions').margin(100) 301 .onClick(() => { 302 this.handlePopup = !this.handlePopup; 303 }) 304 .bindPopup(this.handlePopup, { 305 // Popup of the PopupOptions type 306 message: 'This is a popup with PopupOptions', 307 messageOptions: { 308 // Text style of the popup 309 textColor: Color.Red, 310 font: { 311 size: '14vp', 312 style: FontStyle.Italic, 313 weight: FontWeight.Bolder 314 } 315 }, 316 placement: Placement.Bottom, 317 enableArrow: false, // Set the arrow not to display. 318 targetSpace: '15vp', 319 onStateChange: (e) => { 320 console.info(JSON.stringify(e.isVisible)); 321 if (!e.isVisible) { 322 this.handlePopup = false; 323 } 324 } 325 }) 326 }.margin(20) 327 } 328} 329``` 330 331 332 333### Example 3: Setting the Popup Style 334 335This example demonstrates how to use the **bindPopup** API with properties like **arrowHeight**, **arrowWidth**, **radius**, **shadow**, and **popupColor** to set the styles for both the popup's arrow and the popup itself. 336 337```ts 338// xxx.ets 339 340@Entry 341@Component 342struct PopupExample { 343 @State customPopup: boolean = false; 344 @State handlePopup: boolean = false; 345 346 build() { 347 Column({ space: 100 }) { 348 Button("popup") 349 .margin({ top: 50 }) 350 .onClick(() => { 351 this.customPopup = !this.customPopup; 352 }) 353 .bindPopup(this.customPopup, { 354 message: "this is a popup", 355 arrowHeight: 20, // Set the height for the popup arrow. 356 arrowWidth: 20, // Set the width for the popup arrow. 357 radius: 20, // Set the corner radius of the popup. 358 shadow: ShadowStyle.OUTER_DEFAULT_XS, // Set the shadow for the popup. 359 }) 360 361 Button('PopupOptions') 362 .onClick(() => { 363 this.handlePopup = !this.handlePopup; 364 }) 365 .bindPopup(this.handlePopup, { 366 width: 300, 367 message: 'This is a popup with PopupOptions', 368 arrowPointPosition: ArrowPointPosition.START, // Set the position for the popup arrow. 369 backgroundBlurStyle: BlurStyle.NONE, // Disable the background blur for the popup. 370 popupColor: Color.Red, // Set the background color for the popup. 371 autoCancel: true, 372 }) 373 } 374 .width('100%') 375 } 376} 377``` 378 379 380 381### Example 4: Setting the Popup Animation 382 383In this example, the **bindPopup** API is used with the **transition** property to implement animations for displaying and dismissing popups. 384 385```ts 386// xxx.ets 387@Entry 388@Component 389struct PopupExample { 390 @State handlePopup: boolean = false; 391 @State customPopup: boolean = false; 392 393 // Popup builder 394 @Builder popupBuilder() { 395 Row() { 396 Text('Custom Popup with transitionEffect').fontSize(10) 397 }.height(50).padding(5) 398 } 399 400 build() { 401 Flex({ direction: FlexDirection.Column }) { 402 // PopupOptions for setting the popup 403 Button('PopupOptions') 404 .onClick(() => { 405 this.handlePopup = !this.handlePopup; 406 }) 407 .bindPopup(this.handlePopup, { 408 message: 'This is a popup with transitionEffect', 409 placementOnTop: true, 410 showInSubWindow: false, 411 onStateChange: (e) => { 412 console.info(JSON.stringify(e.isVisible)) 413 if (!e.isVisible) { 414 this.handlePopup = false; 415 } 416 }, 417 // Set the popup animation to a combination of opacity and translation effects, with no exit animation. 418 transition:TransitionEffect.asymmetric( 419 TransitionEffect.OPACITY.animation({ duration: 1000, curve: Curve.Ease }).combine( 420 TransitionEffect.translate({ x: 50, y: 50 })), 421 TransitionEffect.IDENTITY) 422 }) 423 .position({ x: 100, y: 150 }) 424 425 // CustomPopupOptions for setting the popup 426 Button('CustomPopupOptions') 427 .onClick(() => { 428 this.customPopup = !this.customPopup; 429 }) 430 .bindPopup(this.customPopup, { 431 builder: this.popupBuilder, 432 placement: Placement.Top, 433 showInSubWindow: false, 434 onStateChange: (e) => { 435 if (!e.isVisible) { 436 this.customPopup = false; 437 } 438 }, 439 // Set the popup entrance and exit animations to be a scaling effect. 440 transition:TransitionEffect.scale({ x: 1, y: 0 }).animation({ duration: 500, curve: Curve.Ease }) 441 }) 442 .position({ x: 80, y: 300 }) 443 }.width('100%').padding({ top: 5 }) 444 } 445} 446``` 447 448 449 450### Example 5: Adding an Event to a Popup 451 452This example uses the **bindPopup** API with the **onWillDismiss** property to intercept the dismissal event when a popup is about to be dismissed and execute a callback function. 453 454```ts 455// xxx.ets 456 457@Entry 458@Component 459struct PopupExample { 460 @State handlePopup: boolean = false; 461 build() { 462 Column() { 463 Button('PopupOptions') 464 .onClick(() => { 465 this.handlePopup = true; 466 }) 467 .bindPopup(this.handlePopup, { 468 message: 'This is a popup with PopupOptions', 469 messageOptions: { 470 textColor: Color.Red, 471 font: { 472 size: '14vp', 473 style: FontStyle.Italic, 474 weight: FontWeight.Bolder 475 } 476 }, 477 placement: Placement.Bottom, 478 enableArrow: false, 479 targetSpace: '15vp', 480 onStateChange: (e) => { 481 if (!e.isVisible) { 482 this.handlePopup = false; 483 } 484 }, 485 onWillDismiss: ( 486 (dismissPopupAction: DismissPopupAction) => { 487 console.info("dismissReason:" + JSON.stringify(dismissPopupAction.reason)); 488 if (dismissPopupAction.reason === DismissReason.PRESS_BACK) { 489 dismissPopupAction.dismiss(); 490 } 491 } 492 ) 493 }) 494 }.margin(20) 495 } 496} 497``` 498 499 500 501### Example 6: Intercepting the Popup Dismissal Event 502 503In this example, the **onWillDismiss** property is set to **false** to intercept the dismissal event of the popup. 504 505```ts 506// xxx.ets 507 508@Entry 509@Component 510struct PopupExample { 511 @State handlePopup: boolean = false; 512 513 build() { 514 Column() { 515 Button('PopupOptions') 516 .onClick(() => { 517 this.handlePopup = true; 518 }) 519 .bindPopup(this.handlePopup, { 520 message: 'This is a popup with PopupOptions', 521 messageOptions: { 522 textColor: Color.Red, 523 font: { 524 size: '14vp', 525 style: FontStyle.Italic, 526 weight: FontWeight.Bolder 527 } 528 }, 529 placement: Placement.Bottom, 530 enableArrow: false, 531 targetSpace: '15vp', 532 followTransformOfTarget: true, 533 onStateChange: (e) => { 534 let timer = setTimeout(() => { 535 this.handlePopup = false; 536 }, 6000); 537 if (!e.isVisible) { 538 this.handlePopup = false; 539 clearTimeout(timer); 540 } 541 }, 542 onWillDismiss: false 543 }) 544 }.margin(20) 545 } 546} 547``` 548 549 550
