GrPopover

For a while the role of a universal popover was played by GrDropdown, but it is about a menu: it declares role="menu" and aria-haspopup="menu" rigidly and walks the focus across the items. For a form, a confirmation or a palette that is the wrong semantics — a screen reader will announce a menu where there is none.

Here it is the other way round: the role is set with a prop (dialog by default, plus menu, listbox, grid, group and none), because the keyboard pattern inside the panel belongs to the content. Menus, context menus, palettes and Popconfirm are assembled on this primitive.

The #trigger slot receives triggerProps — they have to be hung on a real focusable element rather than on a wrapper:

<GrPopover>
  <template #trigger="{ triggerProps }">
    <GrButton v-bind="triggerProps">Open</GrButton>
  </template>
</GrPopover>

aria-expanded and aria-controls are obliged to live on the interactive element itself: on a div around it they are mute. The click is listened for by the wrapper in the process — so the trigger can be anything at all, as long as the ARIA travels to the button.

trigger="manual" switches off opening by a click: the moment of opening is decided by the consumer through v-model:open. That is the mode of a context menu and of confirmations.

And that is not an omission. A non-modal layer does not block the page, so Tab is obliged to take the focus outside — otherwise the user is locked in a panel on a working page.

modal switches the second mode on: the background goes into inert, Tab walks in a ring inside the panel, the scrolling of the page is blocked, and the layer enters the stack as a modal one — like a window. A popover with a form or a confirmation needs it: without isolating the background the user takes the focus onto the very page the popover belongs to. In this mode the focus is moved into the panel regardless of autoFocus — the background is unavailable, and a layer without focus inside it would become a keyboard trap.

The modality arrives from the same assembly as in a window, a drawer and a viewer, so there is no second implementation of the modal layer in the package. The stack, Esc and the return of focus to the trigger — ../overlays.md.

The panel is focusable (tabindex="-1"), and on opening the focus is moved precisely to it. Focusing the first control on the user’s behalf is a decision of the content rather than of the shell: in a filter it is appropriate, in a delete confirmation it is not.

For role="dialog" a name is mandatory: either ariaLabel or labelledBy with the id of a visible heading inside the panel. A panel without a name will be announced by a screen reader as “dialog” and nothing more.

closeOnEsc and closeOnClickOutside are on by default. closeOnContentClick is not: it suits a menu, where a click on an item means the choice, and harms a form, where every click on a field would close the panel.

Imperatively — open(), close(), toggle() through a ref on the component. That set is considered the reference one for overlays in the package and is held by the overlayImperativeApi gate.

The panel lies at the same height as GrDropdown (--gr-z-dropdown), and that is deliberate: both are anchored non-modal overlays of one class, and at different heights they would start covering each other depending on the order of opening. The scale of the layers — ../z-index.md.

placement and offsetPx set the side and the gap; the resulting side may differ from the one that was set — the panel flips over when there is not enough room, and the transform-origin of the animation flips with it.

size sets the inner padding and the type size by the control scale — see ../sizes.md.

triggerProps carry both the ARIA and the click. They have to be bound to the interactive element itself rather than to a wrapper around it:

<GrPopover>
  <template #trigger="{ triggerProps }">
    <GrButton v-bind="triggerProps">
      Open
    </GrButton>
  </template>
</GrPopover>

The reason is behaviour rather than tidiness. The #trigger slot may contain more than the trigger: a button next to it, a link in a card, a cross on a chip. A click living on the wrapper would catch them all and open the panel past the user’s intent. One living in triggerProps opens it only from the element it was given to.

A slot left without v-bind="triggerProps" still opens on a click on the wrapper: that is how it used to work, and that has not been taken away. But such a trigger is left without a keyboard and without aria-haspopup/aria-expanded — the panel is not announced to a screen reader, and there is no reaching it with Tab. In a dev build the component warns about such a trigger in the console.

trigger is click (the default), manual or hover.

manual opens only programmatically, through v-model:open: that is how a context menu and confirmations work, where the moment of opening is decided by the consumer.

hover opens on hovering with the openDelay and closeDelay delays. Both are needed, each for its own reason: without the first the panel jumps out on any crossing of the cursor, without the second it cannot be kept while moving from the trigger to the panel — there is an offsetPx gap between them. The panel listens for hovering as well, so a cursor that has moved onto it does not put the panel out.

