Popup

The Popup component is a utility that lets you display content in tooltips and popovers.

Introduction

The Popup is a utility component for creating various kinds of popups. It relies on the third-party Floating UI library for positioning.

Component

import { Unstable_Popup as Popup } from '@mui/base/Unstable_Popup';

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

anchor is passed as the reference element to Floating UI's useFloating hook. 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. See how it's done in the Disable portal section below.

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

import * as React from 'react';
import { Unstable_Popup as Popup } from '@mui/base/Unstable_Popup';
import { styled } from '@mui/system';

export default function SimplePopup() {
  const [anchor, setAnchor] = React.useState<null | HTMLElement>(null);

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

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

  return (
    <div>
      <Button aria-describedby={id} type="button" onClick={handleClick}>
        Toggle Popup
      </Button>
      <Popup id={id} open={open} anchor={anchor}>
        <PopupBody>The content of the Popup.</PopupBody>
      </Popup>
    </div>
  );
}

const grey = {
  50: '#f6f8fa',
  200: '#d0d7de',
  500: '#6e7781',
  700: '#424a53',
  900: '#24292f',
};

const blue = {
  500: '#007FFF',
  600: '#0072E5',
  700: '#0059B2',
};

const PopupBody = styled('div')(
  ({ theme }) => `
  width: max-content;
  padding: 12px 16px;
  margin: 8px;
  border-radius: 8px;
  border: 1px solid ${theme.palette.mode === 'dark' ? grey[700] : grey[200]};
  background-color: ${theme.palette.mode === 'dark' ? grey[900] : grey[50]};
  box-shadow: ${
    theme.palette.mode === 'dark'
      ? `0px 4px 8px rgb(0 0 0 / 0.7)`
      : `0px 4px 8px rgb(0 0 0 / 0.1)`
  };
  font-family: 'IBM Plex Sans', sans-serif;
  font-size: 0.875rem;
  z-index: 1;
`,
);

const Button = styled('button')`
  font-family: 'IBM Plex Sans', sans-serif;
  font-size: 0.875rem;
  line-height: 1.5;
  background-color: ${blue[500]};
  color: white;
  border-radius: 8px;
  font-weight: 600;
  padding: 8px 16px;
  cursor: pointer;
  transition: all 150ms ease;
  border: none;

  &:hover {
    background-color: ${blue[600]};
  }

  &:active {
    background-color: ${blue[700]};
  }

  &:focus-visible {
    box-shadow: 0 4px 20px 0 rgb(61 71 82 / 0.1), 0 0 0 5px rgb(0 127 255 / 0.5);
    outline: none;
  }
`;

import * as React from 'react';
import { Unstable_Popup as Popup } from '@mui/base/Unstable_Popup';
import { styled } from '@mui/system';

export default function SimplePopup() {
  const [anchor, setAnchor] = React.useState<null | HTMLElement>(null);

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

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

  return (
    <div>
      <Button aria-describedby={id} type="button" onClick={handleClick}>
        Toggle Popup
      </Button>
      <Popup id={id} open={open} anchor={anchor}>
        <PopupBody>The content of the Popup.</PopupBody>
      </Popup>
    </div>
  );
}

const grey = {
  50: '#f6f8fa',
  200: '#d0d7de',
  500: '#6e7781',
  700: '#424a53',
  900: '#24292f',
};

const blue = {
  500: '#007FFF',
  600: '#0072E5',
  700: '#0059B2',
};

const PopupBody = styled('div')(
  ({ theme }) => `
  width: max-content;
  padding: 12px 16px;
  margin: 8px;
  border-radius: 8px;
  border: 1px solid ${theme.palette.mode === 'dark' ? grey[700] : grey[200]};
  background-color: ${theme.palette.mode === 'dark' ? grey[900] : grey[50]};
  box-shadow: ${
    theme.palette.mode === 'dark'
      ? `0px 4px 8px rgb(0 0 0 / 0.7)`
      : `0px 4px 8px rgb(0 0 0 / 0.1)`
  };
  font-family: 'IBM Plex Sans', sans-serif;
  font-size: 0.875rem;
  z-index: 1;
`,
);

