# Popover

Opens a non-modal popup anchored to a trigger.

[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Popover.tsx)

## Overview

Popover renders a non-modal dialog anchored to a trigger, opened on click, for interactive or longer content.

## Examples

### Basic

```tsx
import { Button, Popover, style } from '@tempoxyz/ds'

export function Demo() {
  return (
    <Popover.Root>
      <Popover.Trigger render={<Button variant="secondary" />}>Network fee</Popover.Trigger>
      <Popover.Popup>
        <Popover.Title>Network fee</Popover.Title>
        <Popover.Description>Paid in the token you send.</Popover.Description>
        <div {...styles.actions()}>
          <Popover.Close render={<Button size="small" variant="secondary" />}>Got it</Popover.Close>
        </div>
      </Popover.Popup>
    </Popover.Root>
  )
}

namespace styles {
  export const actions = style({ marginTop: '16' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Popover/Basic.tsx)

### Side

Set `side` on `Popover.Popup` to `top`, `right`, `bottom` (default), or `left`. Add `Popover.Arrow` to point toward the trigger.

```tsx
import { Button, Popover } from '@tempoxyz/ds'

export function Demo() {
  return (
    <Popover.Root>
      <Popover.Trigger render={<Button variant="secondary" />}>With arrow</Popover.Trigger>
      <Popover.Popup side="right">
        <Popover.Arrow />
        <Popover.Title>Estimated arrival</Popover.Title>
        <Popover.Description>About one minute.</Popover.Description>
      </Popover.Popup>
    </Popover.Root>
  )
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Popover/Side.tsx)

## Anatomy

Import the component and assemble its parts.

```tsx
import { Popover } from '@tempoxyz/ds'

<Popover.Root>
  <Popover.Trigger />
  <Popover.Popup>
    <Popover.Arrow />
    <Popover.Title />
    <Popover.Description />
    <Popover.Close />
  </Popover.Popup>
</Popover.Root>
```

## Guidelines

### When to Use

* Explain a value with a sentence and a link, such as the methodology behind a throughput tile.
* Show details on demand, such as the breakdown of a network fee.
* Edit one setting in place, such as the label of a saved address.

### When Not to Use

* Use a [Tooltip](/docs/components/tooltip) for a short label on an icon button.
* Use a [Menu](/docs/components/menu) for a list of actions.
* Use [Select](/docs/components/select), [Combobox](/docs/components/combobox), or [DatePicker](/docs/components/date-picker) to choose a value.
* Use a [Dialog](/docs/components/dialog) for a task with several fields or full attention.
* Use a [Drawer](/docs/components/drawer) for long content.
* Use visible text for information everyone needs, such as an error or a required step.

### Keep Content Small

A popover holds a title, a sentence or two, and at most two controls. `Popover.Popup` grows up to the available width, so give text popovers a `maxWidth`, such as 20rem.

**Do:** Explain a metric with a title, one sentence, and a link.

```tsx
/**
 * Do example for "Keep Content Small" on the Popover page.
 * Explain a metric with a title, one sentence, and a link.
 * @module
 */
import { Button, style } from '@tempoxyz/ds'
import { InfoCircle } from '@tempoxyz/ds/icons'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.stack()}>
      <div {...styles.header()}>
        <span {...styles.label()}>Throughput</span>
        <Button aria-label="About throughput" shape="icon" size="small" variant="tertiary">
          <InfoCircle />
        </Button>
      </div>
      <div {...styles.popup()}>
        <span {...styles.title()}>Throughput</span>
        <p {...styles.description()}>Transactions per second, averaged over each block.</p>
        <span {...styles.link()}>View methodology</span>
      </div>
    </div>
  )
}

namespace styles {
  export const description = style({
    color: 'content.secondary',
    margin: '0 !custom',
    typography: 'body.b2',
  })

  export const header = style({ alignItems: 'center', columnGap: '4', display: 'flex' })

  export const label = style({ color: 'content.primary', typography: 'body.b2Strong' })

  export const link = style({
    color: 'content.primary',
    textDecorationLine: 'underline !custom',
    typography: 'body.b2Strong',
  })

  export const popup = style({
    backgroundColor: 'background.elevated',
    borderRadius: 'sm',
    boxShadow: 'regular',
    boxSizing: 'border-box',
    display: 'flex',
    flexDirection: 'column',
    padding: '20',
    rowGap: '8',
    width: '15rem !custom',
  })

  export const stack = style({
    alignItems: 'flex-start',
    display: 'flex',
    flexDirection: 'column',
    rowGap: '8',
  })

  export const title = style({ color: 'content.primary', typography: 'body.b1Strong' })
}
```

**Don't:** Build a multi-field form in a popover. Use a [Dialog](/docs/components/dialog).

