Popup

Popup is a utility that lets you declaratively anchor "popup" containers to another element.

This component's name is inspired by <popup>. It uses Floating UI under the hood to provide a well-tested, lightweight, and fully declarative positioning utility for tooltips, dropdowns, and more.

Popup doesn't provide any styles — just positioning! The popup's preferred placement, distance, and skidding (offset) can be configured using attributes. An arrow that points to the anchor can be shown and customized to your liking. Additional positioning options are available and described in more detail below.

Popup is a low-level utility built specifically for positioning elements. Do not mistake it for a tooltip or similar because it does not facilitate an accessible experience! Almost every correct usage of <wa-popup> will involve building other components. It should rarely, if ever, occur directly in your HTML.

val placementVar = Var[SharedTypes.Placement]("top")
val distanceVar  = Var("0")
val skiddingVar  = Var("0")
val activeVar    = Var(true)
val arrowVar     = Var(false)

div(
  Popup(
    _.placement <-- placementVar,
    _.distance <-- distanceVar.signal.map(_.toDouble),
    _.skidding <-- skiddingVar.signal.map(_.toDouble),
    _.active <-- activeVar,
    _.arrow <-- arrowVar,
    _.style := "--arrow-color: var(--wa-color-brand-fill-loud)",
    _.slots.anchor(
      span(
        display.inlineBlock,
        width.px(150),
        height.px(150),
        border := "1px dashed var(--wa-color-neutral-fill-loud)",
        margin.px(50)
      )
    )
  )(
    div(
      width.px(100),
      height.px(50),
      background   := "var(--wa-color-brand-fill-loud)",
      borderRadius := "var(--wa-border-radius-m)"
    )
  ),
  div(
    cls("flex gap-2"),
    Select(
      _.label := "Placement",
      _.name  := "placement",
      _.value <-- placementVar,
      _.onInput.mapToValue.map(_.asInstanceOf[SharedTypes.Placement]) --> placementVar
    )(
      UOption(_.value := CommonKeys.Placement.top.value)("top"),
      UOption(_.value := CommonKeys.Placement.topStart.value)("top-start"),
      UOption(_.value := CommonKeys.Placement.topEnd.value)("top-end"),
      UOption(_.value := CommonKeys.Placement.bottom.value)("bottom"),
      UOption(_.value := CommonKeys.Placement.bottomStart.value)("bottom-start"),
      UOption(_.value := CommonKeys.Placement.bottomEnd.value)("bottom-end"),
      UOption(_.value := CommonKeys.Placement.right.value)("right"),
      UOption(_.value := CommonKeys.Placement.rightStart.value)("right-start"),
      UOption(_.value := CommonKeys.Placement.rightEnd.value)("right-end"),
      UOption(_.value := CommonKeys.Placement.left.value)("left"),
      UOption(_.value := CommonKeys.Placement.leftStart.value)("left-start"),
      UOption(_.value := CommonKeys.Placement.leftEnd.value)("left-end")
    ),
    Input(
      _.label := "Distance",
      _.`type`.number,
      _.name := "distance",
      _.value <-- distanceVar,
      _.onInput.mapToValue --> distanceVar
    )(),
    Input(
      _.label := "Skidding",
      _.`type`.number,
      _.name := "skidding",
      _.value <-- skiddingVar,
      _.onInput.mapToValue --> skiddingVar
    )()
  ),
  div(
    cls("flex gap-2 mt-2"),
    Switch(
      _.name := "active",
      _.checked <-- activeVar,
      _.onInput.mapToChecked --> activeVar
    )("Active"),
    Switch(
      _.name := "arrow",
      _.checked <-- arrowVar,
      _.onInput.mapToChecked --> arrowVar
    )("Arrow")
  )
)

