Sajari UI

Popover is a non-modal dialog that floats around a trigger. It is used to display contextual information to the user, and should be paired with a clickable trigger element.

Import

Popover: The wrapper that provides props, state, and context to its children.
PopoverTrigger: Used to wrap the reference (or trigger) element.
PopoverContent: The popover itself.
PopoverHeader: The header of the popover.
PopoverBody: The body of the popover.
PopoverFooter: The footer of the popover.
PopoverArrow: A visual arrow that points to the reference (or trigger).
PopoverCloseButton: A button to close the popover.
PopoverAnchor: Used to wrap the position-reference element.

import {
  Popover,
  PopoverTrigger,
  PopoverContent,
  PopoverHeader,
  PopoverBody,
  PopoverFooter,
  PopoverArrow,
  PopoverCloseButton,
  PopoverAnchor,
} from '@sajari-ui/core';

import {
  Popover,
  PopoverTrigger,
  PopoverContent,
  PopoverHeader,
  PopoverBody,
  PopoverFooter,
  PopoverArrow,
  PopoverCloseButton,
  PopoverAnchor,
} from '@sajari-ui/core';

Basic Usage

When using this component, ensure the children passed to PopoverTrigger is focusable. Users can tab to it using their keyboard, and it can take a ref. It is critical for accessiblity.

A11y: When Popover opens, focus is sent to PopoverContent. When it closes, focus is returned to the trigger.

Editable Example

<Popover>
  <PopoverTrigger>
    <Button>Trigger</Button>
  </PopoverTrigger>
  <PopoverContent>
    <PopoverArrow />
    <PopoverCloseButton />
    <PopoverHeader>Confirmation!</PopoverHeader>
    <PopoverBody>Are you sure you want to have that milkshake?</PopoverBody>
  </PopoverContent>
</Popover>

<Popover>
  <PopoverTrigger>
    <Button>Trigger</Button>
  </PopoverTrigger>
  <PopoverContent>
    <PopoverArrow />
    <PopoverCloseButton />
    <PopoverHeader>Confirmation!</PopoverHeader>
    <PopoverBody>Are you sure you want to have that milkshake?</PopoverBody>
  </PopoverContent>
</Popover>

By default, the Popover doesn't render in a Portal. To make them display in a portal, wrap the PopoverContent in a Portal.

You might need to Inspect Element to see this in action. Notice that PopoverContent is rendered as a child of <body>.

Editable Example

<Popover>
  <PopoverTrigger>
    <Button>Trigger</Button>
  </PopoverTrigger>
  <Portal>
    <PopoverContent>
      <PopoverArrow />
      <PopoverHeader>Header</PopoverHeader>
      <PopoverCloseButton />
      <PopoverBody>
        <Button appearance="primary">Button</Button>
      </PopoverBody>
      <PopoverFooter>This is the footer</PopoverFooter>
    </PopoverContent>
  </Portal>
</Popover>

<Popover>
  <PopoverTrigger>
    <Button>Trigger</Button>
  </PopoverTrigger>
  <Portal>
    <PopoverContent>
      <PopoverArrow />
      <PopoverHeader>Header</PopoverHeader>
      <PopoverCloseButton />
      <PopoverBody>
        <Button appearance="primary">Button</Button>
      </PopoverBody>
      <PopoverFooter>This is the footer</PopoverFooter>
    </PopoverContent>
  </Portal>
</Popover>

By default, focus is to sent to PopoverContent when it opens. Pass the initialFocusRef prop to send focus to a specific element instead.

Editable Example

function WalkthroughPopover() {
  const initialFocusRef = React.useRef();

  return (
    <Popover initialFocusRef={initialFocusRef} closeOnBlur={false}>
      <PopoverTrigger>
        <Button>Trigger</Button>
      </PopoverTrigger>
      <PopoverContent textColor="text-white" backgroundColor="bg-blue-900" borderColor="border-blue-900">
        <PopoverHeader padding="p-4" fontWeight="font-bold" borderWidth="border-0">
          Manage Your Channels
        </PopoverHeader>
        <PopoverArrow />
        <PopoverCloseButton textColor="text-white" />
        <PopoverBody>
          Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et
          dolore.
        </PopoverBody>
        <PopoverFooter
          borderWidth="border-0"
          display="flex"
          alignItems="items-center"
          justifyContent="justify-between"
          padding="p-4"
        >
          <Box fontSize="text-sm">Step 2 of 4</Box>
          <ButtonGroup>
            <Button appearance="success" size="sm">
              Setup Email
            </Button>
            <Button appearance="primary" size="sm" ref={initialFocusRef}>
              Next
            </Button>
          </ButtonGroup>
        </PopoverFooter>
      </PopoverContent>
    </Popover>
  );
}

