Modal

Modal dialogs interrupt a user by isolating information that needs to be acted upon. They are often triggered by an action a user took, and should be used to inform, confirm or complete a task.

Table of contents

• How to use Modal
• Code examples
• Content recommendations
• Accessibility

How to use Modal

• Use modal dialogs to request information critical for a user to continue their current process
• Use modal dialogs to warn users about a potentially destructive action they are taking
• Use modal dialogs consistently across use cases
• Do not use modal dialogs for nonessential information that is not related to the current user flow
• Avoid modal dialogs that interrupt high-stake processes such as checkout flows

Code examples

The Modal component can be configured in a number of different ways. Use this guidance to determine when to use certain variations:

Basic example

function ModalExample() {
  const [isShown, setShown] = React.useState(false);
  return (
    <React.Fragment>
      <Button onClick={() => setShown(true)}>Show centered modal</Button>
      <Modal title="Centered modal" isShown={isShown}>
        {() => (
          <React.Fragment>
            <Modal.Header title="Title" onClose={() => setShown(false)} />
            <Modal.Content>Hello from controlled modal window</Modal.Content>
            <Modal.Controls>
              <Button buttonType="positive" onClick={() => setShown(false)}>
                Confirm
              </Button>
              <Button buttonType="muted" onClick={() => setShown(false)}>
                Close
              </Button>
            </Modal.Controls>
          </React.Fragment>
        )}
      </Modal>
    </React.Fragment>
  );
}
function ModalExample() {
  const [isShown, setShown] = React.useState(false);
  return (
    <React.Fragment>
      <Button onClick={() => setShown(true)}>Show centered modal</Button>
      <Modal title="Centered modal" isShown={isShown}>
        {() => (
          <React.Fragment>
            <Modal.Header title="Title" onClose={() => setShown(false)} />
            <Modal.Content>Hello from controlled modal window</Modal.Content>
            <Modal.Controls>
              <Button buttonType="positive" onClick={() => setShown(false)}>
                Confirm
              </Button>
              <Button buttonType="muted" onClick={() => setShown(false)}>
                Close
              </Button>
            </Modal.Controls>
          </React.Fragment>
        )}
      </Modal>
    </React.Fragment>
  );
}
Hide source

Modal position (position)

function ModalExample() {
  const [isShown, setShown] = React.useState(false);
  const [position, setPosition] = React.useState('top');
  return (
    <React.Fragment>
      <Form>
        <FieldGroup row>
          <Button
            buttonType="positive"
            onClick={() => {
              setPosition('top');
              setShown(true);
            }}
          >
            Show top modal
          </Button>
          <Button
            onClick={() => {
              setPosition('center');
              setShown(true);
            }}
          >
            Show center modal
          </Button>
        </FieldGroup>
      </Form>
      <Modal title="Centered modal" isShown={isShown} position={position}>
        {() => (
          <React.Fragment>
            <Modal.Header title="Title" onClose={() => setShown(false)} />
            <Modal.Content>Hello from controlled modal window</Modal.Content>
            <Modal.Controls>
              <Button buttonType="positive" onClick={() => setShown(false)}>
                Confirm
              </Button>
              <Button buttonType="muted" onClick={() => setShown(false)}>
                Close
              </Button>
            </Modal.Controls>
          </React.Fragment>
        )}
      </Modal>
    </React.Fragment>
  );
}
function ModalExample() {
  const [isShown, setShown] = React.useState(false);
  const [position, setPosition] = React.useState('top');
  return (
    <React.Fragment>
      <Form>
        <FieldGroup row>
          <Button
            buttonType="positive"
            onClick={() => {
              setPosition('top');
              setShown(true);
            }}
          >
            Show top modal
          </Button>
          <Button
            onClick={() => {
              setPosition('center');
              setShown(true);
            }}
          >
            Show center modal
          </Button>
        </FieldGroup>
      </Form>
      <Modal title="Centered modal" isShown={isShown} position={position}>
        {() => (
          <React.Fragment>
            <Modal.Header title="Title" onClose={() => setShown(false)} />
            <Modal.Content>Hello from controlled modal window</Modal.Content>
            <Modal.Controls>
              <Button buttonType="positive" onClick={() => setShown(false)}>
                Confirm
              </Button>
              <Button buttonType="muted" onClick={() => setShown(false)}>
                Close
              </Button>
            </Modal.Controls>
          </React.Fragment>
        )}
      </Modal>
    </React.Fragment>
  );
}
Hide source

Modal sizes (size)

function ModalExample() {
  const [isShown, setShown] = React.useState(false);
  const [size, setSize] = React.useState('medium');
  return (
    <React.Fragment>
      <Form>
        <SelectField
          onChange={(e) => {
            setSize(e.target.value);
          }}
          labelText="Select a width"
        >
          <Option value="small">small</Option>
          <Option value="medium">medium</Option>
          <Option value="large">large</Option>
          <Option value="fullWidth">full width</Option>
          <Option value="200px">200px (specific width value)</Option>
        </SelectField>
        <Button
          onClick={() => {
            setShown(true);
          }}
        >
          Show modal
        </Button>
      </Form>
      <Modal title="Centered modal" isShown={isShown} size={size}>
        {() => (
          <React.Fragment>
            <Modal.Header title="Title" onClose={() => setShown(false)} />
            <Modal.Content>Hello from controlled modal window</Modal.Content>
            <Modal.Controls>
              <Button buttonType="positive" onClick={() => setShown(false)}>
                Confirm
              </Button>
              <Button buttonType="muted" onClick={() => setShown(false)}>
                Close
              </Button>
            </Modal.Controls>
          </React.Fragment>
        )}
      </Modal>
    </React.Fragment>
  );
}
function ModalExample() {
  const [isShown, setShown] = React.useState(false);
  const [size, setSize] = React.useState('medium');
  return (
    <React.Fragment>
      <Form>
        <SelectField
          onChange={(e) => {
            setSize(e.target.value);
          }}
          labelText="Select a width"
        >
          <Option value="small">small</Option>
          <Option value="medium">medium</Option>
          <Option value="large">large</Option>
          <Option value="fullWidth">full width</Option>
          <Option value="200px">200px (specific width value)</Option>
        </SelectField>
        <Button
          onClick={() => {
            setShown(true);
          }}
        >
          Show modal
        </Button>
      </Form>
      <Modal title="Centered modal" isShown={isShown} size={size}>
        {() => (
          <React.Fragment>
            <Modal.Header title="Title" onClose={() => setShown(false)} />
            <Modal.Content>Hello from controlled modal window</Modal.Content>
            <Modal.Controls>
              <Button buttonType="positive" onClick={() => setShown(false)}>
                Confirm
              </Button>
              <Button buttonType="muted" onClick={() => setShown(false)}>
                Close
              </Button>
            </Modal.Controls>
          </React.Fragment>
        )}
      </Modal>
    </React.Fragment>
  );
}
Hide source

Content recommendations

• Practice progressive disclosure. Eliminate extra details to keep copy concise and actionable
• Focus on the objective of the modal dialog. Start each sentence with the objective when possible
• To enable users to navigate quickly, write concise sentences that are easy to understand at a glance
• Limit the number of concepts in each sentence. Write simple sentences for all audiences
• To keep UX copy actionable use present tense for user interactions
• Avoid “never,” “always” and other absolutes
• Use contractions when possible
• Avoid exclamation marks

Accessibility

Missing