Dialogs

Dialogs inform users about a task and can contain critical information, require decisions, or involve multiple tasks.

A Dialog is a type of modal window that appears in front of app content to provide critical information or ask for a decision. Dialogs disable all app functionality when they appear, and remain on screen until confirmed, dismissed, or a required action has been taken.

Dialogs are purposefully interruptive, so they should be used sparingly.

Simple Dialogs

Simple dialogs can provide additional details or actions about a list item. For example, they can display avatars, icons, clarifying subtext, or orthogonal actions (such as adding an account).

Touch mechanics:

Choosing an option immediately commits the option and closes the menu
Touching outside of the dialog, or pressing Back, cancels the action and closes the dialog

class SimpleDialogDemo extends React.Component {
  constructor(props) {
    super(props);

    this.handleClickOpen = this.handleClickOpen.bind(this);
    this.handleClose = this.handleClose.bind(this);

    this.state = {
      open: false,
      selectedValue: null,
    };
  }

  handleClickOpen() {
    this.setState({
      open: true,
    });
  }

  handleClose(value) {
    const setVal = typeof value === 'string' ? value : this.state.selectedValue;
    this.setState({ selectedValue: setVal, open: false });
  }

  render() {
    const emails = ['username@gmail.com', 'user02@gmail.com'];

    return (
      <div>
        <Typography variant="subtitle1">Selected: {this.state.selectedValue}</Typography>
        <br />
        <Button variant="outlined" onClick={this.handleClickOpen}>
          Open simple dialog
        </Button>

        <Dialog
          onClose={this.handleClose}
          aria-labelledby="simple-dialog-title"
          open={this.state.open}
        >
          <DialogTitle id="simple-dialog-title">Set backup account</DialogTitle>
          <div>
            <List>
              {emails.map((email) => (
                <ListItem button onClick={() => this.handleClose(email)} key={email}>
                  <ListItemAvatar>
                    <Avatar style={{ backgroundColor: 'blue', color: '#fff' }}>
                      <Person />
                    </Avatar>
                  </ListItemAvatar>
                  <ListItemText primary={email} />
                </ListItem>
              ))}
              <ListItem button onClick={() => this.handleClose('addAccount')}>
                <ListItemAvatar>
                  <Avatar color="neutral">
                    <Add />
                  </Avatar>
                </ListItemAvatar>
                <ListItemText primary="add account" />
              </ListItem>
            </List>
          </div>
        </Dialog>
      </div>
    );
  }
}

class SimpleDialogDemo extends React.Component {
  constructor(props) {
    super(props);

    this.handleClickOpen = this.handleClickOpen.bind(this);
    this.handleClose = this.handleClose.bind(this);

    this.state = {
      open: false,
      selectedValue: null,
    };
  }

  handleClickOpen() {
    this.setState({
      open: true,
    });
  }

  handleClose(value) {
    const setVal = typeof value === 'string' ? value : this.state.selectedValue;
    this.setState({ selectedValue: setVal, open: false });
  }

  render() {
    const emails = ['username@gmail.com', 'user02@gmail.com'];

    return (
      <div>
        <Typography variant="subtitle1">Selected: {this.state.selectedValue}</Typography>
        <br />
        <Button variant="outlined" onClick={this.handleClickOpen}>
          Open simple dialog
        </Button>

        <Dialog
          onClose={this.handleClose}
          aria-labelledby="simple-dialog-title"
          open={this.state.open}
        >
          <DialogTitle id="simple-dialog-title">Set backup account</DialogTitle>
          <div>
            <List>
              {emails.map((email) => (
                <ListItem button onClick={() => this.handleClose(email)} key={email}>
                  <ListItemAvatar>
                    <Avatar style={{ backgroundColor: 'blue', color: '#fff' }}>
                      <Person />
                    </Avatar>
                  </ListItemAvatar>
                  <ListItemText primary={email} />
                </ListItem>
              ))}
              <ListItem button onClick={() => this.handleClose('addAccount')}>
                <ListItemAvatar>
                  <Avatar color="neutral">
                    <Add />
                  </Avatar>
                </ListItemAvatar>
                <ListItemText primary="add account" />
              </ListItem>
            </List>
          </div>
        </Dialog>
      </div>
    );
  }
}