function WalkthroughPopover() {
  const initialFocusRef = React.useRef();
  return (
    <Popover initialFocusRef={initialFocusRef} closeOnBlur={false}>
      <PopoverTrigger>
        <Button>Trigger</Button>
      </PopoverTrigger>
      <PopoverContent textColor="text-white" backgroundColor="bg-blue-900" borderColor="border-blue-900">
        <PopoverHeader padding="p-4" fontWeight="font-bold" borderWidth="border-0">
          Manage Your Channels
        </PopoverHeader>
        <PopoverArrow />
        <PopoverCloseButton textColor="text-white" />
        <PopoverBody>
          Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et
          dolore.
        </PopoverBody>
        <PopoverFooter
          borderWidth="border-0"
          display="flex"
          alignItems="items-center"
          justifyContent="justify-between"
          padding="p-4"
        >
          <Box fontSize="text-sm">Step 2 of 4</Box>
          <ButtonGroup>
            <Button appearance="success" size="sm">
              Setup Email
            </Button>
            <Button appearance="primary" size="sm" ref={initialFocusRef}>
              Next
            </Button>
          </ButtonGroup>
        </PopoverFooter>
      </PopoverContent>
    </Popover>
  );
}

Controlled Usage

You can control the opening and closing of the popover by passing the open, and onClose props.

Sometimes you might need to set the returnFocusOnClose prop to false to prevent popver from returning focus to PopoverTrigger's children.

Editable Example

function ControlledUsage() {
  const [isOpen, setIsOpen] = React.useState(false);
  const open = () => setIsOpen(!isOpen);
  const close = () => setIsOpen(false);

  return (
    <>
      <Button margin="mr-5" onClick={open}>
        Trigger
      </Button>
      <Popover returnFocusOnClose={false} open={isOpen} onClose={close} closeOnBlur={false}>
        <PopoverTrigger>
          <Button appearance="danger">Popover Target</Button>
        </PopoverTrigger>
        <PopoverContent>
          <PopoverHeader fontWeight="font-semibold">Confirmation</PopoverHeader>
          <PopoverArrow />
          <PopoverCloseButton />
          <PopoverBody>Are you sure you want to continue with your action?</PopoverBody>
          <PopoverFooter display="flex" justifyContent="justify-end">
            <ButtonGroup>
              <Button size="sm">Cancel</Button>
              <Button appearance="primary" size="sm">
                Apply
              </Button>
            </ButtonGroup>
          </PopoverFooter>
        </PopoverContent>
      </Popover>
    </>
  );
}

function ControlledUsage() {
  const [isOpen, setIsOpen] = React.useState(false);
  const open = () => setIsOpen(!isOpen);
  const close = () => setIsOpen(false);
  return (
    <>
      <Button margin="mr-5" onClick={open}>
        Trigger
      </Button>
      <Popover returnFocusOnClose={false} open={isOpen} onClose={close} closeOnBlur={false}>
        <PopoverTrigger>
          <Button appearance="danger">Popover Target</Button>
        </PopoverTrigger>
        <PopoverContent>
          <PopoverHeader fontWeight="font-semibold">Confirmation</PopoverHeader>
          <PopoverArrow />
          <PopoverCloseButton />
          <PopoverBody>Are you sure you want to continue with your action?</PopoverBody>
          <PopoverFooter display="flex" justifyContent="justify-end">
            <ButtonGroup>
              <Button size="sm">Cancel</Button>
              <Button appearance="primary" size="sm">
                Apply
              </Button>
            </ButtonGroup>
          </PopoverFooter>
        </PopoverContent>
      </Popover>
    </>
  );
}

Popover Anchor

You can wrap your component with PopoverAnchor to prevent trigger any action. The wrapped component will become a position reference. Actions will only be triggerred by components inside PopoverTrigger.

In this case, you can only open and close the popover with Button. If you click on Input, it acts same as the original input and doesn't trigger any action about popover.

Editable Example

