Popover

Client componentEngine: react-aria

ImportCopy Anchor Link

import { Popover } from '@nizivo/react/popover';

// Once per app (Getting started), after
// @nizivo/tokens/tokens.css and @nizivo/react/css/base.css and @nizivo/react/css/icon-button.css
import '@nizivo/react/css/popover.css';

Static or interactiveCopy Anchor Link

Client. It always ships React Aria's dialog, popover and positioning code: @nizivo/react/popover measures 35.0 KiB gzip with React Aria inside (size-limit, all locales; packages/react/SIZES.md). Most of it is shared with Menu and Select, so a page that already has one of them pays far less. How to choose.

Popover, Menu, Tooltip or DialogCopy Anchor Link

• A Menu lists actions or links; a Select chooses a value. Use them when the popup is a list.
• A Tooltip names or explains its trigger in a few words and holds nothing to press.
• A Popover holds content and controls next to the control that opened it: a store's status with a "Pause" action, quick filters, a notifications list.
• A Dialog asks for the whole page's attention. Use it for a task the user must finish or dismiss before going on.

PlacementCopy Anchor Link

Popover.Popup takes side (top, bottom, start, end; default bottom), align (start, center, end; default center) and sideOffset (default 8 px). start and end follow the writing direction. When there is no room, it flips to the other side; data-side on the popup is the side it ended on, as a physical top, right, bottom or left, and data-align the alignment.

It is as wide as its content, up to 22.5rem (360 px) and the viewport less 32 px. Set --nz-popover-width for a fixed width. Its content scrolls when it is taller than the room below (or above) the trigger.

There is no arrow: Figma's popups (the Dropdown Menu and the Date Range Picker) have none.

Naming itCopy Anchor Link

A Popover.Title names the popover. Without one, give Popover.Popup an aria-label:

<Popover.Popup aria-label="Filters">…</Popover.Popup>

The close buttonCopy Anchor Link

<Popover.Close /> with no render and no children is a small IconButton (tertiary, sm) showing the close glyph, named "Close" (labels={{ close: '…' }} or aria-label renames it). As a direct child of Popover.Popup it sits in the top end corner, and the title leaves room for it. With children it is a plain button; with render, your element, for example render={<Button size="sm">Done</Button>}. Its markup is IconButton's, so a page that imports per-component stylesheets needs css/icon-button.css too.

Inside other overlaysCopy Anchor Link

A Popover opened inside a Dialog or a Drawer portals into that overlay and paints above it, and a Select, Menu, Tooltip or Dialog opened inside a Popover paints above the Popover. Escape and a press outside close only the topmost one; the page stays scroll-locked until the last one closes, and focus walks back trigger by trigger.

