---
title: Overlays and positioning
description: Compose Dialog and Popover with Base UI render semantics and the local AnchoredSurface.
order: 12
toc:
  - id: dialog
    title: Dialog
  - id: popover
    title: Popover
  - id: anchored-surface
    title: Continuous tail
  - id: positioning
    title: Custom positioning
  - id: choosing-an-overlay
    title: Choose an overlay
---

## Dialog {#dialog}

```tsx
import { Button } from "@workspace/ui/components/button"
import {
  Dialog,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@workspace/ui/components/dialog"

export function ProfileDialog() {
  return (
    <Dialog>
      <DialogTrigger render={<Button variant="outline" />}>
        Edit profile
      </DialogTrigger>
      <DialogContent>
        <DialogHeader>
          <DialogTitle>Edit profile</DialogTitle>
          <DialogDescription>Update your public information.</DialogDescription>
        </DialogHeader>
        <div>Form content</div>
        <DialogFooter>
          <Button type="submit">Save</Button>
        </DialogFooter>
      </DialogContent>
    </Dialog>
  )
}
```

`DialogContent` already includes the portal, overlay, and default close button. The title and description connect to the underlying accessibility attributes, so do not replace them with unstructured `div` elements.

## Popover {#popover}

```tsx
import { Button } from "@workspace/ui/components/button"
import {
  Popover,
  PopoverContent,
  PopoverDescription,
  PopoverTitle,
  PopoverTrigger,
} from "@workspace/ui/components/popover"

;<Popover>
  <PopoverTrigger render={<Button variant="outline" />}>
    Open settings
  </PopoverTrigger>
  <PopoverContent align="end">
    <PopoverTitle>Display settings</PopoverTitle>
    <PopoverDescription>Choose the list density.</PopoverDescription>
  </PopoverContent>
</Popover>
```

The local API continues to forward Base UI Popup and Positioner props. Pass `open` and `onOpenChange` to `Popover` when controlled state is required.

## Continuous tail {#anchored-surface}

The local `showArrow` is more than a triangular SVG. It renders `PopoverContent` through `AnchoredSurface`, producing one rounded surface with a continuous curved tail:

```tsx
<PopoverContent
  side="bottom"
  showArrow={{ cornerRadius: "2xl", tailSize: "sm" }}
  className="w-80 p-0"
  viewportClassName="max-h-72 p-4"
>
  {content}
</PopoverContent>
```

The outer surface remains `overflow: visible` so the tail is not clipped. Scrolling happens inside `data-slot="popover-viewport"`. Use `viewportClassName` when constraining content height or applying content padding.

`AnchoredSurface` can also render on its own, but it is visual only: it does not own anchor measurement, collision detection, focus, or a portal.

## Custom positioning {#positioning}

`PopoverContent` additionally exposes `anchor`, `positionMethod`, `arrowPadding`, `alignOffset`, and `sideOffset`. Pass virtual or custom anchors through the shared component instead of rebuilding the Base UI primitives.

For control outside React, create a handle with `createPopoverHandle<Payload>()` and connect it to the Root using Base UI's handle pattern.

## Choose an overlay {#choosing-an-overlay}

- Block background interaction with `Dialog` or `AlertDialog`.
- Use `Sheet` for a task surface entering from a screen edge and `Drawer` for a touch-oriented mobile panel.
- Use `Popover` for interactive content attached to a trigger.
- Use `HoverCard` for a preview revealed by hover or focus.
- Use `Tooltip` for short, non-interactive descriptions.

Compare basic usage with the [shadcn Popover documentation](https://ui.shadcn.com/docs/components/base/popover), but keep the Base UI `render` composition syntax.