function WithPopoverAnchor() {
  const [isEditing, setIsEditing] = React.useState(false);
  const [color, setColor] = React.useState('text-black');

  return (
    <Popover
      open={isEditing}
      onOpen={() => setIsEditing(!isEditing)}
      onClose={() => setIsEditing(false)}
      closeOnBlur={false}
      isLazy
      lazyBehavior="keepMounted"
    >
      <PopoverAnchor>
        <TextInput
          textColor={color}
          width="w-auto"
          display="inline-flex"
          disabled={!isEditing}
          defaultValue="Popover Anchor"
        />
      </PopoverAnchor>

      <PopoverTrigger>
        <Button appearance="warning" margin="ml-5">
          {isEditing ? 'Save' : 'Edit'}
        </Button>
      </PopoverTrigger>

      <PopoverContent>
        <PopoverBody>
          Colors:
          <RadioGroup onChange={(e) => setColor(e.target.value)} value={color}>
            <Radio value="text-black">black</Radio>
            <Radio value="text-red-500">red</Radio>
            <Radio value="text-blue-500">blue</Radio>
          </RadioGroup>
        </PopoverBody>
      </PopoverContent>
    </Popover>
  );
}

function WithPopoverAnchor() {
  const [isEditing, setIsEditing] = React.useState(false);
  const [color, setColor] = React.useState('text-black');
  return (
    <Popover
      open={isEditing}
      onOpen={() => setIsEditing(!isEditing)}
      onClose={() => setIsEditing(false)}
      closeOnBlur={false}
      isLazy
      lazyBehavior="keepMounted"
    >
      <PopoverAnchor>
        <TextInput
          textColor={color}
          width="w-auto"
          display="inline-flex"
          disabled={!isEditing}
          defaultValue="Popover Anchor"
        />
      </PopoverAnchor>
      <PopoverTrigger>
        <Button appearance="warning" margin="ml-5">
          {isEditing ? 'Save' : 'Edit'}
        </Button>
      </PopoverTrigger>
      <PopoverContent>
        <PopoverBody>
          Colors:
          <RadioGroup onChange={(e) => setColor(e.target.value)} value={color}>
            <Radio value="text-black">black</Radio>
            <Radio value="text-red-500">red</Radio>
            <Radio value="text-blue-500">blue</Radio>
          </RadioGroup>
        </PopoverBody>
      </PopoverContent>
    </Popover>
  );
}

Accessing Internal state

Popover provides access to two internal details: open and onClose. Use the render prop pattern to gain access to them.

Editable Example

function InternalStateEx() {
  const initRef = React.useRef();

  return (
    <Popover closeOnBlur={false} initialFocusRef={initRef}>
      {({ open, onClose }) => (
        <>
          <PopoverTrigger>
            <Button>Click to {open ? 'close' : 'open'}</Button>
          </PopoverTrigger>
          <Portal>
            <PopoverContent>
              <PopoverHeader>This is the header</PopoverHeader>
              <PopoverCloseButton />
              <PopoverBody>
                <Box>Hello. Nice to meet you! This is the body of the popover</Box>
                <Button margin="mt-4" appearance="primary" onClick={onClose} ref={initRef}>
                  Close
                </Button>
              </PopoverBody>
              <PopoverFooter>This is the footer</PopoverFooter>
            </PopoverContent>
          </Portal>
        </>
      )}
    </Popover>
  );
}

function InternalStateEx() {
  const initRef = React.useRef();
  return (
    <Popover closeOnBlur={false} initialFocusRef={initRef}>
      {({ open, onClose }) => (
        <>
          <PopoverTrigger>
            <Button>Click to {open ? 'close' : 'open'}</Button>
          </PopoverTrigger>
          <Portal>
            <PopoverContent>
              <PopoverHeader>This is the header</PopoverHeader>
              <PopoverCloseButton />
              <PopoverBody>
                <Box>Hello. Nice to meet you! This is the body of the popover</Box>
                <Button margin="mt-4" appearance="primary" onClick={onClose} ref={initRef}>
                  Close
                </Button>
              </PopoverBody>
              <PopoverFooter>This is the footer</PopoverFooter>
            </PopoverContent>
          </Portal>
        </>
      )}
    </Popover>
  );
}

You can change the background, arrow size, box shadow and so on.

Editable Example

<Popover>
  <PopoverTrigger>
    <Button>Click</Button>
  </PopoverTrigger>
  <PopoverContent backgroundColor="bg-orange-500" textColor="text-white">
    <PopoverHeader fontWeight="font-semibold">Customization</PopoverHeader>
    <PopoverArrow backgroundColor="bg-red-500" />
    <PopoverCloseButton backgroundColor="bg-purple-500" textColor="text-white" />
    <PopoverBody>
      Tadaa!! The arrow color and background color is customized. Check the props for each component.
    </PopoverBody>
  </PopoverContent>
