Chakra UI

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

Popover is built on top of the Popper.js library, and composes the Popper component.

Import#

Popover: The wrapper that provides props, state, and context to it's 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.
PopoverArrow: A visual arrow that points to the reference (or trigger).
PopoverCloseButton: Obviously, a button to close the popover.

import {
  Popover,
  PopoverTrigger,
  PopoverContent,
  PopoverHeader,
  PopoverBody,
  PopoverFooter,
  PopoverArrow,
  PopoverCloseButton,
} from "@chakra-ui/core";

import {
  Popover,
  PopoverTrigger,
  PopoverContent,
  PopoverHeader,
  PopoverBody,
  PopoverFooter,
  PopoverArrow,
  PopoverCloseButton,
} from "@chakra-ui/core";

Basic Usage#

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

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

<Popover>
  <PopoverTrigger>
    <Button>Trigger</Button>
  </PopoverTrigger>
  <PopoverContent zIndex={4}>
    <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 zIndex={4}>
    <PopoverArrow />
    <PopoverCloseButton />
    <PopoverHeader>Confirmation!</PopoverHeader>
    <PopoverBody>Are you sure you want to have that milkshake?</PopoverBody>
  </PopoverContent>
</Popover>

Editable Example

By default, the Popover doesn't render in a Portal. To make them display in a portal, pass the usePortal prop.

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

<Popover usePortal>
  <PopoverTrigger>
    <Button>Trigger</Button>
  </PopoverTrigger>
  <PopoverContent zIndex={4}>
    <PopoverArrow />
    <PopoverHeader>Header</PopoverHeader>
    <PopoverCloseButton />
    <PopoverBody>
      <Button variantColor="blue">Button</Button>
    </PopoverBody>
    <PopoverFooter>This is the footer</PopoverFooter>
  </PopoverContent>
</Popover>

<Popover usePortal>
  <PopoverTrigger>
    <Button>Trigger</Button>
  </PopoverTrigger>
  <PopoverContent zIndex={4}>
    <PopoverArrow />
    <PopoverHeader>Header</PopoverHeader>
    <PopoverCloseButton />
    <PopoverBody>
      <Button variantColor="blue">Button</Button>
    </PopoverBody>
    <PopoverFooter>This is the footer</PopoverFooter>
  </PopoverContent>
</Popover>

Editable Example

By default, focus is to sent to the PopoverContent when it opens, you might want to send focus to a specific element when it opens. Pass the initialFocusRef prop to do so.

function WalkthroughPopover() {
  const initialFocusRef = React.useRef();
  return (
    <Popover
      initialFocusRef={initialFocusRef}
      placement="bottom"
      closeOnBlur={false}
    >
      <PopoverTrigger>
        <Button>Trigger</Button>
      </PopoverTrigger>
      <PopoverContent
        zIndex={4}
        color="white"
        bg="blue.800"
        borderColor="blue.800"
      >
        <PopoverHeader pt={4} fontWeight="bold" border="0">
          Manage Your Channels
        </PopoverHeader>
        <PopoverArrow />
        <PopoverCloseButton />
        <PopoverBody>
          Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do
          eiusmod tempor incididunt ut labore et dolore.
        </PopoverBody>
        <PopoverFooter
          border="0"
          d="flex"
          alignItems="center"
          justifyContent="space-between"
          pb={4}
        >
          <Box fontSize="sm">Step 2 of 4</Box>
          <ButtonGroup size="sm">
            <Button variantColor="green">Setup Email</Button>
            <Button variantColor="blue" ref={initialFocusRef}>
              Next
            </Button>
          </ButtonGroup>
        </PopoverFooter>
      </PopoverContent>
    </Popover>
  );
}

function WalkthroughPopover() {
  const initialFocusRef = React.useRef();
  return (
    <Popover
      initialFocusRef={initialFocusRef}
      placement="bottom"
      closeOnBlur={false}
    >
      <PopoverTrigger>
        <Button>Trigger</Button>
      </PopoverTrigger>
      <PopoverContent
        zIndex={4}
        color="white"
        bg="blue.800"
        borderColor="blue.800"
      >
        <PopoverHeader pt={4} fontWeight="bold" border="0">
          Manage Your Channels
        </PopoverHeader>
        <PopoverArrow />
        <PopoverCloseButton />
        <PopoverBody>
          Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do
          eiusmod tempor incididunt ut labore et dolore.
        </PopoverBody>
        <PopoverFooter
          border="0"
          d="flex"
          alignItems="center"
          justifyContent="space-between"
          pb={4}
        >
          <Box fontSize="sm">Step 2 of 4</Box>
          <ButtonGroup size="sm">
            <Button variantColor="green">Setup Email</Button>
            <Button variantColor="blue" ref={initialFocusRef}>
              Next
            </Button>
          </ButtonGroup>
        </PopoverFooter>
      </PopoverContent>
    </Popover>
  );
}