Alerts

Alerts are urgent interruptions, requiring acknowledgement, that inform the user about a situation.

Most alerts don't need titles. They summarize a decision in a sentence or two by either:

Asking a question (e.g. "Delete this conversation?")

Making a statement related to the action buttons
Use title bar alerts only for high-risk situations, such as the potential loss of connectivity. Users should be able to understand the choices based on the title and button text alone.

If a title is required:

Use a clear question or statement with an explanation in the content area, such as "Erase USB storage?".
Avoid apologies, ambiguity, or questions, such as “Warning!” or “Are you sure?”

Note: Text-only simple alerts may require manual focus management upon the dialog becoming visible. Examine the demo to see how <RootRef> is used to trigger focus on the <DialogTitle>.

class AlertDialog extends React.Component {
  constructor(props) {
    super(props);

    this.handleClickOpen = this.handleClickOpen.bind(this);
    this.handleOnEntered = this.handleOnEntered.bind(this);
    this.handleClose = this.handleClose.bind(this);

    this.dialogRef = React.createRef();

    this.state = {
      open: false,
    };
  }

  handleClickOpen() {
    this.setState({
      open: true,
    });
  }

  handleOnEntered() {
    this.dialogRef.current.focus();
  }

  handleClose(value) {
    this.setState({ open: false });
  }

  render() {
    const dialogFocused = this.state.focused ? -1 : null;
    return (
      <div>
        <Button variant="outlined" onClick={this.handleClickOpen}>
          Open alert dialog
        </Button>

        <Dialog
          open={this.state.open}
          onClose={this.handleClose}
          onEntered={this.handleOnEntered}
          aria-labelledby="alert-dialog-title"
          aria-describedby="alert-dialog-description"
        >
          <RootRef rootRef={this.dialogRef}>
            <DialogTitle id="alert-dialog-title" disableTypography={true} tabIndex={-1}>
              <Typography variant="h3">Use Google's location service?</Typography>
            </DialogTitle>
          </RootRef>
          <DialogContent>
            <DialogContentText id="alert-dialog-description">
              Let Google help apps determine location. This means sending anonymous location data to
              Google, even when no apps are running.
            </DialogContentText>
          </DialogContent>
          <DialogActions>
            <Button onClick={this.handleClose}>Agree</Button>
            <Button onClick={this.handleClose} variant="text">
              Disagree
            </Button>
          </DialogActions>
        </Dialog>
      </div>
    );
  }
}

class AlertDialog extends React.Component {
  constructor(props) {
    super(props);

    this.handleClickOpen = this.handleClickOpen.bind(this);
    this.handleOnEntered = this.handleOnEntered.bind(this);
    this.handleClose = this.handleClose.bind(this);

    this.dialogRef = React.createRef();

    this.state = {
      open: false,
    };
  }

  handleClickOpen() {
    this.setState({
      open: true,
    });
  }

  handleOnEntered() {
    this.dialogRef.current.focus();
  }

  handleClose(value) {
    this.setState({ open: false });
  }

  render() {
    const dialogFocused = this.state.focused ? -1 : null;
    return (
      <div>
        <Button variant="outlined" onClick={this.handleClickOpen}>
          Open alert dialog
        </Button>

        <Dialog
          open={this.state.open}
          onClose={this.handleClose}
          onEntered={this.handleOnEntered}
          aria-labelledby="alert-dialog-title"
          aria-describedby="alert-dialog-description"
        >
          <RootRef rootRef={this.dialogRef}>
            <DialogTitle id="alert-dialog-title" disableTypography={true} tabIndex={-1}>
              <Typography variant="h3">Use Google's location service?</Typography>
            </DialogTitle>
          </RootRef>
          <DialogContent>
            <DialogContentText id="alert-dialog-description">
              Let Google help apps determine location. This means sending anonymous location data to
              Google, even when no apps are running.
            </DialogContentText>
          </DialogContent>
          <DialogActions>
            <Button onClick={this.handleClose}>Agree</Button>
            <Button onClick={this.handleClose} variant="text">
              Disagree
            </Button>
          </DialogActions>
        </Dialog>
      </div>
    );
  }
}

