Floating UI Mechanism

Concepts

The following are examples of floating UI components:

• HPopover
• HTooltip
• HSelect
• HDropdown

Consider a dropdown component: when you click the Share button, a dropdown menu appears:

A floating component consists of three parts:

• Trigger: When the user interacts with this element (e.g., focus or click), it toggles the open state of the menu.
• Anchor: When the menu is open, it is positioned relative to this element.
• Floating content: The menu itself.

By default, the trigger also serves as the anchor. Clicking the Share button displays the menu directly beneath it:

You can change the anchor to display the floating content in a different position (see Changing the anchor):

Basic Usage

Props Mapping

• The trigger element is the first child of the floating component.
• floating-* props apply to the floating content element.

👉 Conditional rendering of the trigger element

Avoid setting v-if directly on the trigger element, as this causes the component to re-render. As a result, the floating UI may lose its anchor HTML element reference, causing the floating menu to appear in the wrong position.

<HDropdown>
  <HButton
    v-if="showButton"
    label="Share"
  />
</HDropdown>

Instead, either move the v-if to the floating component itself (recommended), or wrap the trigger element in a <div>:

<!-- Recommended -->
<HDropdown
  v-if="showButton"
>
  <HButton
    label="Share"
  />
</HDropdown>

<!-- Alternative -->
<HDropdown>
  <div v-if="showButton">
    <HButton
      label="Share"
    />
  </div>
</HDropdown>

Trigger

Changing the Anchor

match-anchor-size Prop Behavior

This prop controls how the floating menu's width is determined.

false: The floating menu size grows freely.	true: The floating menu size matches the anchor size.
min: The minimum floating menu size matches the anchor size.	max: The maximum floating menu size matches the anchor size.

Nested Layers & Click Outside Behavior

Scenario

• Clicking Trigger 0 opens Layer 1.
• Clicking Trigger 1 opens Layer 2.
• Clicking Trigger 2 opens Layer 3.

Default Behavior

Clicking outside all layers closes all layers.

Clicking inside a child layer (but outside its parent) does not close the parent layer.
For example: Clicking on Layer 3 does not close Layer 2.

Closing Layers One by One

If you want to close layers one at a time when clicking outside, set the prop disableOutSidePointerEvent = true on each layer you want to behave this way.

Example: If you set this prop to true for Layer 2 and Layer 3:

1. Click outside → closes Layer 3.
2. Click outside again → closes Layer 2.
3. Click outside again → closes Layer 1.