Popup (Preview)

To add the Popup component to your app:

1
2
import { Popup } from '@forge/react';

Description

A popup displays brief content in an overlay.

Props

Examples

Default

This is the simplest form of a popup. The popup opens from a trigger element.

1
2
import React, { useState } from "react";
import { Popup, Button, Box, xcss } from "@forge/react";

const contentStyles = xcss({
  padding: "space.200",
});

const PopupExample = () => {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <Popup
      isOpen={isOpen}
      onClose={() => setIsOpen(false)}
      placement="bottom-start"
      content={() => <Box xcss={contentStyles}>Content</Box>}
      trigger={() => (
        <Button
          appearance="primary"
          isSelected={isOpen}
          onClick={() => setIsOpen(!isOpen)}
        >
          {isOpen ? "Close" : "Open"} popup
        </Button>
      )}
    />
  );
};

Placement

Use the placement prop to set a preferred position (auto, top, right, left, or bottom). The popup will move automatically if it's near the edge of the screen.

Using the auto placement will place the popup on the side with the most space available.

All available placement values: "auto" | "auto-start" | "auto-end" | "top" | "bottom" | "right" | "left" | "top-start" | "top-end" | "bottom-start" | "bottom-end" | "right-start" | "right-end" | "left-start" | "left-end"

Multiple

You can use popups multiple times on the same page.

1
2
import React, { useState } from "react";
import { Popup, Button, Box, xcss, ButtonGroup } from "@forge/react";

const contentStyles = xcss({
  padding: "space.200",
});

const PopupExample = ({ index }) => {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <Popup
      isOpen={isOpen}
      onClose={() => setIsOpen(false)}
      placement="bottom-start"
      content={() => <Box xcss={contentStyles}>Content</Box>}
      trigger={() => (
        <Button
          appearance="primary"
          isSelected={isOpen}
          onClick={() => setIsOpen(!isOpen)}
        >
          {isOpen ? "Close" : "Open"} popup {index + 1}
        </Button>
      )}
    />
  );
};

const PopupMultipleExample = () => (
  <ButtonGroup label="Open required popup">
    {Array.from(Array(3)).map((_, index) => (
      <PopupExample index={index} />
    ))}
  </ButtonGroup>
);

Role

Use the role prop to set a role for the popup content. We do not forbid passing any of the aria roles, but we strongly recommend using only menu or dialog. When the role="dialog" property is passed, one of the following properties must also be added: label or titleId.

1
2
import React, { useState } from "react";
import { Popup, Button, Box, xcss } from "@forge/react";

const contentStyles = xcss({
  padding: "space.200",
});

const PopupRoleExample = () => {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <Popup
      isOpen={isOpen}
      onClose={() => setIsOpen(false)}
      placement="bottom-start"
      role="dialog"
      content={() => <Box xcss={contentStyles}>Content</Box>}
      trigger={() => (
        <Button
          appearance="primary"
          isSelected={isOpen}
          onClick={() => setIsOpen(!isOpen)}
        >
          {isOpen ? "Close" : "Open"} popup
        </Button>
      )}
    />
  );
};

Full width

Use shouldFitContainer to fit the popup width to its parent's width. When set to true, the trigger and popup elements will be wrapped in a div with position: relative. The popup will be rendered as a sibling to the trigger element, and will be full width.

1
2
import React, { useState } from "react";
import { Popup, Button, Box, xcss } from "@forge/react";

const contentStyles = xcss({
  padding: "space.200",
});

const PopupFullWidthExample = () => {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <Popup
      isOpen={isOpen}
      onClose={() => setIsOpen(false)}
      placement="bottom-start"
      shouldFitContainer
      content={() => <Box xcss={contentStyles}>Content</Box>}
      trigger={() => (
        <Button
          shouldFitContainer
          appearance="primary"
          isSelected={isOpen}
          onClick={() => setIsOpen(!isOpen)}
        >
          {isOpen ? "Close" : "Open"} popup
        </Button>
      )}
    />
  );
};

Accessibility Considerations

• Don’t make popups that scroll. There isn't enough visual affordance to show that there's hidden content.
• Avoid nesting popups wherever possible.
• Use role to indicate what type of interactive element the popup is going to be. - Usually the popup will be a menu or dialog. When the popup is used as a dialog, make sure it has a label or titleId that gives the dialog an accessible name.