Form Dialogs

Form dialogs allow users to fill out form fields within a dialog. For example, if your site prompts for potential subscribers to fill in their email address, they can fill out the email field and touch 'Submit'

class AlertDialog extends React.Component {
  constructor(props) {
    super(props);

    this.handleClickOpen = this.handleClickOpen.bind(this);
    this.handleClose = this.handleClose.bind(this);

    this.state = {
      open: false,
    };
  }

  handleClickOpen() {
    this.setState({
      open: true,
    });
  }

  handleClose() {
    this.setState({ open: false });
  }

  render() {
    return (
      <div>
        <Button variant="outlined" onClick={this.handleClickOpen}>
          Open form dialog
        </Button>
        <Dialog
          open={this.state.open}
          onClose={this.handleClose}
          aria-labelledby="form-dialog-title"
          aria-describedby="form-dialog-description"
        >
          <DialogTitle id="form-dialog-title">Subscribe</DialogTitle>
          <DialogContent>
            <DialogContentText id="form-dialog-description" gutterBottom>
              To subscribe to this website, please enter your email address here. We will send
              updates occasionally.
            </DialogContentText>
            <TextField
              autoFocus
              margin="dense"
              id="name"
              label="Email Address"
              type="email"
              fullWidth
            />
          </DialogContent>
          <DialogActions>
            <Button onClick={this.handleClose}>Subscribe</Button>
            <Button onClick={this.handleClose} variant="text">
              Cancel
            </Button>
          </DialogActions>
        </Dialog>
      </div>
    );
  }
}

class AlertDialog extends React.Component {
  constructor(props) {
    super(props);

    this.handleClickOpen = this.handleClickOpen.bind(this);
    this.handleClose = this.handleClose.bind(this);

    this.state = {
      open: false,
    };
  }

  handleClickOpen() {
    this.setState({
      open: true,
    });
  }

  handleClose() {
    this.setState({ open: false });
  }

  render() {
    return (
      <div>
        <Button variant="outlined" onClick={this.handleClickOpen}>
          Open form dialog
        </Button>
        <Dialog
          open={this.state.open}
          onClose={this.handleClose}
          aria-labelledby="form-dialog-title"
          aria-describedby="form-dialog-description"
        >
          <DialogTitle id="form-dialog-title">Subscribe</DialogTitle>
          <DialogContent>
            <DialogContentText id="form-dialog-description" gutterBottom>
              To subscribe to this website, please enter your email address here. We will send
              updates occasionally.
            </DialogContentText>
            <TextField
              autoFocus
              margin="dense"
              id="name"
              label="Email Address"
              type="email"
              fullWidth
            />
          </DialogContent>
          <DialogActions>
            <Button onClick={this.handleClose}>Subscribe</Button>
            <Button onClick={this.handleClose} variant="text">
              Cancel
            </Button>
          </DialogActions>
        </Dialog>
      </div>
    );
  }
}

Full-Screen Dialogs

class AlertDialog extends React.Component {
  constructor(props) {
    super(props);

    this.handleClickOpen = this.handleClickOpen.bind(this);
    this.handleClose = this.handleClose.bind(this);

    this.state = {
      open: false,
    };
  }

  transition(props) {
    return <Slide direction="up" {...props} />;
  }

  handleClickOpen() {
    this.setState({
      open: true,
    });
  }

  handleClose() {
    this.setState({ open: false });
  }

