Floating UI

Source

<script setup lang="ts">
import { ref } from "vue";
import MtFloatingUi from "@shopware-ag/meteor-component-library/MtFloatingUi";
import MtButton from "@shopware-ag/meteor-component-library/MtButton";
import MtNumberField from "@shopware-ag/meteor-component-library/MtNumberField";

const isOpened = ref(false);
const width = ref(120);
const height = ref(120);
</script>

<template>
  <mt-floating-ui
    :is-opened="isOpened"
    show-arrow
    :offset="6"
    @close="isOpened = false"
  >
    <template #trigger>
      <mt-button variant="secondary" @click="isOpened = !isOpened">
        Toggle floating UI
      </mt-button>
    </template>

    <div class="floating-surface">
      <strong class="floating-surface__title">Adjust size</strong>
      <div class="floating-surface__fields">
        <mt-number-field
          v-model="width"
          label="Width"
          size="small"
          number-type="int"
        />
        <mt-number-field
          v-model="height"
          label="Height"
          size="small"
          number-type="int"
        />
      </div>
      <mt-button size="small" variant="primary">Apply</mt-button>
    </div>
  </mt-floating-ui>
</template>

<style scoped>
.floating-surface {
  width: 320px;
  padding: 16px;
  border-radius: var(--border-radius-m);
  border: 1px solid var(--color-border-secondary-default);
  background: var(--color-elevation-surface-raised);
  box-shadow: 0 6px 24px -8px rgba(16, 16, 19, 0.1);
}

.floating-surface__title {
  display: block;
  margin-bottom: 10px;
}

.floating-surface__fields {
  display: flex;
  gap: 12px;
  margin-bottom: 10px;
}
</style>

Usage

Floating UI is a low-level primitive for building custom popover-style surfaces such as rich pickers, menus, inspectors, or inline tools, with automatic positioning relative to a trigger element. Use it when higher-level components such as Action Menu do not fit the custom floating interaction you need.

import { MtFloatingUi } from "@shopware-ag/meteor-component-library";

Examples

Multiple anchors

Use detached mode together with anchorElement to share one floating surface across multiple triggers. The floating panel repositions itself to each anchor as the user hovers, and a short close delay keeps it reachable when the cursor travels from trigger to panel.

<script setup lang="ts">
import { ref } from "vue";
import MtFloatingUi from "@shopware-ag/meteor-component-library/MtFloatingUi";
import MtButton from "@shopware-ag/meteor-component-library/MtButton";

const anchors = ["Anchor 1", "Anchor 2", "Anchor 3"];

const isOpened = ref(false);
const anchorElement = ref<HTMLElement | null>(null);
const activeAnchor = ref("");
let closeTimer: ReturnType<typeof setTimeout> | null = null;

function openFor(event: MouseEvent, anchor: string) {
  if (closeTimer) {
    clearTimeout(closeTimer);
    closeTimer = null;
  }
  anchorElement.value = event.currentTarget as HTMLElement;
  activeAnchor.value = anchor;
  isOpened.value = true;
}

function scheduleClose() {
  closeTimer = setTimeout(() => {
    isOpened.value = false;
  }, 200);
}

function cancelClose() {
  if (closeTimer) {
    clearTimeout(closeTimer);
    closeTimer = null;
  }
}
</script>

<template>
  <div class="anchors">
    <div
      v-for="anchor in anchors"
      :key="anchor"
      @mouseenter="openFor($event, anchor)"
      @mouseleave="scheduleClose"
    >
      <mt-button variant="secondary">{{ anchor }}</mt-button>
    </div>
  </div>

  <mt-floating-ui
    :is-opened="isOpened"
    :anchor-element="anchorElement"
    :floating-ui-options="{ placement: 'bottom' }"
    detached
    @close="isOpened = false"
  >
    <div
      class="floating-surface"
      @mouseenter="cancelClose"
      @mouseleave="scheduleClose"
    >
      <strong>{{ activeAnchor }}</strong>
      <p class="floating-surface__text">
        One shared floating surface, repositioned to the hovered anchor.
      </p>
    </div>
  </mt-floating-ui>
</template>

<style scoped>
.anchors {
  display: flex;
  gap: 12px;
}

.floating-surface {
  width: 280px;
  padding: 16px;
  border-radius: var(--border-radius-m);
  border: 1px solid var(--color-border-secondary-default);
  background: var(--color-elevation-surface-raised);
  box-shadow: 0 6px 24px -8px rgba(16, 16, 19, 0.1);
}

.floating-surface__text {
  margin-top: 6px;
  font-size: var(--font-size-xs);
  color: var(--color-text-secondary-default);
}
</style>

API reference

Props

Prop	Type	Default
`is-opened` *	`boolean`
`floating-ui-options`	`Partial<{ placement?: Placement \| undefined; strategy?: Strategy \| undefined; middleware?: (false \| { name: string; options?: any; fn: (state: { placement: Placement; middlewareData: MiddlewareData; x: number; y: number; initialPlacement: Placement; strategy: Strategy; rects: ElementRects; platform: Platform; elements: Elements; }) => Promisable<MiddlewareReturn>; } \| null \| undefined)[] \| undefined; platform?: Platform \| undefined; }> \| undefined`
`show-arrow`	`boolean`
`offset`	`number`
`auto-update-options`	`Partial<AutoUpdateOptions>`
`match-reference-width` If true, the floating UI content will match the width of the reference element.	`boolean`
`anchor-element` An external DOM element to anchor the floating content to, instead of the built-in trigger slot wrapper	`HTMLElement \| null`
`detached` When true, the trigger slot is not rendered and the root wrapper is not displayed Use with `anchorElement`.	`boolean`

Events

Event	Payload
`close`	`[]`

Slots

Slot	Bindings
`trigger`	`{}`
`default`	`{ referenceElementWidth: number; referenceElementHeight: number; }`

Best practices

Manage the open state outside the component and update it through isOpened and the close event.
Provide a clear trigger element so users understand what opens the floating surface.
Style the slotted content as a complete surface, including background, border, spacing, and shadow.
Use matchReferenceWidth when the floating surface should align to the trigger width.

Don't

Do not use Floating UI when a higher-level component such as Action Menu already fits the use case.
Do not rely on it to provide a finished surface design. It only handles positioning and behavior.
Do not forget to handle keyboard and focus behavior for custom interactive content.

Behavior

Floating UI teleports its content to body, so the floating surface can escape clipping and stacking issues in the local layout.
It uses Floating UI middleware to offset, flip, and measure the floating surface automatically.
showArrow adds an arrow element, but the slotted content still needs to provide the actual surface styling.
The default slot receives referenceElementWidth and referenceElementHeight, which help when the floating content needs to size itself relative to the trigger.
matchReferenceWidth sets the floating container width to the trigger width automatically.

Accessibility

Make sure the trigger clearly communicates what it opens.
If the floating content contains interactive controls, manage focus and keyboard behavior intentionally.
Provide visible structure and labels inside the floating surface so the custom content stays understandable once opened.

Popover: when the standard popover styling and interaction model already fit.
Action Menu: when you need a standard menu of actions or options.

Edit this pageorReport an issue

Entity Select

A repository-backed select that loads its options from an Admin SDK entity repository.

Help Text

A small help trigger that reveals brief supporting guidance in a tooltip.