Popup - Examples - Components

A popup displays brief content in an overlay.

Motion in Early Access

The motion added into Popup is in Early Access. The motion updates are currently behind the feature flag: platform-dst-motion-uplift-popup.

Default

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

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.

import { useState } from 'react';

import { css, jsx } from '@compiled/react';

import Button from '@atlaskit/button/default/button';
import { cssMap } from '@atlaskit/css';
import { type Placement, placements } from '@atlaskit/popper/main';
import { Popup } from '@atlaskit/popup/popup';
import { Box } from '@atlaskit/primitives/compiled/box';
import { token } from '@atlaskit/tokens';

const placementGridPositions = cssMap({
	'top-start': {
		gridColumn: 2,
		gridRow: 1,
	},
	top: {
		gridColumn: 3,
		gridRow: 1,
	},
	'top-end': {
		gridColumn: 4,
		gridRow: 1,
	},
	'bottom-start': {
		gridColumn: 2,
		gridRow: 5,
	},
	bottom: {
		gridColumn: 3,
		gridRow: 5,
	},
	'bottom-end': {
		gridColumn: 4,
		gridRow: 5,
	},
	'right-start': {
		gridColumn: 5,
		gridRow: 2,
	},
	right: {
		gridColumn: 5,
		gridRow: 3,
	},
	'right-end': {
		gridColumn: 5,
		gridRow: 4,
	},
	'left-start': {
		gridColumn: 1,
		gridRow: 2,
	},
	left: {
		gridColumn: 1,
		gridRow: 3,
	},
	'left-end': {
		gridColumn: 1,
		gridRow: 4,
	},
	'auto-start': {
		gridColumn: 3,
		gridRow: 2,
	},
	auto: {
		gridColumn: 3,
		gridRow: 3,
	},
	'auto-end': {
		gridColumn: 3,
		gridRow: 4,
	},
});

const contentStyles = css({
	maxWidth: '220px',
	paddingBlockEnd: token('space.200'),
	paddingBlockStart: token('space.200'),
	paddingInlineEnd: token('space.200'),
	paddingInlineStart: token('space.200'),
});

const buttonGridStyles = css({
	display: 'grid',
	gap: token('space.100'),
	gridTemplate: 'repeat(5, 1fr) / repeat(5, 1fr)',
	justifyItems: 'stretch',
});

const PopupPlacementExample = (): JSX.Element => {
	const [openPlacement, setOpenPlacement] = useState<Placement | null>(null);

	return (
		<div css={buttonGridStyles}>
			{placements.map((placement) => {
				const isOpen = openPlacement === placement;

				return (
					<Popup
						shouldRenderToParent
						key={placement}
						placement={placement}
						isOpen={isOpen}
						onClose={() => {
							setOpenPlacement((value) => (value === placement ? null : value));
						}}
						content={() => (
							<div css={contentStyles}>
								Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut aliquam massa ac risus
								scelerisque, in iaculis magna semper. Phasellus sagittis congue elit, non suscipit
								nulla rhoncus vitae.
							</div>
						)}
						trigger={(triggerProps) => (
							<Box xcss={placementGridPositions[placement]}>
								<Button
									{...triggerProps}
									shouldFitContainer
									isSelected={isOpen}
									onClick={() => setOpenPlacement(isOpen ? null : placement)}
								>
									{placement}
								</Button>
							</Box>
						)}
					/>
				);
			})}
		</div>
	);
};

export default PopupPlacementExample;

Multiple

You can use popups multiple times on the same page.

Nested

Nesting popups inside other popups works out of the box. However, be mindful that nested popups quickly become confusing, inaccessible, and difficult to navigate. If you’re nesting a lot of content, it’s time to move your experience to a new page instead.

This example has additional code to prevent the parent popup closing when interacting with the child popup.

Content updates

When changing the content inside the popup, call the update() function to reposition the popup.

Make sure to call this in the same callback or update step to ensure everything happens in the same animation frame.

Updates on

import { useEffect, useState } from 'react';

import { jsx } from '@compiled/react';

import Button from '@atlaskit/button/default/button';
import { cssMap } from '@atlaskit/css';
import noop from '@atlaskit/ds-lib/noop';
import Heading from '@atlaskit/heading/heading';
import { Popup } from '@atlaskit/popup/popup';
import { Box } from '@atlaskit/primitives/compiled/box';
import { Stack } from '@atlaskit/primitives/compiled/stack';
import { Text } from '@atlaskit/primitives/compiled/text';
import Toggle from '@atlaskit/toggle/toggle';
import { token } from '@atlaskit/tokens';