val placementVar = Var[SharedTypes.Placement]("top")val distanceVar  = Var("0")val skiddingVar  = Var("0")val activeVar    = Var(true)val arrowVar     = Var(false)div(  Popup(    _.placement <-- placementVar,    _.distance <-- distanceVar.signal.map(_.toDouble),    _.skidding <-- skiddingVar.signal.map(_.toDouble),    _.active <-- activeVar,    _.arrow <-- arrowVar,    _.style := "--arrow-color: var(--wa-color-brand-fill-loud)",    _.slots.anchor(      span(        display.inlineBlock,        width.px(150),        height.px(150),        border := "1px dashed var(--wa-color-neutral-fill-loud)",        margin.px(50)      )    )  )(    div(      width.px(100),      height.px(50),      background   := "var(--wa-color-brand-fill-loud)",      borderRadius := "var(--wa-border-radius-m)"    )  ),  div(    cls("flex gap-2"),    Select(      _.label := "Placement",      _.name  := "placement",      _.value <-- placementVar,      _.onInput.mapToValue.map(_.asInstanceOf[SharedTypes.Placement]) --> placementVar    )(      UOption(_.value := CommonKeys.Placement.top.value)("top"),      UOption(_.value := CommonKeys.Placement.topStart.value)("top-start"),      UOption(_.value := CommonKeys.Placement.topEnd.value)("top-end"),      UOption(_.value := CommonKeys.Placement.bottom.value)("bottom"),      UOption(_.value := CommonKeys.Placement.bottomStart.value)("bottom-start"),      UOption(_.value := CommonKeys.Placement.bottomEnd.value)("bottom-end"),      UOption(_.value := CommonKeys.Placement.right.value)("right"),      UOption(_.value := CommonKeys.Placement.rightStart.value)("right-start"),      UOption(_.value := CommonKeys.Placement.rightEnd.value)("right-end"),      UOption(_.value := CommonKeys.Placement.left.value)("left"),      UOption(_.value := CommonKeys.Placement.leftStart.value)("left-start"),      UOption(_.value := CommonKeys.Placement.leftEnd.value)("left-end")    ),    Input(      _.label := "Distance",      _.`type`.number,      _.name := "distance",      _.value <-- distanceVar,      _.onInput.mapToValue --> distanceVar    )(),    Input(      _.label := "Skidding",      _.`type`.number,      _.name := "skidding",      _.value <-- skiddingVar,      _.onInput.mapToValue --> skiddingVar    )()  ),  div(    cls("flex gap-2 mt-2"),    Switch(      _.name := "active",      _.checked <-- activeVar,      _.onInput.mapToChecked --> activeVar    )("Active"),    Switch(      _.name := "arrow",      _.checked <-- arrowVar,      _.onInput.mapToChecked --> arrowVar    )("Arrow")  ))

A popup's anchor should not be styled with display: contents since the coordinates will not be eligible for calculation. However, if the anchor is a <slot> element, popup will use the first assigned element as the anchor. This behavior allows other components to pass anchors through more easily via composition.

Examples

Activating

Popups are inactive and hidden until the active attribute is applied. Removing the attribute will tear down all positioning logic and listeners, meaning you can have many idle popups on the page without affecting performance.

val activeVar = Var(true)

div(
  Popup(
    _.placement.top,
    _.active <-- activeVar,
    _.slots.anchor(
      span(
        display.inlineBlock,
        width.px(150),
        height.px(150),
        border := "2px dashed var(--wa-color-neutral-fill-loud)",
        margin.px(50)
      )
    )
  )(
    div(
      width.px(100),
      height.px(50),
      background   := "var(--wa-color-brand-fill-loud)",
      borderRadius := "var(--wa-border-radius-m)"
    )
  ),
  br(),
  Switch(
    _.checked <-- activeVar,
    _.onInput.mapToChecked --> activeVar
  )("Active")
)

val activeVar = Var(true)div(  Popup(    _.placement.top,    _.active <-- activeVar,    _.slots.anchor(      span(        display.inlineBlock,        width.px(150),        height.px(150),        border := "2px dashed var(--wa-color-neutral-fill-loud)",        margin.px(50)      )    )  )(    div(      width.px(100),      height.px(50),      background   := "var(--wa-color-brand-fill-loud)",      borderRadius := "var(--wa-border-radius-m)"    )  ),  br(),  Switch(    _.checked <-- activeVar,    _.onInput.mapToChecked --> activeVar  )("Active"))

External Anchors

By default, anchors are slotted into the popup using the anchor slot. If your anchor needs to live outside of the popup, you can pass the anchor's id to the anchor attribute. Alternatively, you can pass an element reference to the anchor property to achieve the same effect without using an id.

div(
  span(
    idAttr := "external-anchor",
    display.inlineBlock,
    width.px(150),
    height.px(150),
    border := "2px dashed var(--wa-color-neutral-fill-loud)",
    margin := "50px 0 0 50px"
  ),
  Popup(
    _.anchor := "external-anchor",
    _.placement.top,
    _.active := true
  )(
    div(
      width.px(100),
      height.px(50),
      background   := "var(--wa-color-brand-fill-loud)",
      borderRadius := "var(--wa-border-radius-m)"
    )
  )
)

div(  span(    idAttr := "external-anchor",    display.inlineBlock,    width.px(150),    height.px(150),    border := "2px dashed var(--wa-color-neutral-fill-loud)",    margin := "50px 0 0 50px"  ),  Popup(    _.anchor := "external-anchor",    _.placement.top,    _.active := true  )(    div(      width.px(100),      height.px(50),      background   := "var(--wa-color-brand-fill-loud)",      borderRadius := "var(--wa-border-radius-m)"    )  ))

Placement