```tsx
/**
 * Don't example for "Keep Content Small" on the Popover page.
 * Don't build a multi-field form in a popover. Use a Dialog.
 * @module
 */
import { Button, style, TextInput } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.popup()}>
      <span {...styles.title()}>New webhook</span>
      <TextInput.Group>
        <TextInput.Control aria-label="Endpoint URL" placeholder="Endpoint URL" />
      </TextInput.Group>
      <TextInput.Group>
        <TextInput.Control aria-label="Events" placeholder="Events" />
      </TextInput.Group>
      <TextInput.Group>
        <TextInput.Control aria-label="Signing secret" placeholder="Signing secret" />
      </TextInput.Group>
      <div {...styles.actions()}>
        <Button size="small" variant="secondary">
          Cancel
        </Button>
        <Button size="small">Create webhook</Button>
      </div>
    </div>
  )
}

namespace styles {
  export const actions = style({
    columnGap: '8',
    display: 'flex',
    justifyContent: 'flex-end',
    marginTop: '4',
  })

  export const popup = style({
    backgroundColor: 'background.elevated',
    borderRadius: 'sm',
    boxShadow: 'regular',
    boxSizing: 'border-box',
    display: 'flex',
    flexDirection: 'column',
    padding: '20',
    rowGap: '8',
    width: '16rem !custom',
  })

  export const title = style({ color: 'content.primary', typography: 'body.b1Strong' })
}
```

### Add Hover Without Replacing Click

* **Click (default):** `Popover.Trigger` toggles on click, which covers a mouse, a tap, and Enter or Space.
* **Hover and Click (openOnHover):** For info icons on dashboards. Opens after 300ms of hover, and click still works.

### Offer a Close Action for Controls

Escape and an outside press close a popover. If it holds controls, add a `Popover.Close` button, such as Cancel or Done, for touch screens.

**Do:** Add a `Popover.Close` action beside the controls.

```tsx
/**
 * Do example for "Offer a Close Action for Controls" on the Popover page.
 * Add a `Popover.Close` action beside the controls.
 * @module
 */
import { Button, style, TextInput } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.popup()}>
      <span {...styles.title()}>Address label</span>
      <TextInput.Group>
        <TextInput.Control aria-label="Label" defaultValue="Alex, main wallet" />
      </TextInput.Group>
      <div {...styles.actions()}>
        <Button size="small" variant="secondary">
          Cancel
        </Button>
        <Button size="small">Save label</Button>
      </div>
    </div>
  )
}

namespace styles {
  export const actions = style({
    columnGap: '8',
    display: 'flex',
    justifyContent: 'flex-end',
    marginTop: '4',
  })

  export const popup = style({
    backgroundColor: 'background.elevated',
    borderRadius: 'sm',
    boxShadow: 'regular',
    boxSizing: 'border-box',
    display: 'flex',
    flexDirection: 'column',
    padding: '20',
    rowGap: '8',
    width: '16rem !custom',
  })

  export const title = style({ color: 'content.primary', typography: 'body.b1Strong' })
}
```

**Don't:** Rely on Escape or an outside press to leave a popover with controls.

```tsx
/**
 * Don't example for "Offer a Close Action for Controls" on the Popover page.
 * Don't rely on Escape or an outside press to leave a popover with controls.
 * @module
 */
import { style, TextInput } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.popup()}>
      <span {...styles.title()}>Address label</span>
      <TextInput.Group>
        <TextInput.Control aria-label="Label" defaultValue="Alex, main wallet" />
      </TextInput.Group>
    </div>
  )
}

namespace styles {
  export const popup = style({
    backgroundColor: 'background.elevated',
    borderRadius: 'sm',
    boxShadow: 'regular',
    boxSizing: 'border-box',
    display: 'flex',
    flexDirection: 'column',
    padding: '20',
    rowGap: '8',
    width: '16rem !custom',
  })

  export const title = style({ color: 'content.primary', typography: 'body.b1Strong' })
}
```

### Point at Small Triggers

`Popover.Popup` opens 8px from its trigger. If the trigger is small, such as an info icon in a table header, add `Popover.Arrow`.

**Do:** Add `Popover.Arrow` to point at a small trigger.

