Popover

Display popover section relative to given target element

Source

View source code

LLM docs

LLM documentation

Docs

Edit this page

PackageIcon

@mantine/core

Usage

import { Popover, Text, Button } from '@mantine/core';

function Demo() {
  return (
    <Popover width={200} position="bottom" withArrow shadow="md">
      <Popover.Target>
        <Button>Toggle popover</Button>
      </Popover.Target>
      <Popover.Dropdown>
        <Text size="xs">This is uncontrolled popover, it is opened when button is clicked</Text>
      </Popover.Dropdown>
    </Popover>
  );
}

Controlled

You can control the Popover state with the opened and onChange props:

import { useState } from 'react';
import { Button, Popover } from '@mantine/core';

function Demo() {
  const [opened, setOpened] = useState(false);
  return (
    <Popover opened={opened} onChange={setOpened}>
      <Popover.Target>
        <Button onClick={() => setOpened((o) => !o)}>
          Toggle popover
        </Button>
      </Popover.Target>

      <Popover.Dropdown>Dropdown</Popover.Dropdown>
    </Popover>
  );
}

Controlled example with mouse events:

import { useDisclosure } from '@mantine/hooks';
import { Popover, Text, Button } from '@mantine/core';

function Demo() {
  const [opened, { close, open }] = useDisclosure(false);
  return (
    <Popover width={200} position="bottom" withArrow shadow="md" opened={opened}>
      <Popover.Target>
        <Button onMouseEnter={open} onMouseLeave={close}>
          Hover to see popover
        </Button>
      </Popover.Target>
      <Popover.Dropdown style={{ pointerEvents: 'none' }}>
        <Text size="sm">This popover is shown when user hovers the target element</Text>
      </Popover.Dropdown>
    </Popover>
  );
}

Focus trap

If you need to use interactive elements (inputs, buttons, etc.) inside Popover.Dropdown, set the trapFocus prop:

import { Popover, Button, TextInput } from '@mantine/core';

function Demo() {
  return (
    <Popover width={300} trapFocus position="bottom" withArrow shadow="md">
      <Popover.Target>
        <Button>Toggle popover</Button>
      </Popover.Target>
      <Popover.Dropdown>
        <TextInput label="Name" placeholder="Name" size="xs" />
        <TextInput label="Email" placeholder="john@doe.com" size="xs" mt="xs" />
      </Popover.Dropdown>
    </Popover>
  );
}

Inline elements

Enable the inline middleware to use Popover with inline elements:

Stantler’s magnificent antlers were traded at high prices as works of art. As a result, this Pokémon was hunted close to extinction by those who were after the priceless antlers. When visiting a junkyard, you may catch sight of it having an intense fight with Murkrow over shiny objects.Ho-Oh’s feathers glow in seven colors depending on the angle at which they are struck by light. These feathers are said to bring happiness to the bearers. This Pokémon is said to live at the foot of a rainbow.

import { Popover, Mark, Text } from '@mantine/core';

function Demo() {
  return (
    <Text>
      Stantler’s magnificent antlers were traded at high prices as works of art. As a result, this
      Pokémon was hunted close to extinction by those who were after the priceless antlers.{' '}
      <Popover middlewares={{ flip: true, shift: true, inline: true }} position="top">
        <Popover.Target>
          <Mark>When visiting a junkyard</Mark>
        </Popover.Target>
        <Popover.Dropdown>Inline dropdown</Popover.Dropdown>
      </Popover>
      , you may catch sight of it having an intense fight with Murkrow over shiny objects.Ho-Oh’s
      feathers glow in seven colors depending on the angle at which they are struck by light. These
      feathers are said to bring happiness to the bearers. This Pokémon is said to live at the foot
      of a rainbow.
    </Text>
  );
}

Same width

Set the width="target" prop to make the Popover dropdown take the same width as the target element:

import { Popover, Text, Button } from '@mantine/core';

function Demo() {
  return (
    <Popover width="target" position="bottom" withArrow shadow="md">
      <Popover.Target>
        <Button w={280}>Toggle popover</Button>
      </Popover.Target>
      <Popover.Dropdown>
        <Text size="sm">
          This popover has same width as target, it is useful when you are building input dropdowns
        </Text>
      </Popover.Dropdown>
    </Popover>
  );
}

