# Popover

A trigger button and native popover panel for menu-like floating content.

## Usage

Use standalone; the panel usually wraps `MenuList`.
```svelte
<Popover label="Menu" {...props}>
  <MenuList {...props} />
</Popover>
```

## Anatomy

The `class` attribute values represent part names. Other attributes represent their corresponding props. The panel usually wraps `MenuList`.

```svelte
<button class="label" popovertarget aria-haspopup aria-expanded aria-controls>
  {label}
</button>
<div class="whole" popover role style data-svs-placement>
  <div class="top" aria-hidden conditional: arrow, placement=bottom></div>
  <div class="left" aria-hidden conditional: arrow, placement=right></div>
  <div class="main">{children}</div>
  <div class="bottom" aria-hidden conditional: arrow, placement=top></div>
  <div class="right" aria-hidden conditional: arrow, placement=left></div>
</div>
```

Button trigger plus a `[popover]` panel, using the native Popover API and CSS Anchor Positioning only, with no JavaScript positioning fallback. `open` syncs both ways between programmatic state and native toggle events. `position`, `align`, `offset`, `matchWidth`, and `autoFlip` derive the native placement style; when `arrow` is enabled, a measurement effect reads the resolved trigger/panel rects on open, scroll, and resize so the rendered caret follows native flips and `data-svs-placement` exposes the resolved side, and `overflow: visible` is applied to the panel so the caret renders outside its box. `hover` adds pointer/focus opening only where the primary pointer can hover, otherwise it behaves like native click/focus opening. The component always provides `MenuContainerContext` so a nested `MenuList` can focus its first enabled item and close through the container. `manual` switches the panel to `popover="manual"` and disables native light-dismiss behavior.

## Props

| Name | Type | Default | Description |
|---|---|---|---|
| `label*` | `Snippet` | - | Trigger label; receives open state and variant as arguments |
| `children*` | `Snippet` | - | Panel content; receives the variant as its argument and usually renders a `MenuList` |
| `open` | `boolean` | `false` | Bindable open state; can be observed and controlled |
| `hover` | `boolean` | `false` | Opens on pointer enter and focus for hover-capable primary pointers |
| `position` | `Position` | `"bottom"` | Native anchor placement position |
| `align` | `Align` | `"start"` | Native anchor placement alignment |
| `offset` | `number` | `0` | Gap from the anchor edge in px |
| `autoFlip` | `boolean` | `true` | Enables native fallback placement |
| `matchWidth` | `boolean` | `false` | Sets panel min-width to the anchor width |
| `ariaRole` | `PopoverRole` | - | Sets the panel role, such as `menu`, `listbox`, or `dialog` |
| `manual` | `boolean` | `false` | Uses `popover="manual"` and disables native light-dismiss behavior |
| `arrow` | `boolean` | `false` | Renders the resolved placement caret part and sets `data-svs-placement`; also auto-applies `overflow: visible` to the panel so the caret can render outside |
| `attach` | `Attachment` | - | Svelte attachment on the trigger |
| `element` | `HTMLButtonElement` | - | Bindable trigger element |
| `styling` | `SVSClass` | - | Styling override |
| `variant` | `SVSVariant` | `NEUTRAL` | Popover variant |
`*` required. Other `HTMLButtonAttributes` are passed to the trigger `<button>` via rest props; `class` is merged onto the trigger.

## Styling

To learn more, see [Styling](/docs/styling).

### Variant Management

No automatic switching.

### Default Class Name

`svs-popover`

## Behavior

Button trigger plus a `[popover]` panel, using the native Popover API and CSS Anchor Positioning only, with no JavaScript positioning fallback. `open` syncs both ways between programmatic state and native toggle events. `position`, `align`, `offset`, `matchWidth`, and `autoFlip` derive the native placement style. When `arrow` is enabled, a measurement effect reads the resolved trigger/panel rects on open, scroll, and resize so the rendered caret follows native flips and `data-svs-placement` exposes the resolved side, and `overflow: visible` is applied to the panel so the caret renders outside its box. `hover` adds pointer/focus opening only where the primary pointer can hover, otherwise it behaves like native click/focus opening. The component always provides `MenuContainerContext` so a nested `MenuList` can focus its first enabled item and close through the container. `manual` switches the panel to `popover="manual"` and disables native light-dismiss behavior.

