How can developers create and manage custom popup views in HarmonyOS?

#huawei #harmony #harmonyos

Read the original article：How can developers create and manage custom popup views in HarmonyOS?

Context

Popups are small UI elements that show extra information or tips. They are often used for screen recording, tooltips, or simple notifications. In HarmonyOS, developers can create basic popups with PopupOptions, or fully customized ones using CustomPopupOptions and the @Builder function.

Description

Standard popups are limited in layout and design. If you need a more flexible popup (for example, with images, custom text layout, or styles), you can create a custom popup using the builder function.

There are some important rules when using popups:

You can only show a popup after the page is fully built. Showing it too early may cause position or shape issues.
You can control the popup’s background with the mask property — for example, mask: true makes the background dim and blocks touches behind the popup.

Solution / Approach

Here is a working example of a custom popup using @Builder and bindPopup.

@Entry
@Component
struct Index {
  @State customPopup: boolean = false
  @Builder popupBuilder() {
    Column({space: 6})
    {
      Row({ space: 2 }) {
        Image($r("app.media.ic_info"))
          .width(90)
          .height(90)

        Text('This is Custom Popup')
          .fontSize(18)
          .fontWeight(FontWeight.Bold)
      }
      .alignItems(VerticalAlign.Center)

      Text('This is Custom Popup Info Text')
        .fontSize(16)
        .fontWeight(FontWeight.Regular)
    }
    .alignItems(HorizontalAlign.Center)
    .width(300)
    .height(140)
    .padding(5)
    .borderRadius(24)
    .borderWidth(1)
    .borderColor(Color.Orange)
  }

  build() {
    Column() {
      Button('Show Popup')
        .onClick(() => {
          this.customPopup = !this.customPopup
        })
        .bindPopup(this.customPopup, {
          builder: this.popupBuilder,
          placement:Placement.Bottom,
          popupColor:Color.Orange,
          onStateChange: (e) => {
            if (!e.isVisible) {
              this.customPopup = false
            }
          }
        })
    }
    .alignItems(HorizontalAlign.Center)
    .justifyContent(FlexAlign.Center)
    .width('100%')
    .height('100%')
  }
}

popupBuilder() defines the layout and content of the popup.
The popup includes an image and two text lines.
bindPopup() links the popup to a button. When the button is clicked, the popup shows.
onStateChange is used to update the state when the popup is closed.