Balance Logo
Balance
Reckon Design System
Open playroom

Popover

Popovers are small overlays that open on demand. They let users access additional content and actions without cluttering the page.
Install
pnpm add @balance-web/popover
Import usage
import {
usePopover,
Popover,
PopoverDialog,
PopoverContent,
Popper,
Manager,
Reference,
usePopper
} from '@balance-web/popover';
  • Code
  • API

Alternatives

  • Dropdown — For presenting a list of discrete actions to a user
  • SelectMenu — For presenting a list of selectable options to a user

Popover

Popovers are small overlays that open on demand, and close when the user clicks outside or presses the escape key. They let users access additional content and actions without cluttering the page.

The popover dialog has no dimensions of its own so it will expand or contract to contain the children provided. Consider this when using the popover, and be sure to provide appropriate styles for height and width.

If you need a list of actions use a <DropdownMenu/>. For searchable options or for use within a form, use a <Select/>

Edit in Playroom

Placement

The positioning of the popover, relative to the trigger, can be adjusted.

  • top
  • top-start
  • top-end
  • left
  • left-start
  • left-end
  • right
  • right-start
  • right-end
  • bottom
  • bottom-start
  • bottom-end

Trigger

Defines the appearance of the trigger button. Any component/element is fine as long as it accepts a ref and onClick, and the triggerProps are spread onto it.

Primitives

This package also exposes a set of primitives that can be used to compose popover content in a consistent manner.

PopoverContent

This component is the root of your content. All popover pimitives should be used inside it.

<PopoverContent>{/** popover primitives go here */}</PopoverContent>

PopoverContent.Header

This primitives provides padding for the header content and renders children as flex row.

PopoverContent.Body

This primitive provides padding for the main content of the popover. It does make any assumptions about the layout of the content.

PopoverContent.Form

If the popover contains a form, the entire popover must be wrapped in the Popover.Form component for the submit function to work correctly.

const submit = useSubmit(someForm)
<PopoverContent>
{/** Form submit function must be passed to the Form primitive. */}
<PopoverContent.Form onSubmit={submit}>
<PopoverContent.Header>
{/** Button type must be submit, don't set onClick handler or the form won't submit when the user presses enter. */}
<Button label="Submit" type="submit" />
</PopoverContent.Header>
<PopoverContent.Body></PopoverContent.Body>
</PopoverContent.Form>
</PopoverContent>

PopoverContent.Footer

This primitives provides padding for the footer content and renders children as flex row.

PopoverDialog and usePopover

The <Popover/> component is the easiest way to create a Popover, but if you need something more customised, you can do so by using the <PopoverDialog/> combined with the usePopover hook.

usePopover provides all of the neccesary logic for <PopoverDialog/>, but both can be used independently.

Recipes

Below are some examples of the type of content that can be composed using primitives.

Fast add

For popovers forms, it's recommended to use the PopoverDialog + usePopover combo as it gives more control over the popover behaviour to handle things like dirty form checks.

Copyright © 2024 Reckon. Designed and developed in partnership with Thinkmill.
Bitbucket logoJira software logoConfluence logo