Use the placement attribute to tell the popup the preferred placement of the popup. Note that the actual position will vary to ensure the panel remains in the viewport if you're using positioning features such as flip and shift.

Since placement is preferred when using flip, you can observe the popup's current placement when it's active by looking at the data-current-placement attribute. This attribute will update as the popup flips to find available space and it will be removed when the popup is deactivated.

val placementVar = Var[SharedTypes.Placement]("top")

div(
  Popup(
    _.placement <-- placementVar,
    _.active := true,
    _.slots.anchor(
      span(
        display.inlineBlock,
        width.px(150),
        height.px(150),
        border := "2px dashed var(--wa-color-neutral-fill-loud)",
        margin.px(50)
      )
    )
  )(
    div(
      width.px(100),
      height.px(50),
      background   := "var(--wa-color-brand-fill-loud)",
      borderRadius := "var(--wa-border-radius-m)"
    )
  ),
  Select(
    _.label := "Placement",
    _.value <-- placementVar,
    _.onInput.mapToValue.map(_.asInstanceOf[SharedTypes.Placement]) --> placementVar,
    _.style := "max-width: 280px;"
  )(
    UOption(_.value := CommonKeys.Placement.top.value)("top"),
    UOption(_.value := CommonKeys.Placement.topStart.value)("top-start"),
    UOption(_.value := CommonKeys.Placement.topEnd.value)("top-end"),
    UOption(_.value := CommonKeys.Placement.bottom.value)("bottom"),
    UOption(_.value := CommonKeys.Placement.bottomStart.value)("bottom-start"),
    UOption(_.value := CommonKeys.Placement.bottomEnd.value)("bottom-end"),
    UOption(_.value := CommonKeys.Placement.right.value)("right"),
    UOption(_.value := CommonKeys.Placement.rightStart.value)("right-start"),
    UOption(_.value := CommonKeys.Placement.rightEnd.value)("right-end"),
    UOption(_.value := CommonKeys.Placement.left.value)("left"),
    UOption(_.value := CommonKeys.Placement.leftStart.value)("left-start"),
    UOption(_.value := CommonKeys.Placement.leftEnd.value)("left-end")
  )
)

val placementVar = Var[SharedTypes.Placement]("top")div(  Popup(    _.placement <-- placementVar,    _.active := true,    _.slots.anchor(      span(        display.inlineBlock,        width.px(150),        height.px(150),        border := "2px dashed var(--wa-color-neutral-fill-loud)",        margin.px(50)      )    )  )(    div(      width.px(100),      height.px(50),      background   := "var(--wa-color-brand-fill-loud)",      borderRadius := "var(--wa-border-radius-m)"    )  ),  Select(    _.label := "Placement",    _.value <-- placementVar,    _.onInput.mapToValue.map(_.asInstanceOf[SharedTypes.Placement]) --> placementVar,    _.style := "max-width: 280px;"  )(    UOption(_.value := CommonKeys.Placement.top.value)("top"),    UOption(_.value := CommonKeys.Placement.topStart.value)("top-start"),    UOption(_.value := CommonKeys.Placement.topEnd.value)("top-end"),    UOption(_.value := CommonKeys.Placement.bottom.value)("bottom"),    UOption(_.value := CommonKeys.Placement.bottomStart.value)("bottom-start"),    UOption(_.value := CommonKeys.Placement.bottomEnd.value)("bottom-end"),    UOption(_.value := CommonKeys.Placement.right.value)("right"),    UOption(_.value := CommonKeys.Placement.rightStart.value)("right-start"),    UOption(_.value := CommonKeys.Placement.rightEnd.value)("right-end"),    UOption(_.value := CommonKeys.Placement.left.value)("left"),    UOption(_.value := CommonKeys.Placement.leftStart.value)("left-start"),    UOption(_.value := CommonKeys.Placement.leftEnd.value)("left-end")  ))

Distance

Use the distance attribute to change the distance between the popup and its anchor. A positive value will move the popup further away and a negative value will move it closer.

val distanceVar = Var(0.0)

div(
  Popup(
    _.placement.top,
    _.distance <-- distanceVar,
    _.active := true,
    _.slots.anchor(
      span(
        display.inlineBlock,
        width.px(150),
        height.px(150),
        border := "2px dashed var(--wa-color-neutral-fill-loud)",
        margin.px(50)
      )
    )
  )(
    div(
      width.px(100),
      height.px(50),
      background   := "var(--wa-color-brand-fill-loud)",
      borderRadius := "var(--wa-border-radius-m)"
    )
  ),
  Slider(
    _.label := "Distance",
    _.min   := -50,
    _.max   := 50,
    _.step  := 1,
    _.value <-- distanceVar.signal.map(_.toString),
    _.onInput.map(_.target.value) --> distanceVar
  )(
    maxWidth := "260px"
  )
)

