## Content modal

The `<ContentModal />` is a modal dialog component that you can either use as is, or customise to your need. It is used for short and non-frequent tasks, such as viewing or submitting additional information, or to change aspects of the application.

Below is the most basic example of a content modal; passing only a text string to the `header` prop, and an object defining the button labels/actions to the [`controls`](#controls) prop, as well as `children` (also referred to as the modal body or modal content).

```tsx live
const [isOpen, setIsOpen] = useState(false);
const toggle = () => setIsOpen((prevIsOpen) => !prevIsOpen);

const controls: ControlsProps = {
  confirm: { label: 'Confirm', onClick: toggle, tone: 'primary' },
  cancel: { label: 'Cancel', onClick: toggle, tone: 'ghost' },
};

return (
  <>
    <Button label="Open basic ContentModal" onClick={toggle} tone="neutral" />

    <ContentModal
      isOpen={isOpen}
      onClose={toggle}
      header="Modal title"
      controls={controls}
      ariaDescribedBy="content-modal-description-1"
    >
      <p id="content-modal-description-1">Content modal body</p>
    </ContentModal>
  </>
);
```

### Custom header and footer

In the same way you can pass anything to the modal body (as `children`), you can also customise the `header` and/or `footer` by passing in your own component.

NOTE: You cannot use the `controls` and `footer` props at the same time. Use the `footer` if you need a custom appearance or more complex functionality.

```tsx live
const [isOpen, setIsOpen] = useState(false);
const toggle = () => setIsOpen((prevIsOpen) => !prevIsOpen);

const customHeader = (
  <Flex flexDirection="column" padding="large" gap="xsmall">
    <Text color="neutralSubtle" fontSize="small" lineHeight="nospace" id="custom-header-description-1">
      Custom text
    </Text>
    <Text fontSize="medium" fontWeight="bold" lineHeight="tight" id="custom-header-label-1">
      Custom modal header
    </Text>
  </Flex>
);

const customFooter = (
  <Flex justifyContent="space-between" alignItems="center" padding="large">
    <Button label="Need help?" onClick={toggle} tone="neutral" />
    <Flex gap="xsmall">
      <Button tone="ghost" label="Cancel" onClick={toggle} />
      <Button tone="primary" label="Confirm" onClick={toggle} />
    </Flex>
  </Flex>
);

return (
  <>
    <Button label="Open custom ContentModal" onClick={toggle} tone="neutral" />

    <ContentModal
      isOpen={isOpen}
      onClose={toggle}
      header={customHeader}
      footer={customFooter}
      ariaLabelledBy="custom-header-label-1"
      ariaDescribedBy="custom-header-description-1"
    >
      <Flex flexDirection="column">
        <Field label="Label 1">
          <TextInput />
        </Field>
        <Field label="Label 2">
          <TextInput />
        </Field>
        <Field label="Label 3">
          <TextInput />
        </Field>
      </Flex>
    </ContentModal>
  </>
);
```

### Max width

Use the optional `maxWidth` prop to set the maximum width of the `<ContentModal />`. If no value is provided it defaults to `47.5rem`. It also supports the [responsive prop syntax](/foundations/responsive-layouts/#responsive-prop-syntax).

The example below illustrates a use case where a modal stretching the full width of viewport is needed, so the `maxWidth` has been set to `100vw`.

```tsx live
const [isOpen, setIsOpen] = useState(false);
const toggle = () => setIsOpen((prevIsOpen) => !prevIsOpen);

const controls: ControlsProps = {
  confirm: { label: 'Confirm', onClick: toggle, tone: 'primary' },
  cancel: { label: 'Cancel', onClick: toggle, tone: 'ghost' },
};

return (
  <>
    <Button label="Open full-width ContentModal" tone="neutral" onClick={toggle} />

    <ContentModal
      maxWidth="100vw"
      header="Full-width modal example"
      controls={controls}
      isOpen={isOpen}
      onClose={toggle}
    >
      Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore
      magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
      consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
      Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
    </ContentModal>
  </>
);
```

## Alert modal

The `<AlertModal />` is used to display a message that the user needs to acknowledge or confirm. It accepts `title`, `description` and `controls` – along with other inherited [props](/packages/modal/props#alert-modal).

As a general rule, titles should be phrased as a short question so that the action is easy and clear to make. Descriptions should also be kept succinct and in as very few words, describe the changes or consequences being made to the system.

Alert modals should be used sparingly due to them requiring the user to make an action before they can return to the application.

### Confirm

Use the "confirm"-pattern when you need to confirm significant user decisions. Both the title and the primary button should reflect the action that will occur. The description should clearly describe the action being confirmed and explain any potential consequences that it may cause.

NOTE: Use `critical` tone on the `confirm`-control if the alert describes destructive or irreversible actions, e.g. where an action would result in significant data loss if done accidentally.

```tsx live
const [isOpen, setIsOpen] = useState(false);
const toggle = () => setIsOpen((prevIsOpen) => !prevIsOpen);

const [isOpenCritical, setIsOpenCritical] = useState(false);
const toggleCritical = () => setIsOpenCritical((prevIsOpen) => !prevIsOpen);

const controls: ControlsProps = {
  confirm: { label: 'Yes, edit', onClick: toggle },
  cancel: { label: 'Cancel', onClick: toggle, tone: 'ghost' },
};

const controlsCritical: ControlsProps = {
  confirm: { label: 'Yes, delete', onClick: toggleCritical, tone: 'critical' },
  cancel: { label: 'Cancel', onClick: toggleCritical, tone: 'ghost' },
};

return (
  <>
    <Flex gap="small">
      <Button label="Confirm something" tone="neutral" onClick={toggle} />
      <Button label="Confirm something critical" tone="neutral" onClick={toggleCritical} />
    </Flex>

    <AlertModal
      title="Edit course details?"
      description="If you continue, the course you've selected will be reverted to a draft."
      controls={controls}
      isOpen={isOpen}
      onClose={toggle}
    />

    <AlertModal
      title="Delete course?"
      description="This action is permanent and cannot be reversed."
      controls={controlsCritical}
      isOpen={isOpenCritical}
      onClose={toggleCritical}
    />
  </>
);
```

### Acknowledge

Use the "acknowledge"-pattern when you need the user to acknowledge something important, such as a change in the system, or a new feature. They are provided with a single action to confirm that they have acknowledged the message.

```tsx live
const [isOpen, setIsOpen] = useState(false);
const toggle = () => setIsOpen((prevIsOpen) => !prevIsOpen);

const controls: ControlsProps = {
  confirm: { label: 'Okay, got it', onClick: toggle },
};

return (
  <>
    <Button label="Acknowledge something" tone="neutral" onClick={toggle} />

    <AlertModal
      title="System update"
      description="We have made some recent changes to improve the experience of the learning module."
      controls={controls}
      isOpen={isOpen}
      onClose={toggle}
    />
  </>
);
```

## Content drawer

The `<ContentDrawer />` is a dialog component that slides in from the left or right. Use it to show related content, definitions, or a short task without taking the user away from the current page.

```tsx live
const [isOpen, setIsOpen] = useState(false);
const toggle = () => setIsOpen((prevIsOpen) => !prevIsOpen);

const footerControls: ContentDrawerProps['footerControls'] = [{ label: 'Confirm', onClick: toggle, tone: 'primary' }];

return (
  <>
    <Button label="Open drawer" onClick={toggle} tone="neutral" />

    <ContentDrawer footerControls={footerControls} isOpen={isOpen} onClose={toggle} title="Drawer title">
      <Text>
        Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore
        magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
        consequat.
      </Text>
    </ContentDrawer>
  </>
);
```

### Footer controls

Controls can be placed at the bottom of the drawer using the `footerControls` prop. Footer controls span the full width of the drawer.

```tsx live
const [isOpen, setIsOpen] = useState(false);
const toggle = () => setIsOpen((prevIsOpen) => !prevIsOpen);

const footerControls: ContentDrawerProps['footerControls'] = [
  { label: 'Confirm', onClick: toggle, tone: 'primary' },
  { label: 'Cancel', onClick: toggle, tone: 'ghost' },
];

return (
  <>
    <Button label="Open drawer with footer controls" onClick={toggle} tone="neutral" />

    <ContentDrawer footerControls={footerControls} isOpen={isOpen} onClose={toggle} title="Drawer with footer controls">
      <Text>Drawer content</Text>
    </ContentDrawer>
  </>
);
```

### Max width

Use the optional `maxWidth` prop to set the maximum width of the `<ContentDrawer />`. If no value is provided it defaults to `25rem`. It also supports the [responsive prop syntax](/foundations/responsive-layouts/#responsive-prop-syntax).

### Disable outside dismiss

By default, the drawer closes when the user clicks on the backdrop. Use `disableOutsideDismiss` to prevent this behaviour.

### Hidden title

If header controls need more space, use `hideTitle` to visually hide the title. You must still provide a `title` so it can be announced by screen readers.

## Controls

Use the `controls` prop – in both `<ContentModal />` and `<AlertModal />` – to define how to render the buttons in the modal and what should happen when they are triggered.

It accepts two keys; `confirm` and `cancel`(optional). The `confirm` key represents the primary action of the modal. The `cancel` key represents the secondary action (typically labelled "Cancel"), but is optional in case you don't need it, e.g. in an "Acknowledge alert modal".

Each key accepts another object in which you define the button's `label` and `onClick`, and optionally `loading` and `tone`.

NOTE: To ensure correct typing, import and declare `ControlsProps` as the type for your controls.

```ts
// import { ControlsProps } from '@eds/modal';

const onClickHandler = console.info;

const controls: ControlsProps = {
  confirm: { label: 'Yes, delete', onClick: onClickHandler, tone: 'critical' },
  cancel: { label: 'Cancel', onClick: onClickHandler, tone: 'ghost' },
};
```

## Disable outside dismiss

By default, both `<ContentModal />` and `<AlertModal />` can be dismissed by clicking outside the modal (on the backdrop). Use the `disableOutsideDismiss` prop to prevent this behaviour when you need to ensure the user explicitly interacts with the modal's controls.

```tsx live
const [isOpen, setIsOpen] = useState(false);
const toggle = () => setIsOpen((prevIsOpen) => !prevIsOpen);

const controls: ControlsProps = {
  confirm: { label: 'Confirm', onClick: toggle, tone: 'primary' },
  cancel: { label: 'Cancel', onClick: toggle, tone: 'ghost' },
};

return (
  <>
    <Button label="Open non-dismissable modal" tone="neutral" onClick={toggle} />

    <ContentModal header="Important action" controls={controls} isOpen={isOpen} onClose={toggle} disableOutsideDismiss>
      <Text>This modal cannot be dismissed by clicking outside. You must use the buttons.</Text>
    </ContentModal>
  </>
);
```

## Restore focus

By default, when a modal or drawer closes, focus is restored to the element that had focus before it opened. Use the `restoreFocusTo` prop to restore focus to a specific element instead. This prop accepts a React ref object and works with `<ContentModal />`, `<AlertModal />`, and `<ContentDrawer />`.

```tsx live
const [isOpen, setIsOpen] = useState(false);
const buttonRef = useRef<HTMLButtonElement>(null);
const toggle = () => setIsOpen((prevIsOpen) => !prevIsOpen);

const controls: ControlsProps = {
  confirm: { label: 'Done', onClick: toggle },
};

return (
  <ActionsGroup>
    <Button label="Open Modal" onClick={toggle} tone="primary" />
    <Button ref={buttonRef} label="I will receive focus when the modal closes" tone="neutral" />

    <ContentModal isOpen={isOpen} onClose={toggle} header="Modal title" controls={controls} restoreFocusTo={buttonRef}>
      <p>Modal content</p>
    </ContentModal>
  </ActionsGroup>
);
```

## Overflowing content

The height of the content in the modal body (`children`) will make the modal's height grow until it hits the height of the viewport, after which it automatically make the overflowing content scrollable.

```tsx live
const [isOpen, setIsOpen] = useState(false);
const toggle = () => setIsOpen((prevIsOpen) => !prevIsOpen);

const controls: ControlsProps = {
  confirm: { label: 'Done', onClick: toggle },
};

return (
  <>
    <Button label="Open overflowing modal" tone="neutral" onClick={toggle} />

    <ContentModal header="Overflowing content modal" isOpen={isOpen} controls={controls} onClose={toggle}>
      {Array.from({ length: 50 }).map((_, key) => (
        <Text key={key}>
          Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore
          magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
          consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
          pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id
          est laborum.
        </Text>
      ))}
    </ContentModal>
  </>
);
```

Modals focus the user's attention exclusively on one task or piece of information via a window that sits in front of the page content.

Modal

Accessibility

Responsive layouts

Tokens

Foundations

a11y

Accordion

Actions

AddressInput

AppLayout

Avatar

Badge

Blanket

Breadcrumbs

BulkActionBar

Button

Card

Checkbox

Core

DateDropdown

DateInput

Divider

EmptyState

Field

Fieldset

FileInput

Filtering

Flex

Grid

Heading

Icon

Illustration

Link

List

Loading

Notice

PageHeader

Pagination

PhoneInput

Popover

Radio

RailTrack

RichTextEditor

ScrollWrap

SearchInput

SelectDropdown

SelectInput

ShowMore

Table

Tabs

Text

TextAreaInput

TextInput

Toast

Toggle

Tooltip

Utils

Utils - NextJS

Components

Forms

Search

Tables

Patterns

Introduction

Product tone and voice

Capitalisation

Date and time

Inclusive design

Content

Welcome to EDS

Start designing

Start developing

Contributing

Releases

The EDS way

Coding style guide

Guide to Pendo

Setting up the EDS repo

Creating a new component

Automated testing

PR and changeset process

Publishing snapshots

Publishing packages

Monorepo tools

Team resources

AlertModal

ContentModal

ContentDrawer