</Popover>

<Popover>
  <PopoverTrigger>
    <Button>Click</Button>
  </PopoverTrigger>
  <PopoverContent backgroundColor="bg-orange-500" textColor="text-white">
    <PopoverHeader fontWeight="font-semibold">Customization</PopoverHeader>
    <PopoverArrow backgroundColor="bg-red-500" />
    <PopoverCloseButton backgroundColor="bg-purple-500" textColor="text-white" />
    <PopoverBody>
      Tadaa!! The arrow color and background color is customized. Check the props for each component.
    </PopoverBody>
  </PopoverContent>
</Popover>

Since popover is powered by PopperJS, you can change the placement of the popover by passing the placement prop. See the props for the possible placement values.

Even though you specified the placement, Popover will try to reposition itself in the event that available space at the specified placement isn't enough.

Editable Example

<Popover placement="top-start">
  <PopoverTrigger>
    <Button>Click me</Button>
  </PopoverTrigger>
  <PopoverContent>
    <PopoverHeader fontWeight="font-semibold">Popover placement</PopoverHeader>
    <PopoverArrow />
    <PopoverCloseButton />
    <PopoverBody>
      Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore.
    </PopoverBody>
  </PopoverContent>
</Popover>

<Popover placement="top-start">
  <PopoverTrigger>
    <Button>Click me</Button>
  </PopoverTrigger>
  <PopoverContent>
    <PopoverHeader fontWeight="font-semibold">Popover placement</PopoverHeader>
    <PopoverArrow />
    <PopoverCloseButton />
    <PopoverBody>
      Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore.
    </PopoverBody>
  </PopoverContent>
</Popover>

By default, the Popover component renders children of PopoverContent to the DOM, meaning that invisible popover contents are still rendered but are hidden by styles.

If you want to defer rendering of popover content until that Popover is opened, you can use the isLazy prop. This is useful if your PopoverContent needs to be extra performant, or make network calls on mount that should only happen when the component is displayed.

Editable Example

<Popover isLazy>
  <PopoverTrigger>
    <Button>Click me</Button>
  </PopoverTrigger>
  <PopoverContent>
    <PopoverHeader fontWeight="font-semibold">Popover placement</PopoverHeader>
    <PopoverArrow />
    <PopoverCloseButton />
    <PopoverBody>
      Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore.
    </PopoverBody>
  </PopoverContent>
</Popover>

<Popover isLazy>
  <PopoverTrigger>
    <Button>Click me</Button>
  </PopoverTrigger>
  <PopoverContent>
    <PopoverHeader fontWeight="font-semibold">Popover placement</PopoverHeader>
    <PopoverArrow />
    <PopoverCloseButton />
    <PopoverBody>
      Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore.
    </PopoverBody>
  </PopoverContent>
</Popover>

Accessiblity

When you see the word "trigger", it is referring to the children of PopoverTrigger

Keyboard and Focus

When the popover is opened, focus is moved to the PopoverContent. If the initialFocusRef is set, then focus moves to the element with that ref.
When the popover is closed, focus returns to the trigger. If you set returnFocusOnClose to false, focus will not return.
If trigger is set to hover:
- Focusing on or mousing over the trigger will open the popover.
- Blurring or mousing out of the trigger will close the popover. If you move your mouse into the PopoverContent, it'll remain visible.
If trigger is set to click:
- Clicking the trigger or using the Space or Enter when focus is on the trigger will open the popover.
- Clicking the trigger again will close the popover.
Hitting the Esc key while the popover is open and focus is within the PopoverContent, will close the popover. If you set closeOnEsc to false, it will not close.
Clicking outside or blurring out of the PopoverContent closes the popover. If you set closeOnBlur to false, it will not close.

ARIA Attributes

If the trigger is set to click, the PopoverContent element has role set to dialog. If the trigger is set to hover, the PopoverContent has role set to tooltip.
The PopoverContent has aria-labelledby set to the id of the PopoverHeader.
The PopoverContent has aria-describedby set to the id of the PopoverBody.
The PopoverContent has aria-hidden set to true or false depending on the open/closed state of the popover.
The trigger has aria-haspopup set to true to denote that it triggers a popover.
The trigger has aria-controls set to the id of the PopoverContent to associate the popover and the trigger.
The trigger has aria-expanded set to true or false depending on the open/closed state of the popover.