## Accessibility

### ARIA Roles and Attributes

The component applies these automatically:

- Trigger (`label` `<button>`): `aria-haspopup` from `ariaRole` or `"true"` when unset, `aria-expanded` from the open state, and `aria-controls` pointing to the panel.
- Panel (`whole` `<div>`): `role` from the `ariaRole` prop when supplied.
- Arrow caret (`top` / `bottom` / `left` / `right` `<div>`, when rendered): `aria-hidden="true"`.

Set `ariaRole` to match the panel content, such as `"menu"` when the panel hosts a `MenuList`. See [MenuList](/docs/menu-list) for the common menu panel case.

### Standards Basis

Popover is built on a native `<button>` trigger and the native Popover API, so keyboard and assistive-technology support follows the browser standard for button controls and popover dismissal. See the [Concepts standards-first guidance](/docs/concepts) for the library's approach.

## Exports

### Types

```ts
interface PopoverProps extends Omit<HTMLButtonAttributes, "children" | "style" | "popovertarget" | "popovertargetaction"> {
  label: string | Snippet<[boolean, string]>; // trigger; Snippet<[open, variant]>
  children: Snippet<[string]>; // panel content; Snippet<[variant]>; usually renders a MenuList
  open?: boolean; // bindable (false); observe + control
  hover?: boolean; // (false); open on pointerenter / focusin where the primary pointer can hover
  position?: Position; // ("bottom")
  align?: Align; // ("start")
  offset?: number; // (0); gap from the anchor edge, px
  autoFlip?: boolean; // (true); native fallback placement
  matchWidth?: boolean; // (false); panel min-width = anchor width
  ariaRole?: PopoverRole; // panel role
  manual?: boolean; // (false); popover="manual" disables light-dismiss
  arrow?: boolean; // (false); render the resolved placement caret part (`top`/`bottom`/`left`/`right`) and `data-svs-placement`
  attach?: Attachment<HTMLButtonElement>;
  element?: HTMLButtonElement; // bindable
  styling?: SVSClass;
  variant?: SVSVariant; // (VARIANT.NEUTRAL)
  // other HTMLButtonAttributes are passed to the trigger via ...rest; `class` is merged onto the trigger
  // style, popovertarget, and popovertargetaction are component-owned
}
type PopoverReqdProps = "label" | "children";
type PopoverBindProps = "open" | "element";
type Position = "top" | "right" | "bottom" | "left";
type Align = "start" | "center" | "end";
type PopoverRole = "menu" | "listbox" | "dialog";
```

### Others

No additional exports are available.

## Examples

The example code uses Tailwind CSS along with `SVSClass`.

### Basic

**Code**

```svelte src=PopoverBasic.svelte
<script lang="ts">
  import { MenuItem, MenuList, Popover } from "svseeds";

  const styling = {
    label: "px-3 py-1.5 rounded-md border bg-white text-sm font-medium shadow-sm cursor-pointer dark:bg-black",
    whole: "mt-2 rounded-md border bg-white p-1 shadow-lg dark:bg-black",
  };
  const childStyle1 = {
    whole: "flex min-w-40 flex-col gap-1",
  };
  const childStyle2 = {
    whole:
      "rounded-sm px-2 py-1 text-left text-sm hover:bg-gray-100 focus-visible:bg-gray-100 focus:outline-hidden dark:hover:bg-gray-800 dark:focus-visible:bg-gray-800",
  };
  const myProps = {
    label: "Menu",
    position: "bottom" as const,
    align: "start" as const,
    offset: 8,
    styling,
  };
</script>

<Popover {...myProps}>
  <MenuList styling={childStyle1}>
    <MenuItem styling={childStyle2}>Profile</MenuItem>
    <MenuItem styling={childStyle2}>Settings</MenuItem>
    <MenuItem styling={childStyle2}>Sign out</MenuItem>
  </MenuList>
</Popover>
```
### With Interactive Variant

