Popover

Popover

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.

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.

Building your own positioned element

This package also exposes usePopper and createMeasurablePopper — the building blocks Popover itself is built on, re-exported alongside everything from react-popper (its own usePopper is deliberately shadowed). Every Balance popper — including Combobox and SelectMenu's menu positioning — is created through createMeasurablePopper rather than react-popper's own hook directly, because it guards a deferred reposition against a document that's gone away (e.g. the trigger unmounted mid-flight). Reach for usePopper directly only if you're building a new floating/positioned component that doesn't fit Popover's trigger/content model.

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.