Props

Name	Type	Default	Description
arrowPadding	`number`	`8`	The padding required to prevent the arrow from reaching the very edge of the popper
arrowShadowColor	`string`		The `box-shadow` of the popover arrow
arrowSize	`number`		The size of the popover arrow
autoFocus	`boolean`		If `true`, focus will be transferred to the first interactive element when the popover opens
boundary	`HTMLElement`, `"clippingParents"`, `"scrollParent"`	`"clippingParents"`	The boundary area for the popper. Used within the `preventOverflow` modifier
children	`React.ReactNode`		The content of the popover. It is usually the `PopoverTrigger`, and `PopoverContent`
closeDelay	`number`
closeOnBlur	`boolean`		If `true`, the popover will close when you blur out it by clicking outside or tabbing out
closeOnEsc	`boolean`		If `true`, the popover will close when you hit the `Esc` key
computePositionOnMount	`boolean`		If `true`, the popover will be positioned when it mounts (even if it's not open) Note 🚨: We don't recommend using this in a popover/menu intensive UI or page as it might affect scrolling performance.
defaultIsOpen	`boolean`		If `true`, the popover will be initially opened
direction	`"ltr"`, `"rtl"`	`"ltr"`	Theme direction `ltr` or `rtl`. Popper's placement will be set accordingly
enabled	`boolean`		Whether the popper.js should be enabled
eventListeners	`boolean`, `{ scroll?: boolean; resize?: boolean; }`, `undefined`		If provided, determines whether the popper will reposition itself on `scroll` and `resize` of the window
flip	`boolean`	`true`	If `true`, the popper will change its placement and flip when it's about to overflow its boundary area
gutter	`number`	`8`	The distance or margin between the reference and popper. It is used internally to create an `offset` modifier. NB: If you define `offset` prop, it'll override the gutter.
id	`string`		The html `id` attribute of the popover. If not provided, we generate a unique id. This `id` is also used to auto-generate the `aria-labelledby` and `aria-decribedby` attributes that points to the `PopoverHeader` and `PopoverBody`
initialFocusRef	`RefObject<FocusableElement>`		The `ref` of the element that should receive focus when the popover opens
isLazy	`boolean`		Performance 🚀: If `true`, the `PopoverContent` rendering will be deferred until the popover is open
open	`boolean`		If `true`, the popover will be opened in controlled mode
lazyBehavior	`LazyBehavior`	`"unmount"`	Performance 🚀: The lazy behavior of popover's content when not visible. Only works when `isLazy={true}` - "unmount": The popover's content is always unmounted when not open. - "keepMounted": The popover's content initially unmounted, but stays mounted when popover is open.
matchWidth	`boolean`		If `true`, the popper will match the width of the reference at all times. It's useful for `autocomplete`, `date-picker` and `select` patterns.
offset	`[number, number]`		The main and cross-axis offset to displace popper element from its reference element
onClose	`(() => void)`		Callback fired when the popover closes
onOpen	`(() => void)`		Callback fired when the popover opens
openDelay	`number`
placement	`PlacementWithLogical`	`"bottom"`	The placement of the popper relative to its reference
preventOverflow	`boolean`	`true`	If `true`, will prevent the popper from being cut off and ensure it's visible within the boundary area
returnFocusOnClose	`boolean`		If `true`, focus will be returned to the element that triggers the popover when it closes
strategy	`"fixed"`, `"absolute"`	`"absolute"`	The CSS positioning strategy to use
trigger	`"click"`, `"hover"`	The interaction that triggers the popover. `hover` - means the popover will open when you hover with mouse or focus with keyboard on the popover trigger `click` - means the popover will open on click or press `Enter` to `Space` on keyboard

Other Props

PopoverContent composes Box and has the ability to smartly position itself. Thanks to popper.js.
PopoverArrow, PopoverHeader, PopoverFooter and PopoverBody composes Box.
PopoverCloseButton composes Button component.

Popover

Import

Basic Usage

Editable Example

Rendering the Popover in a Portal

Editable Example

Focus an element when Popover opens

Editable Example

Controlled Usage

Editable Example

Popover Anchor

Editable Example

Accessing Internal state

Editable Example

Customizing the Popover

Editable Example

Popover Placements

Editable Example

Lazily mounting Popover

Editable Example

Accessiblity

Keyboard and Focus

ARIA Attributes

Props

Popover Props

Other Props