import { data } from './data';

const wrapperStyles = cssMap({
	root: {
		display: 'flex',
		alignItems: 'center',
		justifyContent: 'space-between',
	},
});

const contentStyles = cssMap({
	root: {
		maxWidth: '350px',
		paddingInlineStart: token('space.200'),
		paddingInlineEnd: token('space.200'),
		paddingBlockStart: token('space.200'),
		paddingBlockEnd: token('space.200'),
		textAlign: 'center',
	},
});

const Values = ({ onUpdate }: { onUpdate: () => void }) => {
	const [textIndex, setTextIndex] = useState(0);

	useEffect(() => {
		const intervalId = setInterval(() => {
			setTextIndex((prevIndex) => (prevIndex + 1) % data.length);
			onUpdate();
		}, 15000);

		return () => clearInterval(intervalId);
	}, [onUpdate]);

	return (
		<Box xcss={contentStyles.root} aria-live="assertive" aria-atomic="true">
			<Stack space="space.100">
				<Heading size="large">{data[textIndex].title}</Heading>
				<Box as="blockquote">
					<Text>{data[textIndex].description}</Text>
				</Box>
			</Stack>
		</Box>
	);
};

const PopupContentUpdateExample = (): JSX.Element => {
	const [isOpen, setIsOpen] = useState(false);
	const [isUpdateOn, setIsUpdateOn] = useState(true);

	return (
		<Box xcss={wrapperStyles.root}>
			<Popup
				shouldRenderToParent
				isOpen={isOpen}
				onClose={() => setIsOpen(false)}
				content={(props) => <Values onUpdate={isUpdateOn ? props.update : noop} />}
				placement="right"
				trigger={(triggerProps) => (
					<Button
						{...triggerProps}
						appearance="primary"
						isSelected={isOpen}
						onClick={() => setIsOpen(!isOpen)}
					>
						Open popup
					</Button>
				)}
			/>
			<Box>
				<Text>Updates {isUpdateOn ? 'on' : 'off'}</Text>
				<Toggle
					size="large"
					label="Updates toggle switch controls"
					isChecked={isUpdateOn}
					onChange={(e) => setIsUpdateOn(e.currentTarget.checked)}
				/>
			</Box>
		</Box>
	);
};

export default PopupContentUpdateExample;

Customization

You can customize the popup using a component override with the popupComponent prop.

Make sure to forward the ref to the underlying DOM node, (opens new window), or the positioning of the popup won't work correctly.

Focus

Set focus

You can focus a specific element when opening a dialog popup. When role is "dialog" or "alertdialog", the content render props provide a ref setInitialFocusRef to be set on the desired element. Until platform-dst-top-layer is cleaned up, a role gated on that flag (fg('platform-dst-top-layer') ? 'dialog' : undefined) also gets it. Other roles do not get it: a menu or listbox has a fixed focus rule, and a popup with no role must not take focus. Give the dialog a label or a titleId. Only set focus to an element at the start of the popup, otherwise people who use assistive technology may miss the content.

The specified element needs to be available in the document as soon as the popup is opened, otherwise it will not be focused upon. This means it will not work for content that renders into the popup content after it has already opened, such as async or lazy loaded content. In those cases, you will need to manually set focus on the content once it is rendered.

Select a button to focus

NoneButton 1Button 2Button 3

Disable autofocus

If an element is focused, setting the autofocus prop to false will ensure it keeps focus when the popup is opened.

With the platform-dst-top-layer feature flag on, autoFocus has no effect and focus follows role. The dialog, alertdialog, menu and listbox roles move focus into the popup when it opens. To keep focus where it is, do not use one of these roles. One exception: if a focused combobox or text field controls the popup, focus stays on that field.

Surface detection

The current surface CSS variable is set to the surface color of the popup. You can use the utility.elevation.surface.current design token to style children with the current surface color.

A surface aware box - the background color depends on the surface it's placed on.

Content wrapping

By default, the popup content is rendered inside React.Portal. Use shouldRenderToParent prop to render the content directly after the trigger element.

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.

import { type KeyboardEvent, useEffect, useRef, useState } from 'react';

import { jsx } from '@compiled/react';

import Button from '@atlaskit/button/default/button';
import { cssMap } from '@atlaskit/css';
import { Popup } from '@atlaskit/popup/popup';
import { Box } from '@atlaskit/primitives/compiled/box';
import { Stack } from '@atlaskit/primitives/compiled/stack';
import { token } from '@atlaskit/tokens';