val distanceVar = Var(0.0)div(  Popup(    _.placement.top,    _.distance <-- distanceVar,    _.active := true,    _.slots.anchor(      span(        display.inlineBlock,        width.px(150),        height.px(150),        border := "2px dashed var(--wa-color-neutral-fill-loud)",        margin.px(50)      )    )  )(    div(      width.px(100),      height.px(50),      background   := "var(--wa-color-brand-fill-loud)",      borderRadius := "var(--wa-border-radius-m)"    )  ),  Slider(    _.label := "Distance",    _.min   := -50,    _.max   := 50,    _.step  := 1,    _.value <-- distanceVar.signal.map(_.toString),    _.onInput.map(_.target.value) --> distanceVar  )(    maxWidth := "260px"  ))

Skidding

The skidding attribute is similar to distance, but instead allows you to offset the popup along the anchor's axis. Both positive and negative values are allowed.

val skiddingVar = Var(0.0)

div(
  Popup(
    _.placement.top,
    _.skidding <-- skiddingVar,
    _.active := true,
    _.slots.anchor(
      span(
        display.inlineBlock,
        width.px(150),
        height.px(150),
        border := "2px dashed var(--wa-color-neutral-fill-loud)",
        margin.px(50)
      )
    )
  )(
    div(
      width.px(100),
      height.px(50),
      background   := "var(--wa-color-brand-fill-loud)",
      borderRadius := "var(--wa-border-radius-m)"
    )
  ),
  Slider(
    _.label := "Skidding",
    _.min   := -50,
    _.max   := 50,
    _.step  := 1,
    _.value <-- skiddingVar.signal.map(_.toString),
    _.onInput.map(_.target.value) --> skiddingVar
  )(
    maxWidth := "260px"
  )
)

val skiddingVar = Var(0.0)div(  Popup(    _.placement.top,    _.skidding <-- skiddingVar,    _.active := true,    _.slots.anchor(      span(        display.inlineBlock,        width.px(150),        height.px(150),        border := "2px dashed var(--wa-color-neutral-fill-loud)",        margin.px(50)      )    )  )(    div(      width.px(100),      height.px(50),      background   := "var(--wa-color-brand-fill-loud)",      borderRadius := "var(--wa-border-radius-m)"    )  ),  Slider(    _.label := "Skidding",    _.min   := -50,    _.max   := 50,    _.step  := 1,    _.value <-- skiddingVar.signal.map(_.toString),    _.onInput.map(_.target.value) --> skiddingVar  )(    maxWidth := "260px"  ))

Arrows

Add an arrow to your popup with the arrow attribute. It's usually a good idea to set a distance to make room for the arrow. To adjust the arrow's color and size, use the --arrow-color and --arrow-size custom properties, respectively. You can also target the arrow part to add additional styles such as shadows and borders.

By default, the arrow will be aligned as close to the center of the anchor as possible, considering available space and arrow-padding. You can use the arrow-placement attribute to force the arrow to align to the start, end, or center of the popup instead.

val placementVar      = Var[SharedTypes.Placement]("top")
val arrowPlacementVar = Var[PopupArrowPlacement]("anchor")
val arrowVar          = Var(true)

div(
  Popup(
    _.placement <-- placementVar,
    _.arrow <-- arrowVar,
    _.arrowPlacement <-- arrowPlacementVar,
    _.distance := 8,
    _.active   := true,
    _.style    := "--arrow-color: var(--wa-color-brand-fill-loud)",
    _.slots.anchor(
      span(
        display.inlineBlock,
        width.px(150),
        height.px(150),
        border := "2px dashed var(--wa-color-neutral-fill-loud)",
        margin.px(50)
      )
    )
  )(
    div(
      width.px(100),
      height.px(50),
      background   := "var(--wa-color-brand-fill-loud)",
      borderRadius := "var(--wa-border-radius-m)"
    )
  ),
  div(
    cls("flex flex-wrap gap-4 items-end"),
    Select(
      _.label := "Placement",
      _.name  := "placement",
      _.value <-- placementVar,
      _.onInput.mapToValue.map(_.asInstanceOf[SharedTypes.Placement]) --> placementVar
    )(
      width := "160px",
      UOption(_.value := CommonKeys.Placement.top.value)("top"),
      UOption(_.value := CommonKeys.Placement.topStart.value)("top-start"),
      UOption(_.value := CommonKeys.Placement.topEnd.value)("top-end"),
      UOption(_.value := CommonKeys.Placement.bottom.value)("bottom"),
      UOption(_.value := CommonKeys.Placement.bottomStart.value)("bottom-start"),
      UOption(_.value := CommonKeys.Placement.bottomEnd.value)("bottom-end"),
      UOption(_.value := CommonKeys.Placement.right.value)("right"),
      UOption(_.value := CommonKeys.Placement.rightStart.value)("right-start"),
      UOption(_.value := CommonKeys.Placement.rightEnd.value)("right-end"),
      UOption(_.value := CommonKeys.Placement.left.value)("left"),
      UOption(_.value := CommonKeys.Placement.leftStart.value)("left-start"),
      UOption(_.value := CommonKeys.Placement.leftEnd.value)("left-end")
    ),
    Select(
      _.label := "Arrow Placement",
      _.name  := "arrow-placement",
      _.value <-- arrowPlacementVar,
      _.onInput.mapToValue.map {
        case p: PopupArrowPlacement =>
          arrowPlacementVar.set(p)
        case _ => ()
      } --> Observer.empty
    )(
      width := "160px",
      UOption(_.value := "anchor")("anchor"),
      UOption(_.value := "start")("start"),
      UOption(_.value := "end")("end"),
      UOption(_.value := "center")("center")
    )
  ),
  div(
    cls("flex gap-4 mt-4"),
    Switch(
      _.name := "arrow",
      _.checked <-- arrowVar,
      _.onInput.mapToChecked --> arrowVar
    )("Arrow")
  )
)