offset

Set the offset prop to a number to change the dropdown position relative to the target element. This way you can control the dropdown offset on the main axis only.

Position

Offset

import { Popover, Button, Text } from '@mantine/core';

function Demo() {
  return (
    <Popover
      width={200}
      opened
      position="bottom"
      offset={0}
    >
      <Popover.Target>
        <Button>Popover target</Button>
      </Popover.Target>
      <Popover.Dropdown>
        <Text size="xs">
          Change position and offset to configure dropdown offset relative to target
        </Text>
      </Popover.Dropdown>
    </Popover>
  );
}

To control offset on both axes, pass an object with mainAxis and crossAxis properties:

Position

Main axis

Cross axis

import { Popover, Button, Text } from '@mantine/core';

function Demo() {
  return (
    <Popover
      width={200}
      position="bottom"
      opened
      offset={{ mainAxis: 0, crossAxis: 0 }}
    >
      <Popover.Target>
        <Button>Popover target</Button>
      </Popover.Target>
      <Popover.Dropdown>
        <Text size="xs">
          Change position and offset to configure dropdown offset relative to target
        </Text>
      </Popover.Dropdown>
    </Popover>
  );
}

Middlewares

You can enable or disable Floating UI middlewares with the middlewares prop:

shift middleware shifts the dropdown to keep it in view. It is enabled by default.
flip middleware changes the placement of the dropdown to keep it in view. It is enabled by default.
inline middleware improves positioning for inline reference elements that span over multiple lines. It is disabled by default.
size middleware manipulates the dropdown size. It is disabled by default.

Example of turning off shift and flip middlewares:

import { Popover } from '@mantine/core';

function Demo() {
  return (
    <Popover
      middlewares={{ flip: false, shift: false }}
      position="bottom"
    >
      {/* Popover content */}
    </Popover>
  );
}

Customize middleware options

To customize Floating UI middleware options, pass them as an object to the middlewares prop. For example, to change the shift middleware padding to 20px, use the following configuration:

import { Popover } from '@mantine/core';

function Demo() {
  return (
    <Popover
      middlewares={{ shift: { padding: 20 } }}
      position="bottom"
    >
      {/* Popover content */}
    </Popover>
  );
}

Dropdown arrow

Set the withArrow prop to add an arrow to the dropdown. The arrow is a div element rotated with transform: rotate(45deg).

The arrowPosition prop determines how the arrow is positioned relative to the target element when position is set to *-start and *-end values on the Popover component. By default, the value is center – the arrow is positioned in the center of the target element if it is possible.

If you change arrowPosition to side, then the arrow will be positioned on the side of the target element, and you will be able to control the arrow offset with the arrowOffset prop. Note that when arrowPosition is set to center, the arrowOffset prop is ignored.

Arrow position

Center

Side

Arrow offset

Arrow size

Arrow radius

import { Popover, Button, Text } from '@mantine/core';

function Demo() {
  return (
    <Popover width={200} opened position="bottom-start" withArrow>
      <Popover.Target>
        <Button>Target element</Button>
      </Popover.Target>
      <Popover.Dropdown>
        <Text size="xs">Arrow position can be changed for *-start and *-end positions</Text>
      </Popover.Dropdown>
    </Popover>
  );
}

With overlay

Set the withOverlay prop to add an overlay behind the dropdown. You can pass additional configuration to the Overlay component with the overlayProps prop:

import { Popover, Avatar, Text, Group, Anchor, Stack } from '@mantine/core';