const Button = styled('button')`
  font-family: 'IBM Plex Sans', sans-serif;
  font-size: 0.875rem;
  line-height: 1.5;
  background-color: ${blue[500]};
  color: white;
  border-radius: 8px;
  font-weight: 600;
  padding: 8px 16px;
  cursor: pointer;
  transition: all 150ms ease;
  border: none;

  &:hover {
    background-color: ${blue[600]};
  }

  &:active {
    background-color: ${blue[700]};
  }

  &:focus-visible {
    box-shadow: 0 4px 20px 0 rgb(61 71 82 / 0.1), 0 0 0 5px rgb(0 127 255 / 0.5);
    outline: none;
  }
`;

Press Enter to start editing

Customization

Placement

The Popup'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 opening and closing of the Popup using CSS transitions, CSS animations, or third-party animation libraries.

To enable transitions, first set the withTransition prop. This will make the Popup wait for the exit animation to finish before unmounting.

Then, instead of placing the Popup contents directly as its children, wrap them in a function that receives an object with requestOpen: boolean, onEnter: () => void, and onExited: () => void fields.

Run the open transition when requestOpen becomes true and the close transition when it changes to false. Call the onEnter once the entering transition is about to start. When the exit transition finishes, call the provided onExited function to let the Popup know it can be unmounted.

If using CSS transitions or animations, you can use the onTransitionEnd or onAnimationEnd events, respectively, to detect when the transition is over.

<Button ref={setAnchor} onClick={() => setOpen((o) => !o)} type="button">
  Toggle Popup
</Button>
<Popup anchor={anchor} open={open} withTransition>
  {(props: PopupChildrenProps) => (
    <PopAnimation {...props}>
      <PopupBody>This is an animated popup.</PopupBody>
    </PopAnimation>
  )}
</Popup>

<Button ref={setAnchor} onClick={() => setOpen((o) => !o)} type="button">
  Toggle Popup
</Button>
<Popup anchor={anchor} open={open} withTransition>
  {(props: PopupChildrenProps) => (
    <PopAnimation {...props}>
      <PopupBody>This is an animated popup.</PopupBody>
    </PopAnimation>
  )}
</Popup>

Press Enter to start editing

Disable portal

To render the Popup where it's defined in the source, without using React portals, pass in the disablePortal prop. Note that it may cause visual clipping if a Popup is placed in a container without visible overflow.

You can use fixed positioning to prevent clipping when not using portals. The Popup has the strategy prop which is responsible for determining how the position is calculated. When set to "fixed", the fixed CSS position will be used and the Popup won't be subject to overflow hiding.

<PopupWithTrigger id="popup-with-portal" buttonLabel="With a portal" />
<PopupWithTrigger
  id="popup-without-portal"
  buttonLabel="No portal, default strategy"
  disablePortal
/>
<PopupWithTrigger
  id="popup-without-portal-fixed"
  buttonLabel="No portal, 'fixed' strategy"
  disablePortal
  strategy="fixed"
/>

<PopupWithTrigger id="popup-with-portal" buttonLabel="With a portal" />
<PopupWithTrigger
  id="popup-without-portal"
  buttonLabel="No portal, default strategy"
  disablePortal
/>
<PopupWithTrigger
  id="popup-without-portal-fixed"
  buttonLabel="No portal, 'fixed' strategy"
  disablePortal
  strategy="fixed"
/>

Press Enter to start editing

Floating UI middleware

If you need to modify the underlying Floating UI middleware, you can do so via the middleware prop. By default, the Popup uses the offset (with the value provided in the offset prop) and flip functions. If you provide your own middleware array, these defaults won't be applied.