const contentStyles = cssMap({
	root: {
		paddingInlineStart: token('space.200'),
		paddingInlineEnd: token('space.200'),
		paddingBlockStart: token('space.200'),
		paddingBlockEnd: token('space.200'),
	},
});

const PopupWithRoleExample = (): JSX.Element => {
	const [isDialogOpen, setIsDialogOpen] = useState(false);
	const [isMenuOpen, setIsMenuOpen] = useState(false);
	const menuItemRefs = useRef<Array<HTMLButtonElement | null>>([]);
	const menuTriggerRef = useRef<HTMLButtonElement | null>(null);
	const closeMenu = () => {
		setIsMenuOpen(false);
		menuTriggerRef.current?.focus();
	};

	useEffect(() => {
		if (isMenuOpen) {
			menuItemRefs.current[0]?.focus();
		}
	}, [isMenuOpen]);

	const handleMenuItemKeyDown = (index: number) => (event: KeyboardEvent<HTMLButtonElement>) => {
		const menuItemCount = menuItemRefs.current.length;
		let nextIndex: number | undefined;

		switch (event.key) {
			case 'ArrowDown':
				nextIndex = (index + 1) % menuItemCount;
				break;
			case 'ArrowUp':
				nextIndex = (index - 1 + menuItemCount) % menuItemCount;
				break;
			case 'Home':
				nextIndex = 0;
				break;
			case 'End':
				nextIndex = menuItemCount - 1;
				break;
		}

		if (nextIndex !== undefined) {
			event.preventDefault();
			menuItemRefs.current[nextIndex]?.focus();
		}
	};

	return (
		<Stack alignInline="start" space="space.200">
			<Popup
				shouldRenderToParent
				isOpen={isDialogOpen}
				onClose={() => setIsDialogOpen(false)}
				placement="bottom-start"
				content={() => <Box xcss={contentStyles.root}>Content</Box>}
				role="dialog"
				label="Popup with role dialog example"
				trigger={(triggerProps) => (
					<Button
						{...triggerProps}
						appearance="primary"
						isSelected={isDialogOpen}
						onClick={() => setIsDialogOpen(!isDialogOpen)}
					>
						{isDialogOpen ? 'Close' : 'Open'} dialog popup
					</Button>
				)}
			/>
			<Popup
				// Prefer DropdownMenu for menus. Use Popup only for more complex interactions,
				// and ensure it meets applicable accessibility guidelines and expected menu behavior to prevent regressions.
				autoFocus={false}
				shouldRenderToParent
				isOpen={isMenuOpen}
				onClose={(event) => {
					if (
						event?.type === 'keydown' &&
						'key' in event &&
						(event.key === 'Escape' || event.key === 'Esc')
					) {
						menuTriggerRef.current?.focus();
					}
					setIsMenuOpen(false);
				}}
				placement="bottom-start"
				content={() => (
					<Stack alignInline="start" space="space.0">
						{['Edit', 'Delete'].map((item, index) => (
							<Button
								key={item}
								ref={(element) => {
									menuItemRefs.current[index] = element;
								}}
								onClick={closeMenu}
								onKeyDown={handleMenuItemKeyDown(index)}
								role="menuitem"
							>
								{item}
							</Button>
						))}
					</Stack>
				)}
				role="menu"
				label="Popup with role menu example"
				trigger={(triggerProps) => (
					<Button
						{...triggerProps}
						appearance="primary"
						isSelected={isMenuOpen}
						onClick={(event) => {
							menuTriggerRef.current = event.currentTarget;
							setIsMenuOpen(!isMenuOpen);
						}}
					>
						{isMenuOpen ? 'Close' : 'Open'} menu popup
					</Button>
				)}
			/>
		</Stack>
	);
};

export default PopupWithRoleExample;

Use DropdownMenu whenever possible: this example is not a blessed, production-ready menu pattern. If a complex interaction requires a Popup with role="menu", the consumer must implement the menu behavior. Give each action the appropriate menu-item role, move focus to a menu item when the menu opens, support Arrow Up, Arrow Down, Home, and End navigation, and return focus to the trigger when an action or Escape closes the menu. Preserve each menu item's native Enter and Space activation behavior. Validate the complete interaction with the assistive technologies and browser environments that the product supports. For the complete role and interaction requirements, refer to the WAI-ARIA menu role, (opens new window) and the ARIA Authoring Practices menu and menubar pattern, (opens new window).

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.

Was this page helpful?

We use this feedback to improve our documentation.