Popper

The Popper component lets you create tooltips and popovers that display information about an element on the page.

Introduction

The Popper is a utility component for creating various kinds of popups. It relies on the third-party library (Popper.js v2) for positioning.

Component

Usage

After installation, you can start building with this component using the following basic elements:

<span class="token keyword">import</span> Popper <span class="token keyword">from</span> <span class="token string">'@mui/base/Popper'</span><span class="token punctuation">;</span>

<span class="token keyword">export</span> <span class="token keyword">default</span> <span class="token keyword">function</span> <span class="token function">MyApp</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
  <span class="token keyword">return</span> <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">Popper</span></span><span class="token punctuation">></span></span><span class="token punctuation">{</span><span class="token comment">/* the popper's content */</span><span class="token punctuation">}</span><span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span><span class="token class-name">Popper</span></span><span class="token punctuation">></span></span><span class="token punctuation">;</span>
<span class="token punctuation">}</span>

Basics

By default, the Popper is mounted to the DOM when its open prop is set to true, and removed from the DOM when open is false.

anchorEl is passed as the reference object to create a new Popper.js instance. The children are placed in a Portal prepended to the body of the document to avoid rendering problems. You can disable this behavior with disablePortal prop.

The following demo shows how to create and style a basic popper. Click Toggle Popper to see how it behaves:

import * as React from 'react';
import Popper from '@mui/base/Popper';
import { styled, Theme } from '@mui/system';

export default function SimplePopper() {
  const [anchorEl, setAnchorEl] = React.useState<null | HTMLElement>(null);

  const handleClick = (event: React.MouseEvent<HTMLElement>) => {
    setAnchorEl(anchorEl ? null : event.currentTarget);
  };

  const open = Boolean(anchorEl);
  const id = open ? 'simple-popper' : undefined;

  return (
    <div>
      <button aria-describedby={id} type="button" onClick={handleClick}>
        Toggle Popper
      </button>
      <Popper id={id} open={open} anchorEl={anchorEl}>
        <StyledPopperDiv>The content of the Popper.</StyledPopperDiv>
      </Popper>
    </div>
  );
}

const StyledPopperDiv = styled('div')(
  ({ theme }: { theme: Theme }) => `
  padding: 0.5rem;
  border: 1px solid;
  background-color: ${theme.palette.mode === 'dark' ? '#121212' : '#fff'};
  opacity: 1;
  margin: 0.25rem 0px;
`,
);

import * as React from 'react';
import Popper from '@mui/base/Popper';
import { styled, Theme } from '@mui/system';

export default function SimplePopper() {
  const [anchorEl, setAnchorEl] = React.useState<null | HTMLElement>(null);

  const handleClick = (event: React.MouseEvent<HTMLElement>) => {
    setAnchorEl(anchorEl ? null : event.currentTarget);
  };

  const open = Boolean(anchorEl);
  const id = open ? 'simple-popper' : undefined;

  return (
    <div>
      <button aria-describedby={id} type="button" onClick={handleClick}>
        Toggle Popper
      </button>
      <Popper id={id} open={open} anchorEl={anchorEl}>
        <StyledPopperDiv>The content of the Popper.</StyledPopperDiv>
      </Popper>
    </div>
  );
}

const StyledPopperDiv = styled('div')(
  ({ theme }: { theme: Theme }) => `
  padding: 0.5rem;
  border: 1px solid;
  background-color: ${theme.palette.mode === 'dark' ? '#121212' : '#fff'};
  opacity: 1;
  margin: 0.25rem 0px;
`,
);

Press Enter to start editing

Customization

Placement

The popper's default placement is bottom. You can change it using the placement prop. Try changing this value to top in the interactive demo below to see how it works:

Transitions

You can animate the open and close states of the popper with a render prop child and a transition component, as long as the component meets these conditions:

Is a direct child descendant of the popper
Calls the onEnter callback prop when the enter transition starts
Calls the onExited callback prop when the exit transition is completed

These two callbacks allow the popper to unmount the child content when closed and fully transitioned.