While it is open the rest of the page is inert and does not scroll (React Aria's popovers are modal), as with Menu and Select.

ExamplesCopy Anchor Link

import type { JSX } from 'react';
import { Button } from '@nizivo/react/button';
import { Popover } from '@nizivo/react/popover';

export function PopoverExample(): JSX.Element {
  return (
    <Popover.Root>
      <Popover.Trigger render={<Button variant="secondary">Store status</Button>} />
      <Popover.Popup>
        <Popover.Title level={3}>Store is live</Popover.Title>
        <Popover.Close />
        <Popover.Description>
          Customers can see 42 products. Pause the store to hide them while you restock.
        </Popover.Description>
        <Button size="sm">Pause store</Button>
      </Popover.Popup>
    </Popover.Root>
  );
}

import type { JSX } from 'react';
import { Button } from '@nizivo/react/button';
import { Popover } from '@nizivo/react/popover';

export function PopoverOpenExample(): JSX.Element {
  return (
    <Popover.Root defaultOpen>
      <Popover.Trigger render={<Button variant="secondary">Filters</Button>} />
      <Popover.Popup side="end" align="start" aria-label="Filters">
        <Popover.Description>No filters applied.</Popover.Description>
        <Popover.Close render={<Button size="sm">Done</Button>} />
      </Popover.Popup>
    </Popover.Root>
  );
}

Other exportsCopy Anchor Link

PopoverCloseProps type

import type { PopoverCloseProps } from '@nizivo/react/popover'

The props of Popover.Close, listed above.

PopoverCloseState type

import type { PopoverCloseState } from '@nizivo/react/popover'

The render state of Popover.Close, listed above.

PopoverDescriptionProps type

import type { PopoverDescriptionProps } from '@nizivo/react/popover'

The props of Popover.Description, listed above.

PopoverLabels type

import type { PopoverLabels } from '@nizivo/react/popover'

Strings the Popover renders (§9.3 rule 7, §16.4). close is the accessible name of the default Popover.Close (an IconButton showing the close glyph), set through that part's labels. Engine-owned with React Aria (not overridable): dismiss, the visually hidden "Dismiss" buttons at both ends of the popup.

Name	Type	Default	Description
closerequired	string	'Close'
dismissrequired	string	–

PopoverPopupProps type

import type { PopoverPopupProps } from '@nizivo/react/popover'

The props of Popover.Popup, listed above.

PopoverPopupState type

import type { PopoverPopupState } from '@nizivo/react/popover'

Name	Type	Default	Description
enteringrequired	boolean	–
exitingrequired	boolean	–
siderequired	Side "top" | "right" | "bottom" | "left"	–

PopoverRootProps type

import type { PopoverRootProps } from '@nizivo/react/popover'

The props of Popover.Root, listed above.

PopoverSide type

import type { PopoverSide } from '@nizivo/react/popover'

Logical side; the resolved physical side is data-side on the popup.

type PopoverSide = "top" | "bottom" | "start" | "end"

PopoverTitleLevel type

import type { PopoverTitleLevel } from '@nizivo/react/popover'

type PopoverTitleLevel = 2 | 3 | 4 | 5 | 6

PopoverTitleProps type

import type { PopoverTitleProps } from '@nizivo/react/popover'

The props of Popover.Title, listed above.

PopoverTriggerProps type

import type { PopoverTriggerProps } from '@nizivo/react/popover'

The props of Popover.Trigger, listed above.

PopoverTriggerState type

import type { PopoverTriggerState } from '@nizivo/react/popover'

The render state of Popover.Trigger, listed above.

Data attributes and slotsCopy Anchor Link

Style parts by class (.nz-<slot>) and state by data attribute. Attribute meanings come from contracts/vocabulary.json.

CSS hooksCopy Anchor Link

Set a hook on the component's class or any ancestor to restyle it without specificity games; leave it unset for the default shown.

Layers: nz.components. Classes: .nz-hit-target, .nz-icon-button, .nz-popover-close, .nz-popover-content, .nz-popover-description, .nz-popover-popup, .nz-popover-title, .nz-popover-trigger. Runtime variables: --nz-available-height, --nz-transform-origin.

AccessibilityCopy Anchor Link

These parts are interactive. Each gets the focus outline and touch-action rule from @nizivo/react/css/base.css (the nz.base layer), so the floor survives a restyle:

• popover-close: draws the focus outline itself on keyboard focus.
• popover-trigger: draws the focus outline itself on keyboard focus.

In forced-colours mode these states keep a visible system colour: popover-popup (border).

Behaviour comes from the react-aria engine through Nizivo's adapter: focus management, ARIA wiring and keyboard handling are the engine's.

Pattern: WAI-ARIA Authoring Practices.

KeyboardCopy Anchor Link

Source: react-aria-components 1.22.1 DialogTrigger, Popover and Dialog (react-aria 3.53.1 usePopover, which contains focus while open) through _engines/react-aria/popover.client.tsx. The first-control rule and focus return are Nizivo's (ARCHITECTURE.md §12.2), checked by the overlay lane (test/overlay/popover.spec.tsx, nesting-popover-drawer.spec.tsx) in Chromium, Firefox and WebKit; apps/docs/scripts/smoke.ts checks opening with Enter, Escape closing and focus back on the trigger.

FigmaCopy Anchor Link

Node ids from design/component-map.json, which nz gen writes from component.json. The links open the Nizivo Figma library, which may ask you to sign in.

• Canonical: none
• Ghost masters: none