Editable Example

If the popover contains a form, you might need to trap focus within the popover and close it when the users fills the form and hit "save".

You can leverage react-focus-lock to trap focus within the PopoverContent.

John Smith

// import  FocusLock from "react-focus-lock"

// 1. Create a text input component
const TextInput = React.forwardRef((props, ref) => {
  return (
    <FormControl>
      <FormLabel htmlFor={props.id}>{props.label}</FormLabel>
      <Input ref={ref} id={props.id} {...props} />
    </FormControl>
  );
});

// 2. Create the form
const Form = ({ firstFieldRef, onCancel }) => {
  return (
    <Stack spacing={4}>
      <TextInput
        label="First name"
        id="first-name"
        ref={firstFieldRef}
        defaultValue="John"
      />
      <TextInput label="Last name" id="last-name" defaultValue="Smith" />
      <ButtonGroup d="flex" justifyContent="flex-end">
        <Button variant="outline" onClick={onCancel}>
          Cancel
        </Button>
        <Button isDisabled variantColor="teal">
          Save
        </Button>
      </ButtonGroup>
    </Stack>
  );
};

// 3. Create the Popover
// Ensure you set `closeOnBlur` prop to false so it doesn't close on outside click
const PopoverForm = () => {
  const [isOpen, setIsOpen] = React.useState(false);
  const firstFieldRef = React.useRef(null);
  const open = () => setIsOpen(true);
  const close = () => setIsOpen(false);
  return (
    <>
      <Box d="inline-block" mr={3}>
        John Smith
      </Box>
      <Popover
        isOpen={isOpen}
        initialFocusRef={firstFieldRef}
        onOpen={open}
        onClose={close}
        placement="right"
        closeOnBlur={false}
      >
        <PopoverTrigger>
          <IconButton size="sm" icon="edit" />
        </PopoverTrigger>
        <PopoverContent zIndex={4} p={5}>
          <FocusLock returnFocus persistentFocus={false}>
            <PopoverArrow bg="white" />
            <PopoverCloseButton />
            <Form firstFieldRef={firstFieldRef} onCancel={close} />
          </FocusLock>
        </PopoverContent>
      </Popover>
    </>
  );
};

render(<PopoverForm />);

// import  FocusLock from "react-focus-lock"
// 1. Create a text input component
const TextInput = React.forwardRef((props, ref) => {
  return (
    <FormControl>
      <FormLabel htmlFor={props.id}>{props.label}</FormLabel>
      <Input ref={ref} id={props.id} {...props} />
    </FormControl>
  );
});
// 2. Create the form
const Form = ({ firstFieldRef, onCancel }) => {
  return (
    <Stack spacing={4}>
      <TextInput
        label="First name"
        id="first-name"
        ref={firstFieldRef}
        defaultValue="John"
      />
      <TextInput label="Last name" id="last-name" defaultValue="Smith" />
      <ButtonGroup d="flex" justifyContent="flex-end">
        <Button variant="outline" onClick={onCancel}>
          Cancel
        </Button>
        <Button isDisabled variantColor="teal">
          Save
        </Button>
      </ButtonGroup>
    </Stack>
  );
};
// 3. Create the Popover
// Ensure you set `closeOnBlur` prop to false so it doesn't close on outside click
const PopoverForm = () => {
  const [isOpen, setIsOpen] = React.useState(false);
  const firstFieldRef = React.useRef(null);
  const open = () => setIsOpen(true);
  const close = () => setIsOpen(false);
  return (
    <>
      <Box d="inline-block" mr={3}>
        John Smith
      </Box>
      <Popover
        isOpen={isOpen}
        initialFocusRef={firstFieldRef}
        onOpen={open}
        onClose={close}
        placement="right"
        closeOnBlur={false}
      >
        <PopoverTrigger>
          <IconButton size="sm" icon="edit" />
        </PopoverTrigger>
        <PopoverContent zIndex={4} p={5}>
          <FocusLock returnFocus persistentFocus={false}>
            <PopoverArrow bg="white" />
            <PopoverCloseButton />
            <Form firstFieldRef={firstFieldRef} onCancel={close} />
          </FocusLock>
        </PopoverContent>
      </Popover>
    </>
  );
};
render(<PopoverForm />);