A click in the hover mode keeps working. There is no hovering from the keyboard and from a touchscreen, and a panel opened by the cursor alone does not exist for them at all.

The wrapper around the #trigger slot is inline-block by default: it hugs the content, and the panel stands at the edge of the button itself rather than at the edge of the column. For a button that is right.

For a form control it is not. A control declares itself w-full, as GrInput and GrSelect do, but w-full resolves against the wrapper, and that has already hugged its content. The result: a control across the full width is drawn by its content, and next to an input field that reads as broken markup. A measurement: GrColorPicker in a GrFormField 384px wide was drawn at 113px.

The block prop stretches the wrapper to the full width of the parent:

<GrPopover block>

The name is the same as in GrButton and GrSegmented — in the core it is the settled word for “full width”. matchWidth takes the width from the wrapper precisely, so with block the panel will follow the width of the field rather than the width of the content of the trigger.

Two independent axes and one limit that is not configurable.

The ceiling of the content is the --gr-popover-max-width hook, 22rem by default. That is a readable width of a column of text, and for a form or a card it is right. For content wider than prose — a toolbar, a palette, a grid — the ceiling is removed:

<GrPopover content-class="[--gr-popover-max-width:100vw]">

With a hook rather than with a prop, deliberately: a value stays a value, it can be changed by breakpoint (md:[--gr-popover-max-width:100vw]) and by theme, and it does not argue by specificity with the class of the panel.

100vw rather than none: min(none, …) is invalid CSS, and writing it as 100vw also leaves the second limit in place.

Through contentClass rather than with an inline style. The panel is teleported into the portal (#gr-portal in body), so the wrapper of the trigger is not its ancestor: <GrPopover style="--gr-popover-max-width: 100vw"> will land on the wrapper, will not reach the panel and will silently do nothing. contentClass is the only path to the panel itself. Globally the hook works as usual: in a theme or on :root it is inherited into the portal together with everything else.

The width from the trigger is the matchWidth prop. true means exactly the width of the trigger, 'min' means no narrower than it and then by the content. A panel at a field or at a wide button that turns out narrower than its trigger reads as a layout error.

<GrPopover match-width>            <!-- exactly the width of the trigger -->
<GrPopover match-width="min">      <!-- no narrower than the trigger -->

The axes combine rather than argue, but they resolve differently, and that is a consequence of CSS rather than a decision of the component:

The second is not a flaw but the point of the mode: min means “no narrower than the trigger”, that is, a floor, and a floor is by definition above a ceiling. If a ceiling is exactly what is needed, take matchWidth without min.

That is why these are two independent levers rather than one enumeration: the combinations make sense and resolve predictably.

No wider than the viewport — not configurable. calc(100vw - 1rem) stands as the second operand of the min() and is switched off by nothing from the outside, including --gr-popover-max-width: 100vw: the positioning shifts the panel within the screen but does not narrow it, and without that limit a panel at the edge would move off it.

It is built like the width — a min() of a hook and a limit that is not configurable — but the second operand here is a measurement rather than a constant.

The ceiling of the content is the --gr-popover-max-height hook, 100vh by default, that is, there is no opinion. It is set when the panel is obliged to be lower than the available room:

<GrPopover content-class="[--gr-popover-max-height:20rem]">

Through contentClass and for the same reason as with the width: the panel is teleported, an inline style will land on the wrapper and will not reach it.

No taller than there is room — not configurable. The second operand is the --gr-floating-available-height variable, which the layer writes: the distance to the edge of the viewport on the side the panel ended up on. It is recomputed together with the position, on scrolling included, and is not switched off from the outside.

That quantity cannot be static, and therein lies the whole difference from the width: 100vw is known in advance, while how much room there is under the trigger depends on where the trigger stands. flip will turn the panel to the free side, shift will move it along the edge, but neither of them can shrink it: a panel taller than the viewport stays taller than the viewport after both, and its bottom goes off the screen with no way at all to reach it.

The panel scrolls. The ceiling arrives together with overflow-y: auto, because a ceiling without scrolling does not limit but crops. Until the ceiling is reached, there is no scrollbar — for short panels nothing changes.

That applies to everything standing on GrPopover as well: a long GrDropdown or GrContextMenu menu at the bottom edge of the screen now shrinks with a scroll rather than sliding off.