  render() {
    return (
      <div>
        <Button variant="outlined" onClick={this.handleClickOpen}>
          Open full-screen dialog
        </Button>
        <Dialog
          fullScreen
          open={this.state.open}
          onClose={this.handleClose}
          TransitionComponent={this.transition}
          aria-labelledby="fullscreen-dialog-title"
        >
          <AppBar style={{ position: 'relative' }}>
            <Toolbar>
              <IconButton color="inherit" onClick={this.handleClose} aria-label="Close">
                <Close />
              </IconButton>
              <Typography id="fullscreen-dialog-title" variant="h6" color="inherit">
                Sound
              </Typography>
              <Button
                variant="text"
                color="inherit"
                onClick={this.handleClose}
                margin={{ left: 'auto' }}
              >
                Save
              </Button>
            </Toolbar>
          </AppBar>
          <List>
            <ListItem button>
              <ListItemText primary="Phone ringtone" secondary="Titania" />
            </ListItem>
            <Divider />
            <ListItem button>
              <ListItemText primary="Default notification ringtone" secondary="Tethys" />
            </ListItem>
          </List>
        </Dialog>
      </div>
    );
  }
}

class AlertDialog extends React.Component {
  constructor(props) {
    super(props);

    this.handleClickOpen = this.handleClickOpen.bind(this);
    this.handleClose = this.handleClose.bind(this);

    this.state = {
      open: false,
    };
  }

  transition(props) {
    return <Slide direction="up" {...props} />;
  }

  handleClickOpen() {
    this.setState({
      open: true,
    });
  }

  handleClose() {
    this.setState({ open: false });
  }

  render() {
    return (
      <div>
        <Button variant="outlined" onClick={this.handleClickOpen}>
          Open full-screen dialog
        </Button>
        <Dialog
          fullScreen
          open={this.state.open}
          onClose={this.handleClose}
          TransitionComponent={this.transition}
          aria-labelledby="fullscreen-dialog-title"
        >
          <AppBar style={{ position: 'relative' }}>
            <Toolbar>
              <IconButton color="inherit" onClick={this.handleClose} aria-label="Close">
                <Close />
              </IconButton>
              <Typography id="fullscreen-dialog-title" variant="h6" color="inherit">
                Sound
              </Typography>
              <Button
                variant="text"
                color="inherit"
                onClick={this.handleClose}
                margin={{ left: 'auto' }}
              >
                Save
              </Button>
            </Toolbar>
          </AppBar>
          <List>
            <ListItem button>
              <ListItemText primary="Phone ringtone" secondary="Titania" />
            </ListItem>
            <Divider />
            <ListItem button>
              <ListItemText primary="Default notification ringtone" secondary="Tethys" />
            </ListItem>
          </List>
        </Dialog>
      </div>
    );
  }
}

Optional Sizes

You can set a dialog maximum width by using the maxWidth enumerable in combination with the fullWidth boolean. When the fullWidth property is true, the dialog will adapt based on the maxWidth value.

class MaxWidthDialog extends React.Component {
  constructor(props) {
    super(props);

    this.handleClickOpen = this.handleClickOpen.bind(this);
    this.handleClose = this.handleClose.bind(this);

    this.state = {
      open: false,
      fullWidth: true,
      maxWidth: 'sm',
    };
  }

  handleClickOpen() {
    this.setState({ open: true });
  }

  handleClose() {
    this.setState({ open: false });
  }

  handleMaxWidthChange(event) {
    this.setState({ maxWidth: event.target.value });
  }

  handleFullWidthChange(event) {
    this.setState({ fullWidth: event.target.checked });
  }