function Demo() {
  return (
    <Popover
      width={320}
      shadow="md"
      withArrow
      withOverlay
      overlayProps={{ zIndex: 10000, blur: '8px' }}
      zIndex={10001}
    >
      <Popover.Target>
        <UnstyledButton style={{ zIndex: 10001, position: 'relative' }}>
          <Avatar src="https://avatars.githubusercontent.com/u/79146003?s=200&v=4" radius="xl" />
        </UnstyledButton>
      </Popover.Target>
      <Popover.Dropdown>
        <Group>
          <Avatar src="https://avatars.githubusercontent.com/u/79146003?s=200&v=4" radius="xl" />
          <Stack gap={5}>
            <Text size="sm" fw={700} style={{ lineHeight: 1 }}>
              Mantine
            </Text>
            <Anchor href="https://x.com/mantinedev" c="dimmed" size="xs" style={{ lineHeight: 1 }}>
              @mantinedev
            </Anchor>
          </Stack>
        </Group>

        <Text size="sm" mt="md">
          Customizable React components and hooks library with focus on usability, accessibility and
          developer experience
        </Text>

        <Group mt="md" gap="xl">
          <Text size="sm">
            <b>0</b> Following
          </Text>
          <Text size="sm">
            <b>1,174</b> Followers
          </Text>
        </Group>
      </Popover.Dropdown>
    </Popover>
  );
}

Hide detached

Use the hideDetached prop to configure how the dropdown behaves when the target element is hidden with styles (display: none, visibility: hidden, etc.), removed from the DOM, or when the target element is scrolled out of the viewport.

By default, hideDetached is enabled – the dropdown is hidden with the target element. You can change this behavior with hideDetached={false}. To see the difference, try to scroll the root element of the following demo:

import { Box, Button, Group, Popover } from '@mantine/core';

function Demo() {
  return (
    <Box
      bd="1px solid var(--mantine-color-dimmed)"
      p="xl"
      w={{ base: 340, sm: 400 }}
      h={200}
      style={{ overflow: 'auto' }}
    >
      <Box w={1000} h={400}>
        <Group>
          <Popover width="target" position="bottom" opened>
            <Popover.Target>
              <Button>Toggle popover</Button>
            </Popover.Target>
            <Popover.Dropdown>This popover dropdown is hidden when detached</Popover.Dropdown>
          </Popover>

          <Popover width="target" position="bottom" opened hideDetached={false}>
            <Popover.Target>
              <Button>Toggle popover</Button>
            </Popover.Target>
            <Popover.Dropdown>This popover dropdown is visible when detached</Popover.Dropdown>
          </Popover>
        </Group>
      </Box>
    </Box>
  );
}

Disabled

Set the disabled prop to prevent Popover.Dropdown from rendering:

Disabled

import { Popover, Text, Button } from '@mantine/core';

function Demo() {
  return (
    <Popover width={200}>
      <Popover.Target>
        <Button>Toggle popover</Button>
      </Popover.Target>
      <Popover.Dropdown>
        <Text size="xs">Disabled popover dropdown is always hidden</Text>
      </Popover.Dropdown>
    </Popover>
  );
}

Click outside

By default, Popover closes when you click outside of the dropdown. To disable this behavior, set closeOnClickOutside={false}.

You can configure events that are used for click-outside detection with the clickOutsideEvents prop. By default, Popover listens to mousedown and touchstart events. You can change it to any other events, for example, mouseup and touchend:

import { Popover, Text, Button } from '@mantine/core';

function Demo() {
  return (
    <Popover width={200} position="bottom" clickOutsideEvents={['mouseup', 'touchend']}>
      <Popover.Target>
        <Button>Toggle popover</Button>
      </Popover.Target>
      <Popover.Dropdown>
        <Text size="xs">Popover will be closed with mouseup and touchend events</Text>
      </Popover.Dropdown>
    </Popover>
  );
}

onDismiss

If you need to control the opened state, but still want to close the popover on outside clicks and escape key presses, use the onDismiss prop:

import { useState } from 'react';
import { Button, Popover } from '@mantine/core';

function Demo() {
  const [opened, setOpened] = useState(false);
  return (
    <Popover
      opened={opened}
      onDismiss={() => setOpened(false)}
    >
      <Popover.Target>
        <Button onClick={() => setOpened((o) => !o)}>
          Toggle popover
        </Button>
      </Popover.Target>

      <Popover.Dropdown>Dropdown</Popover.Dropdown>
    </Popover>
  );
}

Initial focus

Popover uses the FocusTrap component to manage focus. Add the data-autofocus attribute to the element that should receive initial focus:

import { Popover } from '@mantine/core';

function Demo() {
  return (
    <Popover>
      <Popover.Target>
        <button type="button">Target</button>
      </Popover.Target>
      <Popover.Dropdown>
        <input />
        <input data-autofocus />
        <input />
      </Popover.Dropdown>
    </Popover>
  );
}

Popover.Target children

Popover.Target requires an element or a component as a single child – strings, fragments, numbers, and multiple elements/components are not supported and will throw an error. Custom components must provide a prop to get the root element ref; all Mantine components support ref out of the box.

import { Popover, Button } from '@mantine/core';

function Demo() {
  return (
    <>
      <Popover.Target>
        <button>Native button – ok</button>
      </Popover.Target>

      {/* OK */}
      <Popover.Target>
        <Button>Mantine component – ok</Button>
      </Popover.Target>

      {/* String, NOT OK – will throw error */}
      <Popover.Target>Raw string</Popover.Target>

      {/* Number, NOT OK – will throw error */}
      <Popover.Target>{2}</Popover.Target>

      {/* Fragment, NOT OK – will throw error */}
      <Popover.Target>
        <>Fragment, NOT OK, will throw error</>
      </Popover.Target>

      {/* Multiple nodes, NOT OK – will throw error */}
      <Popover.Target>
        <div>More that one node</div>
        <div>NOT OK, will throw error</div>
      </Popover.Target>
    </>
  );
}

Required ref prop

Custom components that are rendered inside Popover.Target are required to support the ref prop:

// Example of code that WILL NOT WORK
import { Popover } from '@mantine/core';

// ❌ ref is not forwarded to the root element
function MyComponent() {
  return <div>My component</div>;
}

// This will not work – MyComponent does not support ref
function Demo() {
  return (
    <Popover>
      <Popover.Target>
        <MyComponent />
      </Popover.Target>
    </Popover>
  );
}

Pass ref to the root element:

// Example of code that will work
import { Popover } from '@mantine/core';

// ✅ ref is forwarded to the root element
function MyComponent({ ref, ...others }: React.ComponentProps<'div'>) {
  return <div ref={ref} {...others}>My component</div>;
}

// Works correctly – ref is forwarded
function Demo() {
  return (
    <Popover>
      <Popover.Target>
        <MyComponent />
      </Popover.Target>
    </Popover>
  );
}

Nested popovers

Nested popovers require children rendering without Portal. Usually, you should disable the portal with props of the component that renders popover content. For example, Select has a comboboxProps={{ withinPortal: false }} prop. Check the documentation of the component that you are using to render popover content to find out how to disable the portal. If the portal is not disabled, outside clicks will close all popovers.

Example of disabling the portal in Select and DatePickerInput components:

import { Button, Popover, Select } from '@mantine/core';
import { DatePickerInput } from '@mantine/dates';

function Demo() {
  return (
    <Popover width={300} position="bottom" withArrow shadow="md">
      <Popover.Target>
        <Button>Toggle popover</Button>
      </Popover.Target>
      <Popover.Dropdown bg="var(--mantine-color-body)">
        <Select
          label="Select within Popover"
          placeholder="Select within Popover"
          comboboxProps={{ withinPortal: false }}
          data={['React', 'Angular', 'Svelte', 'Vue']}
        />
        <DatePickerInput
          label="DatePickerInput within Popover"
          placeholder="DatePickerInput within Popover"
          popoverProps={{ withinPortal: false }}
          mt="md"
        />
      </Popover.Dropdown>
    </Popover>
  );
}

Accessibility

Popover follows WAI-ARIA recommendations:

Dropdown element has role="dialog" and aria-labelledby="target-id" attributes
Target element has aria-haspopup="dialog", aria-expanded, aria-controls="dropdown-id" attributes

An uncontrolled Popover will be accessible only when used with a button element or component that renders it (Button, ActionIcon, etc.). Other elements will not support Space and Enter key presses.

Keyboard interactions

Key	Description	Condition
`Escape`	Closes dropdown	`Focus within dropdown`
`Space/Enter`	Opens/closes dropdown	`Focus on target element`

Overlay

Tooltip