**Code**

```svelte src=PopoverPract.svelte
<script lang="ts">
  import { MenuItem, MenuList, Popover } from "svseeds";

  let { variant = $bindable() } = $props();
  const variantStyle1 = {
    neutral: "border-gray-600 bg-white dark:bg-black",
    active: "border-teal-600 bg-teal-50 dark:bg-teal-950",
    inactive: "border-red-600 bg-red-50 dark:bg-red-950",
    blue: "border-blue-600 bg-blue-50 dark:bg-blue-950",
    yellow: "border-yellow-600 bg-yellow-50 dark:bg-yellow-950",
    sky: "border-sky-600 bg-sky-50 dark:bg-sky-950",
  };
  const variantStyle2 = {
    neutral: "border-gray-400",
    active: "border-teal-500",
    inactive: "border-red-500",
    blue: "border-blue-500",
    yellow: "border-yellow-500",
    sky: "border-sky-500",
  };
  const variantStyle3 = {
    neutral: "hover:bg-gray-100 focus-visible:bg-gray-100 dark:hover:bg-gray-800 dark:focus-visible:bg-gray-800",
    active: "hover:bg-teal-100 focus-visible:bg-teal-100 dark:hover:bg-teal-900 dark:focus-visible:bg-teal-900",
    inactive: "hover:bg-red-100 focus-visible:bg-red-100 dark:hover:bg-red-900 dark:focus-visible:bg-red-900",
    blue: "hover:bg-blue-100 focus-visible:bg-blue-100 dark:hover:bg-blue-900 dark:focus-visible:bg-blue-900",
    yellow: "hover:bg-yellow-100 focus-visible:bg-yellow-100 dark:hover:bg-yellow-900 dark:focus-visible:bg-yellow-900",
    sky: "hover:bg-sky-100 focus-visible:bg-sky-100 dark:hover:bg-sky-900 dark:focus-visible:bg-sky-900",
  };
  const styling = {
    whole: "mt-2",
    label: {
      base: "px-3 py-1.5 rounded-md border text-sm font-medium shadow-sm cursor-pointer",
      ...variantStyle1,
    },
    main: {
      base: "rounded-md border bg-white p-1 shadow-lg dark:bg-black",
      ...variantStyle2,
    },
    top: {
      base: "size-3 rotate-45 border-l border-t bg-white dark:bg-black",
      ...variantStyle2,
    },
    bottom: {
      base: "size-3 rotate-45 border-r border-b bg-white dark:bg-black",
      ...variantStyle2,
    },
    left: {
      base: "size-3 rotate-45 border-b border-l bg-white dark:bg-black",
      ...variantStyle2,
    },
    right: {
      base: "size-3 rotate-45 border-r border-t bg-white dark:bg-black",
      ...variantStyle2,
    },
  };
  const childStyle1 = {
    whole: "flex min-w-44 flex-col gap-1",
  };
  const childStyle2 = {
    whole: {
      base: "rounded-sm px-2 py-1 text-left text-sm focus:outline-hidden",
      ...variantStyle3,
    },
  };
  const myProps = {
    label: "Actions",
    position: "bottom" as const,
    align: "center" as const,
    offset: 8,
    arrow: true,
    styling,
  };
</script>

<Popover {variant} {...myProps}>
  <MenuList styling={childStyle1}>
    <MenuItem styling={childStyle2}>New file</MenuItem>
    <MenuItem styling={childStyle2}>Duplicate</MenuItem>
    <MenuItem styling={childStyle2}>Archive</MenuItem>
  </MenuList>
</Popover>
```