val placementVar      = Var[SharedTypes.Placement]("top")val arrowPlacementVar = Var[PopupArrowPlacement]("anchor")val arrowVar          = Var(true)div(  Popup(    _.placement <-- placementVar,    _.arrow <-- arrowVar,    _.arrowPlacement <-- arrowPlacementVar,    _.distance := 8,    _.active   := true,    _.style    := "--arrow-color: var(--wa-color-brand-fill-loud)",    _.slots.anchor(      span(        display.inlineBlock,        width.px(150),        height.px(150),        border := "2px dashed var(--wa-color-neutral-fill-loud)",        margin.px(50)      )    )  )(    div(      width.px(100),      height.px(50),      background   := "var(--wa-color-brand-fill-loud)",      borderRadius := "var(--wa-border-radius-m)"    )  ),  div(    cls("flex flex-wrap gap-4 items-end"),    Select(      _.label := "Placement",      _.name  := "placement",      _.value <-- placementVar,      _.onInput.mapToValue.map(_.asInstanceOf[SharedTypes.Placement]) --> placementVar    )(      width := "160px",      UOption(_.value := CommonKeys.Placement.top.value)("top"),      UOption(_.value := CommonKeys.Placement.topStart.value)("top-start"),      UOption(_.value := CommonKeys.Placement.topEnd.value)("top-end"),      UOption(_.value := CommonKeys.Placement.bottom.value)("bottom"),      UOption(_.value := CommonKeys.Placement.bottomStart.value)("bottom-start"),      UOption(_.value := CommonKeys.Placement.bottomEnd.value)("bottom-end"),      UOption(_.value := CommonKeys.Placement.right.value)("right"),      UOption(_.value := CommonKeys.Placement.rightStart.value)("right-start"),      UOption(_.value := CommonKeys.Placement.rightEnd.value)("right-end"),      UOption(_.value := CommonKeys.Placement.left.value)("left"),      UOption(_.value := CommonKeys.Placement.leftStart.value)("left-start"),      UOption(_.value := CommonKeys.Placement.leftEnd.value)("left-end")    ),    Select(      _.label := "Arrow Placement",      _.name  := "arrow-placement",      _.value <-- arrowPlacementVar,      _.onInput.mapToValue.map {        case p: PopupArrowPlacement =>          arrowPlacementVar.set(p)        case _ => ()      } --> Observer.empty    )(      width := "160px",      UOption(_.value := "anchor")("anchor"),      UOption(_.value := "start")("start"),      UOption(_.value := "end")("end"),      UOption(_.value := "center")("center")    )  ),  div(    cls("flex gap-4 mt-4"),    Switch(      _.name := "arrow",      _.checked <-- arrowVar,      _.onInput.mapToChecked --> arrowVar    )("Arrow")  ))

Flip

When the popup doesn't have enough room in its preferred placement, it can automatically flip to keep it in view and visually connected to its anchor. To enable this, use the flip attribute. By default, the popup will flip to the opposite placement, but you can configure preferred fallback placements using flip-fallback-placement and flip-fallback-strategy. Additional options are available to control the flip behavior's boundary and padding.

By default, flip takes effect when the popup would overflow the viewport. You can use boundary="scroll" to make the popup resize when it overflows its nearest scrollable container instead.

Scroll the container to see how the popup flips to prevent clipping.

val flipVar = Var(true)