Editable Example

Controlled Usage#

You can completely controlled the opening and closing of the popover by passing the isOpen, and onClose.

Sometime, you might need to set returnFocusOnClose to false to prevent popver from returning focus to PopoverTrigger's children.

function ControlledUsage() {
  const [isOpen, setIsOpen] = React.useState(false);
  const open = () => setIsOpen(!isOpen);
  const close = () => setIsOpen(false);
  return (
    <>
      <Button mr={5} onClick={open}>
        Trigger
      </Button>
      <Popover
        returnFocusOnClose={false}
        isOpen={isOpen}
        onClose={close}
        placement="right"
        closeOnBlur={false}
      >
        <PopoverTrigger>
          <Button variantColor="pink">Popover Target</Button>
        </PopoverTrigger>
        <PopoverContent zIndex={4}>
          <PopoverHeader fontWeight="semibold">Confirmation</PopoverHeader>
          <PopoverArrow />
          <PopoverCloseButton />
          <PopoverBody>
            Are you sure you want to continue with your action?
          </PopoverBody>
          <PopoverFooter d="flex" justifyContent="flex-end">
            <ButtonGroup size="sm">
              <Button variant="outline">Cancel</Button>
              <Button variantColor="red">Apply</Button>
            </ButtonGroup>
          </PopoverFooter>
        </PopoverContent>
      </Popover>
    </>
  );
}

function ControlledUsage() {
  const [isOpen, setIsOpen] = React.useState(false);
  const open = () => setIsOpen(!isOpen);
  const close = () => setIsOpen(false);
  return (
    <>
      <Button mr={5} onClick={open}>
        Trigger
      </Button>
      <Popover
        returnFocusOnClose={false}
        isOpen={isOpen}
        onClose={close}
        placement="right"
        closeOnBlur={false}
      >
        <PopoverTrigger>
          <Button variantColor="pink">Popover Target</Button>
        </PopoverTrigger>
        <PopoverContent zIndex={4}>
          <PopoverHeader fontWeight="semibold">Confirmation</PopoverHeader>
          <PopoverArrow />
          <PopoverCloseButton />
          <PopoverBody>
            Are you sure you want to continue with your action?
          </PopoverBody>
          <PopoverFooter d="flex" justifyContent="flex-end">
            <ButtonGroup size="sm">
              <Button variant="outline">Cancel</Button>
              <Button variantColor="red">Apply</Button>
            </ButtonGroup>
          </PopoverFooter>
        </PopoverContent>
      </Popover>
    </>
  );
}

Editable Example

Accessing Internal state#

Chakra provides access to two internal details, isOpen and onClose. Use the render prop pattern to gain access to them.

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

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

Editable Example

Chakra exports all the components you need to customize the look and feel of the popover. You can change the background, arrow size, boxShadow and so on.

Click

<Popover>
  <PopoverTrigger>
    <Box
      tabIndex="0"
      role="button"
      aria-label="Some box"
      p={5}
      w="120px"
      bg="gray.300"
      children="Click"
    />
  </PopoverTrigger>
  <PopoverContent zIndex={4} bg="tomato" color="white">
    <PopoverHeader fontWeight="semibold">Customization</PopoverHeader>
    <PopoverArrow bg="pink.500" />
    <PopoverCloseButton bg="purple.500" />
    <PopoverBody>
      Tadaa!! The arrow color and background color is customized. Check the
      props for each component.
    </PopoverBody>
  </PopoverContent>
</Popover>

<Popover>
  <PopoverTrigger>
    <Box
      tabIndex="0"
      role="button"
      aria-label="Some box"
      p={5}
      w="120px"
      bg="gray.300"
      children="Click"
    />
  </PopoverTrigger>
  <PopoverContent zIndex={4} bg="tomato" color="white">
    <PopoverHeader fontWeight="semibold">Customization</PopoverHeader>
    <PopoverArrow bg="pink.500" />
    <PopoverCloseButton bg="purple.500" />
    <PopoverBody>
      Tadaa!! The arrow color and background color is customized. Check the
      props for each component.
    </PopoverBody>
  </PopoverContent>
</Popover>

Editable Example

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 event the available space at the specified placment isn't enough.

<Popover placement="top-start">
  <PopoverTrigger>
    <Button>Click me</Button>
  </PopoverTrigger>
  <PopoverContent zIndex={4}>
    <PopoverHeader fontWeight="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 zIndex={4}>
    <PopoverHeader fontWeight="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>