```tsx
/**
 * Do example for "Point at Small Triggers" on the Popover page.
 * Add `Popover.Arrow` to point at a small trigger.
 * @module
 */
import { Button, style } from '@tempoxyz/ds'
import { InfoCircle } from '@tempoxyz/ds/icons'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.stack()}>
      <div {...styles.header()}>
        <span {...styles.column()}>
          Fee
          <Button aria-label="About fee" shape="icon" size="small" variant="tertiary">
            <InfoCircle />
          </Button>
        </span>
        <span {...styles.column()}>
          Throughput
          <Button aria-label="About throughput" shape="icon" size="small" variant="tertiary">
            <InfoCircle />
          </Button>
        </span>
      </div>
      <div {...styles.popup()}>
        {/* Popover.Arrow needs an open popup, so this preview draws its shape in place. */}
        <svg
          aria-hidden="true"
          fill="currentColor"
          height="10"
          viewBox="0 0 20 10"
          width="20"
          {...styles.arrow()}
        >
          <path d="M0 10C4 10 7 7 8.6 4.6a2 2 0 0 1 2.8 0C13 7 16 10 20 10Z" />
        </svg>
        <p {...styles.description()}>Paid in the token you send, about 0.01 USDC.</p>
      </div>
    </div>
  )
}

namespace styles {
  export const arrow = style({
    color: 'background.elevated',
    left: '4.25rem !custom',
    position: 'absolute',
    top: '-10px !custom',
  })

  export const column = style({
    alignItems: 'center',
    color: 'content.secondary',
    columnGap: '2px !custom',
    display: 'flex',
    typography: 'body.b3',
  })

  export const description = style({
    color: 'content.secondary',
    margin: '0 !custom',
    typography: 'body.b2',
  })

  export const header = style({ columnGap: '24', display: 'flex', paddingInlineStart: '24' })

  export const popup = style({
    backgroundColor: 'background.elevated',
    borderRadius: 'sm',
    boxShadow: 'regular',
    boxSizing: 'border-box',
    padding: '16',
    position: 'relative',
    width: '15rem !custom',
  })

  export const stack = style({ display: 'flex', flexDirection: 'column', rowGap: '8' })
}
```

**Don't:** Leave the popup's trigger unclear among small icons.

```tsx
/**
 * Don't example for "Point at Small Triggers" on the Popover page.
 * Don't leave the popup's trigger unclear among small icons.
 * @module
 */
import { Button, style } from '@tempoxyz/ds'
import { InfoCircle } from '@tempoxyz/ds/icons'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.stack()}>
      <div {...styles.header()}>
        <span {...styles.column()}>
          Fee
          <Button aria-label="About fee" shape="icon" size="small" variant="tertiary">
            <InfoCircle />
          </Button>
        </span>
        <span {...styles.column()}>
          Throughput
          <Button aria-label="About throughput" shape="icon" size="small" variant="tertiary">
            <InfoCircle />
          </Button>
        </span>
      </div>
      <div {...styles.popup()}>
        <p {...styles.description()}>Paid in the token you send, about 0.01 USDC.</p>
      </div>
    </div>
  )
}

namespace styles {
  export const column = style({
    alignItems: 'center',
    color: 'content.secondary',
    columnGap: '2px !custom',
    display: 'flex',
    typography: 'body.b3',
  })

  export const description = style({
    color: 'content.secondary',
    margin: '0 !custom',
    typography: 'body.b2',
  })

  export const header = style({ columnGap: '24', display: 'flex', paddingInlineStart: '24' })

  export const popup = style({
    backgroundColor: 'background.elevated',
    borderRadius: 'sm',
    boxShadow: 'regular',
    boxSizing: 'border-box',
    padding: '16',
    width: '15rem !custom',
  })

  export const stack = style({ display: 'flex', flexDirection: 'column', rowGap: '8' })
}
```

## Content

### Title With the Subject

Name the value or setting, such as Network fee, with no question. Put the explanation in `Popover.Description`.

### Lead With the Answer

Start with the explanation, such as Transactions per second, averaged over each block. Keep it under about 25 words.

## Accessibility

### Semantics

* **Popover.Trigger (button):** Announces a dialog that click and keyboard open.
* **Popover.Popup (dialog):** A non-modal dialog, named by its title.
* **Popover.Title (h2):** Names the popup.
* **Popover.Description (p):** Describes the popup to screen readers.
* **Popover.Arrow (aria-hidden):** Decorative and hidden from assistive technology.

### Keyboard

* **Open and Activate (Enter or Space):** Opens the popover from the trigger, and activates the focused control in it.
* **Move Through the Popup (Tab):** Moves through the controls in the popup. Past the last control, the popover closes.
* **Return to the Trigger (Shift+Tab):** From the first control, moves focus back to the trigger.
* **Close the Popover (Escape):** Closes the popover.

### Focus

* **Opening (initialFocus):** Focus moves to the first control, or to the popup on touch. Pass `initialFocus` to change it.
* **Non-Modal (modal):** Focus is not trapped, and the page stays interactive unless you set `modal`.
* **Outside Press:** A press outside the popup closes it.
* **Closing (finalFocus):** Escape or an outside press returns focus to the trigger. If the trigger is gone, pass `finalFocus`.

### Your Responsibilities

* **Render Popover.Title:** Always render a title, so the dialog has an accessible name.
* **Name Icon-Only Triggers (aria-label):** Name the trigger's subject, such as "About throughput".

## Related

[Tooltip](/docs/components/tooltip)

Use for short labels on icon buttons.

[Dialog](/docs/components/dialog)

Use for focused tasks that block the page.

[Drawer](/docs/components/drawer)

Use for long content and bottom sheets.

[Menu](/docs/components/menu)

Use for lists of actions.

[Dashboards](/docs/patterns/dashboards)

Covers explaining metrics.