div(
  div(
    position.relative,
    height.px(300),
    border := "2px solid var(--wa-color-surface-border)",
    overflow.auto,
    Popup(
      _.placement.top,
      _.flip <-- flipVar,
      _.active := true,
      _.boundary.scroll,
      _.slots.anchor(
        span(
          display.inlineBlock,
          width.px(150),
          height.px(150),
          border := "2px dashed var(--wa-color-neutral-fill-loud)",
          margin := "150px 50px"
        )
      )
    )(
      div(
        width.px(100),
        height.px(50),
        background   := "var(--wa-color-brand-fill-loud)",
        borderRadius := "var(--wa-border-radius-m)"
      )
    )
  ),
  br(),
  Switch(
    _.checked <-- flipVar,
    _.onInput.mapToChecked --> flipVar
  )("Flip")
)

val flipVar = Var(true)div(  div(    position.relative,    height.px(300),    border := "2px solid var(--wa-color-surface-border)",    overflow.auto,    Popup(      _.placement.top,      _.flip <-- flipVar,      _.active := true,      _.boundary.scroll,      _.slots.anchor(        span(          display.inlineBlock,          width.px(150),          height.px(150),          border := "2px dashed var(--wa-color-neutral-fill-loud)",          margin := "150px 50px"        )      )    )(      div(        width.px(100),        height.px(50),        background   := "var(--wa-color-brand-fill-loud)",        borderRadius := "var(--wa-border-radius-m)"      )    )  ),  br(),  Switch(    _.checked <-- flipVar,    _.onInput.mapToChecked --> flipVar  )("Flip"))

Flip Fallbacks

While using the flip attribute, you can customize the placement of the popup when the preferred placement doesn't have room. For this, use flip-fallback-placements and flip-fallback-strategy.

If the preferred placement doesn't have room, the first suitable placement found in flip-fallback-placement will be used. The value of this attribute must be a string including any number of placements separated by a space, e.g. "right bottom".

If no fallback placement works, the final placement will be determined by flip-fallback-strategy. This value can be either initial (default), where the placement reverts to the position in placement, or best-fit, where the placement is chosen based on available space.

Scroll the container to see how the popup changes it's fallback placement to prevent clipping.

div(
  position.relative,
  height.px(300),
  border := "2px solid var(--wa-color-surface-border)",
  overflow.auto,
  Popup(
    _.placement.top,
    _.flip                   := true,
    _.flipFallbackPlacements := "right bottom",
    _.flipFallbackStrategy.initial,
    _.active := true,
    _.boundary.scroll,
    _.slots.anchor(
      span(
        display.inlineBlock,
        width.px(150),
        height.px(150),
        border := "2px dashed var(--wa-color-neutral-fill-loud)",
        margin := "250px 50px"
      )
    )
  )(
    div(
      width.px(100),
      height.px(50),
      background   := "var(--wa-color-brand-fill-loud)",
      borderRadius := "var(--wa-border-radius-m)"
    )
  )
)

div(  position.relative,  height.px(300),  border := "2px solid var(--wa-color-surface-border)",  overflow.auto,  Popup(    _.placement.top,    _.flip                   := true,    _.flipFallbackPlacements := "right bottom",    _.flipFallbackStrategy.initial,    _.active := true,    _.boundary.scroll,    _.slots.anchor(      span(        display.inlineBlock,        width.px(150),        height.px(150),        border := "2px dashed var(--wa-color-neutral-fill-loud)",        margin := "250px 50px"      )    )  )(    div(      width.px(100),      height.px(50),      background   := "var(--wa-color-brand-fill-loud)",      borderRadius := "var(--wa-border-radius-m)"    )  ))

Shift

When a popup is longer than its anchor, it risks overflowing. In this case, use the shift attribute to shift the popup along its axis and back into view. You can customize the shift behavior using shiftBoundary and shift-padding.

By default, auto-size takes effect when the popup would overflow the viewport. You can use boundary="scroll" to make the popup resize when it overflows its nearest scrollable container instead.

Toggle the switch to see the difference.

val shiftVar = Var(true)

div(
  div(
    position.relative,
    border := "2px solid var(--wa-color-surface-border)",
    overflow.auto,
    Popup(
      _.placement.top,
      _.shift <-- shiftVar,
      _.shiftPadding := 10,
      _.active       := true,
      _.boundary.scroll,
      _.slots.anchor(
        span(
          display.inlineBlock,
          width.px(150),
          height.px(150),
          border := "2px dashed var(--wa-color-neutral-fill-loud)",
          margin := "60px 0 0 10px"
        )
      )
    )(
      div(
        width.px(300),
        height.px(50),
        background   := "var(--wa-color-brand-fill-loud)",
        borderRadius := "var(--wa-border-radius-m)"
      )
    )
  ),
  Switch(
    _.checked <-- shiftVar,
    _.onInput.mapToChecked --> shiftVar
  )("Shift")
)