  render() {
    return (
      <React.Fragment>
        <Button variant="outlined" onClick={this.handleClickOpen}>
          Open max-width dialog
        </Button>
        <Dialog
          fullWidth={this.state.fullWidth}
          maxWidth={this.state.maxWidth}
          open={this.state.open}
          onClose={this.handleClose}
          aria-labelledby="max-width-dialog-title"
        >
          <DialogTitle id="max-width-dialog-title" disableTypography>
            <Typography variant="h3">Optional sizes</Typography>
          </DialogTitle>
          <DialogContent>
            <DialogContentText>
              You can set my maximum width and whether to adapt or not.
            </DialogContentText>
            <form
              noValidate
              style={{
                display: 'flex',
                flexDirection: 'column',
                margin: '1em auto 0',
                width: 'fit-content',
              }}
            >
              <FormControl style={{ minWidth: 120, marginTop: '8px' }}>
                <InputLabel htmlFor="max-width">maxWidth</InputLabel>
                <Select
                  value={this.state.maxWidth}
                  onChange={(event) => this.handleMaxWidthChange(event)}
                  inputProps={{
                    name: 'max-width',
                    id: 'max-width',
                  }}
                >
                  <MenuItem value={false}>false</MenuItem>
                  <MenuItem value="xs">xs</MenuItem>
                  <MenuItem value="sm">sm</MenuItem>
                  <MenuItem value="md">md</MenuItem>
                  <MenuItem value="lg">lg</MenuItem>
                  <MenuItem value="xl">xl</MenuItem>
                </Select>
              </FormControl>
              <FormControlLabel
                margin={{ top: 1 }}
                control={
                  <Switch
                    checked={this.state.fullWidth}
                    onChange={(event) => this.handleFullWidthChange(event)}
                    value="fullWidth"
                  />
                }
                label="Full width"
              />
            </form>
          </DialogContent>
          <DialogActions>
            <Button onClick={this.handleClose}>Close</Button>
          </DialogActions>
        </Dialog>
      </React.Fragment>
    );
  }
}

class MaxWidthDialog extends React.Component {
  constructor(props) {
    super(props);

    this.handleClickOpen = this.handleClickOpen.bind(this);
    this.handleClose = this.handleClose.bind(this);

    this.state = {
      open: false,
      fullWidth: true,
      maxWidth: 'sm',
    };
  }

  handleClickOpen() {
    this.setState({ open: true });
  }

  handleClose() {
    this.setState({ open: false });
  }

  handleMaxWidthChange(event) {
    this.setState({ maxWidth: event.target.value });
  }

  handleFullWidthChange(event) {
    this.setState({ fullWidth: event.target.checked });
  }

  render() {
    return (
      <React.Fragment>
        <Button variant="outlined" onClick={this.handleClickOpen}>
          Open max-width dialog
        </Button>
        <Dialog
          fullWidth={this.state.fullWidth}
          maxWidth={this.state.maxWidth}
          open={this.state.open}
          onClose={this.handleClose}
          aria-labelledby="max-width-dialog-title"
        >
          <DialogTitle id="max-width-dialog-title" disableTypography>
            <Typography variant="h3">Optional sizes</Typography>
          </DialogTitle>
          <DialogContent>
            <DialogContentText>
              You can set my maximum width and whether to adapt or not.
            </DialogContentText>
            <form
              noValidate
              style={{
                display: 'flex',
                flexDirection: 'column',
                margin: '1em auto 0',
                width: 'fit-content',
              }}
            >
              <FormControl style={{ minWidth: 120, marginTop: '8px' }}>
                <InputLabel htmlFor="max-width">maxWidth</InputLabel>
                <Select
                  value={this.state.maxWidth}
                  onChange={(event) => this.handleMaxWidthChange(event)}
                  inputProps={{
                    name: 'max-width',
                    id: 'max-width',
                  }}
                >
                  <MenuItem value={false}>false</MenuItem>
                  <MenuItem value="xs">xs</MenuItem>
                  <MenuItem value="sm">sm</MenuItem>
                  <MenuItem value="md">md</MenuItem>
                  <MenuItem value="lg">lg</MenuItem>
                  <MenuItem value="xl">xl</MenuItem>
                </Select>
              </FormControl>
              <FormControlLabel
                margin={{ top: 1 }}
                control={
                  <Switch
                    checked={this.state.fullWidth}
                    onChange={(event) => this.handleFullWidthChange(event)}
                    value="fullWidth"
                  />
                }
                label="Full width"
              />
            </form>
          </DialogContent>
          <DialogActions>
            <Button onClick={this.handleClose}>Close</Button>
          </DialogActions>
        </Dialog>
      </React.Fragment>
    );
  }
}

Dialogs

Simple Dialogs

Alerts

Form Dialogs

Full-Screen Dialogs

Optional Sizes

Properties

<Dialog />

<DialogActions />

<DialogContent />

<DialogContentText />

<DialogTitle />