Editable Example

Hover Trigger#

To show the popover when you mouse over or focus on the trigger, pass the prop trigger and set it to hover. When you focus on or mouse over the popover trigger, the popover will open.

If you quickly move your cursor to the popover content when it's open, it'll remain open till you leave.

Hover to see @swyx profile

function TwitterEx() {
  return (
    <Popover trigger="hover">
      <PopoverTrigger>
        <Link href="#" color="blue.500">
          Hover to see @swyx profile
        </Link>
      </PopoverTrigger>

      <DarkMode>
        <PopoverContent border="0" zIndex={4} width="400px" color="white">
          <Box p={5}>
            <Avatar
              name="swyx"
              src="https://pbs.twimg.com/profile_images/990728399873232896/CMPn3IxT_reasonably_small.jpg"
            />
            <Text mt={4} fontWeight="bold">
              swyx
              <Badge ml={3} fontSize="xs">
                Follows you
              </Badge>
            </Text>
            <Text mt={3}>
              Infinite Builder working on DX @Netlify. Helping people
              #LearnInPublic
            </Text>
          </Box>
        </PopoverContent>
      </DarkMode>
    </Popover>
  );
}

function TwitterEx() {
  return (
    <Popover trigger="hover">
      <PopoverTrigger>
        <Link href="#" color="blue.500">
          Hover to see @swyx profile
        </Link>
      </PopoverTrigger>
      <DarkMode>
        <PopoverContent border="0" zIndex={4} width="400px" color="white">
          <Box p={5}>
            <Avatar
              name="swyx"
              src="https://pbs.twimg.com/profile_images/990728399873232896/CMPn3IxT_reasonably_small.jpg"
            />
            <Text mt={4} fontWeight="bold">
              swyx
              <Badge ml={3} fontSize="xs">
                Follows you
              </Badge>
            </Text>
            <Text mt={3}>
              Infinite Builder working on DX @Netlify. Helping people
              #LearnInPublic
            </Text>
          </Box>
        </PopoverContent>
      </DarkMode>
    </Popover>
  );
}

Editable Example

Accessiblity#

When you see the word "trigger", it's 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
`isOpen`	`boolean`		If `true`, the popover is shown
`defaultIsOpen`	`boolean`		If `true`, the popover is shown initially.
`initialFocusRef`	`React.Ref`		The `ref` of the element that should receive focus when the popover opens.
`trigger`	`hover`, `click`	`click`	The interaction that triggers the popover.
`placement`	`PopperJS.placement`	`bottom`	The placement of the popover.
`returnFocusOnClose`	`boolean`	`true`	If `true`, the popover will return focus to the trigger when it closes
`closeOnBlur`	`boolean`	`true`	If `true`, the popover will close when you blur out it by clicking outside or tabbing out
`closeOnEsc`	`boolean`	`true`	If `true`, close the popover when the `esc` key is pressed
`children`	`React.ReactNode`, `(props: InternalState) => React.ReactNode`		The children of the popover
`gutter`	`number`	`4`	The gap (in pixels) to apply between the popover and the target. Used by `popper.js`
`usePortal`	`boolean`	`false`	If `true` the popover is displayed with a `Portal`. Rendering content inside a Portal allows the popover content to escape the physical bounds of its parent while still being positioned correctly relative to its target
`onOpen`	`() => void`		Callback fired when the popover opens
`onClose`	`() => void`		Callback fired when the popover closes

Other Props#

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

Proudly made in 🇳🇬

Released under the MIT License.

Popover

Import#

Basic Usage#

Rendering the Popover in a Portal#

Focus an element when Popover opens#

Trapping Focus within Popover#

Controlled Usage#

Accessing Internal state#

Customizing the Popover#

Popover Placements#

Hover Trigger#

Accessiblity#

Keyboard and Focus#

ARIA Attributes#

Props#

Popover Props#

Other Props#

Popover

.css-12m0k8p{pointer-events:auto;}Import.css-18hqai{color:#319795;font-weight:400;outline:none;opacity:0;margin-left:0.375rem;}.css-18hqai:focus{opacity:1;box-shadow:0 0 0 3px rgba(66,153,225,0.6);}#

Basic Usage#

Rendering the Popover in a Portal#

Focus an element when Popover opens#

Trapping Focus within Popover#

Controlled Usage#

Accessing Internal state#

Customizing the Popover#

Popover Placements#

Hover Trigger#

Accessiblity#

Keyboard and Focus#

ARIA Attributes#

Props#

Popover Props#

Other Props#

Import#