Alternatives

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

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

<Popover
  triggerRenderer={({ triggerProps }) => (
    <ActionButton {...triggerProps} label="Click me" />
  )}
>
  <Box width={180} height={80} padding="medium">
    <Text>I'm in a popover!</Text>
  </Box>
</Popover>

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

Edit in Playroom

<Popover
  placement="right"
  triggerRenderer={({ triggerProps }) => (
    <ActionButton {...triggerProps} label="Click me" />
  )}
>
  <Box padding="medium">
    <Text>I'm in a popover!</Text>
  </Box>
</Popover>

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.

Edit in Playroom

<Popover
  triggerRenderer={({ triggerProps }) => (
    <IconButton
      {...triggerProps}
      variant="outline"
      label="Subtle"
      icon={ThumbsUpIcon}
    />
  )}
>
  <Box padding="medium">
    <Text>I'm in a popover!</Text>
  </Box>
</Popover>

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.

Edit in Playroom

<PopoverContent.Header>
  <Box flex="1">
    <Heading level="6">Title</Heading>
  </Box>
  <Inline>
    <Button label="Cancel" variant="text" onClick={() => alert('Cancel')} />
    <Button label="Primary Action" onClick={() => alert('Primary action')} />
  </Inline>
</PopoverContent.Header>

PopoverContent.Body

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

Edit in Playroom

<React.Fragment>
  <PopoverContent.Body>
    <Stack>
      <div>Vertical</div>
      <div>Content</div>
    </Stack>
  </PopoverContent.Body>
  <PopoverContent.Body>
    <Inline>
      <div>Horizontal</div>
      <div>Content</div>
    </Inline>
  </PopoverContent.Body>
</React.Fragment>

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.

Edit in Playroom

<PopoverContent.Footer gap="small">
  <Button
    label="Cancel"
    variant="text"
    onClick={() => alert('Cancel')}
    style={{ flex: 1 }}
  />
  <Button
    label="Primary Action"
    onClick={() => alert('Primary action')}
    style={{ flex: 1 }}
  />
</PopoverContent.Footer>

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.

Edit in Playroom

const { isOpen, setOpen, dialog, trigger } = usePopover({
  placement: 'bottom-start',
  modifiers: [
    {
      name: 'offset',
      options: {
        offset: [0, 8],
      },
    },
  ],
});
return (
  <div>
    <ActionButton
      onClick={() => setOpen(!isOpen)}
      ref={trigger.ref}
      label="Click me"
    />
    <PopoverDialog ref={dialog.ref} {...dialog.props} isVisible={isOpen}>
      <Box padding="medium">
        <Text>I'm in a PopoverDialog, using the usePopover hook!</Text>
      </Box>
    </PopoverDialog>
  </div>
);

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.

Edit in Playroom

const formSchema = field.object({
  firstName: field.text({
    validate: validate((value) => {
      validate.required(value);
      return;
    }),
  }),
  lastName: field.text({
    validate: validate((value) => {
      validate.required(value);
      return;
    }),
  }),
});
const form = useForm(formSchema);
const { isDirty } = useFormSnapshot(form);
const [discardDialogOpen, setDiscardDialogOpen] = React.useState(false);
const onClose = () => {
  if (isDirty) {
    setDiscardDialogOpen(true);
    return;
  }
  setOpen(false);
};
const { isOpen, setOpen, dialog, trigger } = usePopover(
  {},
  {
    onClose,
    closeWhen: ['clickoutside', 'escapepress'],
  }
);
const onSubmit = useSubmit(form, () => {
  setOpen(false);
});
return (
  <div>
    <ActionButton
      label="Fast add"
      ref={trigger.ref}
      onClick={() => setOpen((open) => !open)}
    />
    <PopoverDialog ref={dialog.ref} {...dialog.props} isVisible={isOpen}>
      <PopoverContent>
        <PopoverContent.Form onSubmit={onSubmit}>
          <Box width={480}>
            <PopoverContent.Header>
              <Box flex="1">
                <Heading level="6">Title</Heading>
              </Box>
              <Inline>
                <Button
                  label="Cancel"
                  variant="text"
                  size="small"
                  onClick={onClose}
                />
                <Button label="Submit" size="small" type="submit" />
              </Inline>
            </PopoverContent.Header>
            <PopoverContent.Body>
              <Stack gap="medium">
                <Field
                  label="First name"
                  invalidMessage={form.fields.firstName.props.invalidMessage}
                >
                  <TextInput {...form.fields.firstName.props} />
                </Field>
                <Field
                  label="Last name"
                  invalidMessage={form.fields.lastName.props.invalidMessage}
                >
                  <TextInput {...form.fields.lastName.props} />
                </Field>
              </Stack>
            </PopoverContent.Body>
          </Box>
        </PopoverContent.Form>
      </PopoverContent>
    </PopoverDialog>
    <AlertDialog
      isOpen={discardDialogOpen}
      title="Discard changes?"
      tone="critical"
      actions={{
        confirm: {
          label: 'Yes, discard',
          action: () => {
            setOpen(false);
            setDiscardDialogOpen(false);
          },
        },
        cancel: {
          label: 'Continue editing',
          action: () => setDiscardDialogOpen(false),
        },
      }}
    >
      <Text>Changes you've made so far will not be saved.</Text>
    </AlertDialog>
  </div>
);