Modal

import { ... } from '@ag.ds-next/react/modal';

() => {
	const [isModalOpen, openModal, closeModal] = useTernaryState(false);
	return (
		<React.Fragment>
			<Button onClick={openModal}>Open modal</Button>
			<Modal
				isOpen={isModalOpen}
				onClose={closeModal}
				title="This is the title of the modal dialog, it can span lines but should not be too long."
				actions={
					<ButtonGroup>
						<Button onClick={closeModal}>Primary button</Button>
						<Button variant="secondary" onClick={closeModal}>
							Secondary button
						</Button>
						<Button variant="tertiary" onClick={closeModal}>
							Tertiary button
						</Button>
					</ButtonGroup>
				}
			>
				<Text as="p">
					This is the Modal Body paragraph, it provides detailed instruction and
					context for the the modal action. It can also span lines but long form
					content should be avoided.
				</Text>
			</Modal>
		</React.Fragment>
	);
};

Modals advise users an action may be destructive, detrimental or irreversible. They are triggered by a user interaction and announce important or critical information that requires a decision. For other uses, other patterns are preferred.

Modals require a clear explanation of what will happen if the user proceeds, an alternative option, and an easy way to dismiss.

The user must act or dismiss the modal before they can return to the parent page.

The Primary button should support the user to achieve what they initially elected to do – for example, cancel out of a form.

Do

• use to confirm a destructive action – for example, when cancelling a form and user input will be lost
• use modals to inform people if:
  • an account or information is about to be deleted
  • work or data is about to be lost
  • an error will occur
  • of a cost increase
• use sparingly as they disrupt the user flow
• make sure the modal experience is a brief interaction with no more than two action buttons and a dismiss option (X in the top right corner)
• use a Button or Button group for actions
• include a Close button in the top right corner
• ensure the modal closes when the action is completed.

Don’t

• change the Button group order
• remove the Close button
• change default behaviour
• use a Modal to explain why a user cannot continue in a flow. Use PageAlert instead
• use to guiding navigation patterns unless the outcome will result in lost data
• embed forms in a modal
• use for error, success or loading messages.

Related components

• Drawer – A drawer is a panel that slides in from the right side of the screen. The Drawer is overlayed on top of the main area of the page to capture the user’s attention while keeping the context of the current task.