val shiftVar = Var(true)div(  div(    position.relative,    border := "2px solid var(--wa-color-surface-border)",    overflow.auto,    Popup(      _.placement.top,      _.shift <-- shiftVar,      _.shiftPadding := 10,      _.active       := true,      _.boundary.scroll,      _.slots.anchor(        span(          display.inlineBlock,          width.px(150),          height.px(150),          border := "2px dashed var(--wa-color-neutral-fill-loud)",          margin := "60px 0 0 10px"        )      )    )(      div(        width.px(300),        height.px(50),        background   := "var(--wa-color-brand-fill-loud)",        borderRadius := "var(--wa-border-radius-m)"      )    )  ),  Switch(    _.checked <-- shiftVar,    _.onInput.mapToChecked --> shiftVar  )("Shift"))

Auto-size

Use the auto-size attribute to tell the popup to resize when necessary to prevent it from overflowing. Possible values are horizontal, vertical, and both. You can use autoSizeBoundary and auto-size-padding to customize the behavior of this option. Auto-size works well with flip, but if you're using auto-size-padding make sure flip-padding is the same value.

By default, auto-size takes effect when the popup would overflow the viewport. You can use boundary="scroll" to make the popup resize when it overflows its nearest scrollable container instead.

When using auto-size, one or both of --auto-size-available-width and --auto-size-available-height will be applied to the host element. These values determine the available space the popover has before clipping will occur. Since they cascade, you can use them to set a max-width/height on your popup's content and easily control its overflow.

Scroll the container to see the popup resize as its available space changes.

val autoSizeVar = Var(true)

div(
  div(
    position.relative,
    height.px(300),
    border := "2px solid var(--wa-color-surface-border)",
    overflow.auto,
    Popup(
      _.placement.top,
      _.autoSize <-- autoSizeVar.signal.map(if (_) "both" else "vertical"),
      _.autoSizePadding := 10,
      _.active          := true,
      _.boundary.scroll,
      _.slots.anchor(
        span(
          display.inlineBlock,
          width.px(150),
          height.px(150),
          border := "2px dashed var(--wa-color-neutral-fill-loud)",
          margin := "250px 50px 100px 50px"
        )
      )
    )(
      div(
        background   := "var(--wa-color-brand-fill-loud)",
        borderRadius := "var(--wa-border-radius-m)",
        width.px(100),
        height.px(200),
        maxWidth  := "var(--auto-size-available-width)",
        maxHeight := "var(--auto-size-available-height)",
        overflow.auto
      )
    )
  ),
  br(),
  Switch(
    _.checked <-- autoSizeVar,
    _.onInput.mapToChecked --> autoSizeVar
  )("Auto-size")
)

val autoSizeVar = Var(true)div(  div(    position.relative,    height.px(300),    border := "2px solid var(--wa-color-surface-border)",    overflow.auto,    Popup(      _.placement.top,      _.autoSize <-- autoSizeVar.signal.map(if (_) "both" else "vertical"),      _.autoSizePadding := 10,      _.active          := true,      _.boundary.scroll,      _.slots.anchor(        span(          display.inlineBlock,          width.px(150),          height.px(150),          border := "2px dashed var(--wa-color-neutral-fill-loud)",          margin := "250px 50px 100px 50px"        )      )    )(      div(        background   := "var(--wa-color-brand-fill-loud)",        borderRadius := "var(--wa-border-radius-m)",        width.px(100),        height.px(200),        maxWidth  := "var(--auto-size-available-width)",        maxHeight := "var(--auto-size-available-height)",        overflow.auto      )    )  ),  br(),  Switch(    _.checked <-- autoSizeVar,    _.onInput.mapToChecked --> autoSizeVar  )("Auto-size"))

Hover Bridge

When a gap exists between the anchor and the popup element, this option will add a "hover bridge" that fills the gap using an invisible element. This makes listening for events such as mouseover and mouseout more sane because the pointer never technically leaves the element. The hover bridge will only be drawn when the popover is active. For demonstration purposes, the bridge in this example is shown in orange.

val hoverBridgeVar = Var(true)
val distanceVar    = Var(10.0)
val skiddingVar    = Var(0.0)

