Popover

Popover is the primitive for a non-blocking surface that floats next to the element that opened it: hover cards, inline editors, detail panels, and small forms. It coordinates open state, positioning, dismissal, and exit motion so your component only has to render the floating frame and its contents.

Reach for Popover when a surface should anchor to a trigger (or a separate anchor), position itself with the popper foundation, and dismiss predictably — by an explicit close, an outside interaction, or a controlled state change. Unlike Dialog, Popover is non-modal by default, so the rest of the UI stays interactive while it is open.

Import

import { Popover } from "@lattice-ui/popover";

Anatomy

Compose the parts you need. Root, Portal, and Content form the minimum useful surface; Trigger, Anchor, and Close are optional depending on how you drive and position the popover.

<Popover.Root>
  <Popover.Trigger />
  <Popover.Anchor />
  <Popover.Portal>
    <Popover.Content>
      <Popover.Close />
    </Popover.Content>
  </Popover.Portal>
</Popover.Root>

Example

A controlled popover anchored to its trigger, positioned to the right, with an app-owned frame inside the content.

import { useState } from "@rbxts/react";
import { Popover } from "@lattice-ui/popover";

export function ProfileCardPopover() {
  const [open, setOpen] = useState(false);

  return (
    <Popover.Root open={open} onOpenChange={setOpen}>
      <Popover.Trigger asChild>
        <textbutton Text="View profile" Size={UDim2.fromOffset(140, 38)} />
      </Popover.Trigger>

      <Popover.Portal>
        <Popover.Content placement="right" sideOffset={8} collisionPadding={12}>
          <frame
            BackgroundColor3={Color3.fromRGB(24, 26, 32)}
            Size={UDim2.fromOffset(260, 140)}
          >
            <uilistlayout Padding={new UDim(0, 8)} />
            <textlabel
              BackgroundTransparency={1}
              Size={UDim2.fromOffset(240, 28)}
              Text="Astra"
              TextColor3={Color3.fromRGB(240, 244, 250)}
            />
            <textlabel
              BackgroundTransparency={1}
              Size={UDim2.fromOffset(240, 24)}
              Text="Level 42 builder"
              TextColor3={Color3.fromRGB(176, 184, 198)}
            />
            <Popover.Close asChild>
              <textbutton Text="Close" Size={UDim2.fromOffset(100, 34)} />
            </Popover.Close>
          </frame>
        </Popover.Content>
      </Popover.Portal>
    </Popover.Root>
  );
}

How it behaves

Open state

Popover.Root is controllable. Pass open and onOpenChange to control it, or defaultOpen to run uncontrolled (defaults to closed). Popover.Trigger toggles the open state on activation and Popover.Close closes it; both go through the same state, so controlled and uncontrolled usage behave identically.

Positioning

Popover.Content is positioned by the popper foundation. It measures the anchor and the content, then resolves a final placement and flips to the opposite side when the requested side would collide with the screen edge. Tune it with placement ("top" | "bottom" | "left" | "right", default "bottom"), sideOffset (gap from the anchor, default 0), alignOffset (shift along the anchor’s cross axis, default 0), and collisionPadding (minimum distance from the screen edge, default 8).

By default the content anchors to the trigger. Add a Popover.Anchor to position against a different element — for example, anchoring a popover to a row while the trigger sits elsewhere. The anchor takes precedence over the trigger when both are present.

Focus and selection

Popover.Content mounts a focus scope tied to the open state. Because Popover is non-modal by default, the scope is not trapped — gamepad and GuiObject selection can move freely between the popover and the rest of the screen. Focus is restored to the previously selected object when the popover closes, and the trigger is the natural restore target. Setting modal on the Root switches the scope to trapped so selection stays inside the surface while it is open.

Dismissal

Popover.Content participates in dismissable-layer behavior. An outside press dismisses it, and when modal is true, interaction behind the surface is also blocked. Use onPointerDownOutside and onInteractOutside to observe or veto those interactions before the popover closes.

Motion and presence

Popover.Content runs a default popper-aware reveal/exit recipe that animates from the resolved placement, so it animates in and out without extra setup. The default surface uses a canvas-group recipe; with asChild it uses a transform recipe applied to your element. Override either with transition, and pass forceMount to keep the content mounted through its exit animation (useful when you drive motion yourself or need the node to persist).

API reference

Popover.Root

Popover.Trigger

Popover.Anchor

Popover.Portal

Popover.Content

Popover.Close

Related

• Positioning with popper
• Portals and layers
• Focus management
• Presence and motion
• asChild composition