div(
  Popup(
    _.placement.top,
    _.hoverBridge <-- hoverBridgeVar,
    _.distance <-- distanceVar,
    _.skidding <-- skiddingVar,
    _.active := true,
    _.style := """
      --arrow-color: var(--wa-color-brand-fill-loud);
    """.stripMargin.trim,
    _.slots.anchor(
      span(
        display.inlineBlock,
        width.px(150),
        height.px(150),
        border := "2px dashed var(--wa-color-neutral-fill-loud)",
        margin.px(50)
      )
    )
  )(
    div(
      width.px(100),
      height.px(50),
      background   := "var(--wa-color-brand-fill-loud)",
      borderRadius := "var(--wa-border-radius-m)"
    )
  ),
  br(),
  Switch(
    _.checked <-- hoverBridgeVar,
    _.onInput.mapToChecked --> hoverBridgeVar
  )("Hover Bridge"),
  br(),
  Slider(
    _.label := "Distance",
    _.min   := 0,
    _.max   := 50,
    _.step  := 1,
    _.value <-- distanceVar.signal.map(_.toString),
    _.onInput.map(_.target.value) --> distanceVar
  )(
    maxWidth  := "260px",
    marginTop := "0.5rem"
  ),
  Slider(
    _.label := "Skidding",
    _.min   := -50,
    _.max   := 50,
    _.step  := 1,
    _.value <-- skiddingVar.signal.map(_.toString),
    _.onInput.map(_.target.value) --> skiddingVar
  )(
    maxWidth  := "260px",
    marginTop := "0.5rem"
  )
)

val hoverBridgeVar = Var(true)val distanceVar    = Var(10.0)val skiddingVar    = Var(0.0)div(  Popup(    _.placement.top,    _.hoverBridge <-- hoverBridgeVar,    _.distance <-- distanceVar,    _.skidding <-- skiddingVar,    _.active := true,    _.style := """      --arrow-color: var(--wa-color-brand-fill-loud);    """.stripMargin.trim,    _.slots.anchor(      span(        display.inlineBlock,        width.px(150),        height.px(150),        border := "2px dashed var(--wa-color-neutral-fill-loud)",        margin.px(50)      )    )  )(    div(      width.px(100),      height.px(50),      background   := "var(--wa-color-brand-fill-loud)",      borderRadius := "var(--wa-border-radius-m)"    )  ),  br(),  Switch(    _.checked <-- hoverBridgeVar,    _.onInput.mapToChecked --> hoverBridgeVar  )("Hover Bridge"),  br(),  Slider(    _.label := "Distance",    _.min   := 0,    _.max   := 50,    _.step  := 1,    _.value <-- distanceVar.signal.map(_.toString),    _.onInput.map(_.target.value) --> distanceVar  )(    maxWidth  := "260px",    marginTop := "0.5rem"  ),  Slider(    _.label := "Skidding",    _.min   := -50,    _.max   := 50,    _.step  := 1,    _.value <-- skiddingVar.signal.map(_.toString),    _.onInput.map(_.target.value) --> skiddingVar  )(    maxWidth  := "260px",    marginTop := "0.5rem"  ))

Virtual Elements

In most cases, popups are anchored to an actual element. Sometimes, it can be useful to anchor them to a non-element. To do this, you can pass a VirtualElement to the anchor property. A virtual element must contain a function called getBoundingClientRect() that returns a DOMRect object as shown below.

This example anchors a popup to the mouse cursor using a virtual element. As such, a mouse is required to properly view it.

val enabledVar = Var(false)
Var(0.0)
Var(0.0)

div(
  Popup(
    _.placement.rightStart,
    _.active <-- enabledVar,
    // Note: Setting virtual element would need to be done via ref in real implementation
    _.style := "z-index: 1000; pointer-events: none;"
  )(
    div(
      width.px(100),
      height.px(100),
      border       := "4px solid var(--wa-color-neutral-fill-loud)",
      borderRadius := "50%",
      transform    := "translate(-50px, -50px)",
      animation    := "1s virtual-cursor infinite"
    )
  ),
  Switch(
    _.checked <-- enabledVar,
    _.onInput.mapToChecked --> enabledVar
  )("Highlight mouse cursor"),
  // Note: Mouse tracking would need to be implemented via onMouseMove
)

val enabledVar = Var(false)Var(0.0)Var(0.0)div(  Popup(    _.placement.rightStart,    _.active <-- enabledVar,    // Note: Setting virtual element would need to be done via ref in real implementation    _.style := "z-index: 1000; pointer-events: none;"  )(    div(      width.px(100),      height.px(100),      border       := "4px solid var(--wa-color-neutral-fill-loud)",      borderRadius := "50%",      transform    := "translate(-50px, -50px)",      animation    := "1s virtual-cursor infinite"    )  ),  Switch(    _.checked <-- enabledVar,    _.onInput.mapToChecked --> enabledVar  )("Highlight mouse cursor"),  // Note: Mouse tracking would need to be implemented via onMouseMove)

Built-in Animations

The following classes can be applied to the popup's popup part to animate it in or out programmatically. You can control the animation duration with the --show-duration and --hide-duration custom properties.

show / hide - Shows or hides the popover with a fade
show-with-scale / hide-with-scale - Shows or hides the popover with a fade and subtle scale effect

On this page