Default Gray Amethyst

Dialog

<mo-dialog> | MODialog
Since 1.0 stable

‘Dialogs, sometimes called “modals”, appear above the page and require the user″s immediate attention.’

You are about to confirm an action. Close Open Dialog 
<mo-dialog label="Are you sure you want to confirm this?" class="dialog-overview">
  You are about to confirm an action.
  <mo-button slot="footer" variant="primary">Close</mo-button>
</mo-dialog>

<mo-button>Open Dialog</mo-button>

<script>
  const dialog = document.querySelector('.dialog-overview');
  const openButton = dialog.nextElementSibling;
  const closeButton = dialog.querySelector('mo-button[slot="footer"]');

  openButton.addEventListener('click', () => dialog.show());
  closeButton.addEventListener('click', () => dialog.hide());
</script>

import { useState } from 'react';
import { MOButton, MODialog } from '@metsooutotec/modes-web-components/dist/react';

const App = () => {
  const [open, setOpen] = useState(false);

  return (
    <>
      <MODialog label="Are you sure you want to confirm this?" open={open} onMoAfterHide={() => setOpen(false)}>
        Lorem ipsum dolor sit amet, consectetur adipiscing elit.
        <MOButton slot="footer" variant="primary" onClick={() => setOpen(false)}>
          Close
        </MOButton>
      </MODialog>

      <MOButton onClick={() => setOpen(true)}>Open Dialog</MOButton>
    </>
  );
};

UX tips

  • Use a dialog when you immediately require the user’s attention, e.g. confirming a destructive action.
  • Always provide an obvious way for the user to dismiss the dialog.
  • Don’t nest dialogs. It almost always leads to a poor experience for the user.

Examples

Custom width

Use the --width custom property to set the dialog’s width.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Close Open Dialog 
<mo-dialog label="Dialog" class="dialog-width" style="--width: 50vw;">
  Lorem ipsum dolor sit amet, consectetur adipiscing elit.
  <mo-button slot="footer" variant="primary">Close</mo-button>
</mo-dialog>

<mo-button>Open Dialog</mo-button>

<script>
  const dialog = document.querySelector('.dialog-width');
  const openButton = dialog.nextElementSibling;
  const closeButton = dialog.querySelector('mo-button[slot="footer"]');

  openButton.addEventListener('click', () => dialog.show());
  closeButton.addEventListener('click', () => dialog.hide());
</script>

import { useState } from 'react';
import { MOButton, MODialog } from '@metsooutotec/modes-web-components/dist/react';

const App = () => {
  const [open, setOpen] = useState(false);

  return (
    <>
      <MODialog label="Dialog" open={open} style={{ '--width': '50vw' }} onMoAfterHide={() => setOpen(false)}>
        Lorem ipsum dolor sit amet, consectetur adipiscing elit.
        <MOButton slot="footer" variant="primary" onClick={() => setOpen(false)}>
          Close
        </MOButton>
      </MODialog>

      <MOButton onClick={() => setOpen(true)}>Open Dialog</MOButton>
    </>
  );
};

Scrolling

By design, a dialog’s height will never exceed that of the viewport. As such, dialogs will not scroll with the page ensuring the header and footer are always accessible to the user.

Scroll down and give it a try! 👇

Close Open Dialog 
<mo-dialog label="Dialog" class="dialog-scrolling">
  <div style="height: 150vh; border: dashed 2px var(--color-neutral-200); padding: 0 1rem;">
    <p>Scroll down and give it a try! 👇</p>
  </div>
  <mo-button slot="footer" variant="primary">Close</mo-button>
</mo-dialog>

<mo-button>Open Dialog</mo-button>

<script>
  const dialog = document.querySelector('.dialog-scrolling');
  const openButton = dialog.nextElementSibling;
  const closeButton = dialog.querySelector('mo-button[slot="footer"]');

  openButton.addEventListener('click', () => dialog.show());
  closeButton.addEventListener('click', () => dialog.hide());
</script>

import { useState } from 'react';
import { MOButton, MODialog } from '@metsooutotec/modes-web-components/dist/react';

const App = () => {
  const [open, setOpen] = useState(false);

  return (
    <>
      <MODialog label="Dialog" open={open} onMoAfterHide={() => setOpen(false)}>
        <div
          style={{
            height: '150vh',
            border: 'dashed 2px var(--color-neutral-200)',
            padding: '0 1rem'
          }}
        >
          <p>Scroll down and give it a try! 👇</p>
        </div>

        <MOButton slot="footer" variant="primary" onClick={() => setOpen(false)}>
          Close
        </MOButton>
      </MODialog>

      <MOButton onClick={() => setOpen(true)}>Open Dialog</MOButton>
    </>
  );
};

Preventing the dialog from closing

By default, dialogs will close when the user clicks the close button, clicks the overlay, or presses the Escape key. In most cases, the default behavior is the best behavior in terms of UX. However, there are situations where this may be undesirable, such as when data loss will occur.

To keep the dialog open in such cases, you can cancel the mo-request-close event. When canceled, the dialog will remain open and pulse briefly to draw the user’s attention to it.

You can use event.detail.source to determine what triggered the request to close. This example prevents the dialog from closing when the overlay is clicked, but allows the close button or Escape to dismiss it.

This dialog will not close when you click on the overlay. Close Open Dialog 
<mo-dialog label="Dialog" class="dialog-deny-close">
  This dialog will not close when you click on the overlay.
  <mo-button slot="footer" variant="primary">Close</mo-button>
</mo-dialog>

<mo-button>Open Dialog</mo-button>

<script>
  const dialog = document.querySelector('.dialog-deny-close');
  const openButton = dialog.nextElementSibling;
  const closeButton = dialog.querySelector('mo-button[slot="footer"]');

  openButton.addEventListener('click', () => dialog.show());
  closeButton.addEventListener('click', () => dialog.hide());

  // Prevent the dialog from closing when the user clicks on the overlay
  dialog.addEventListener('mo-request-close', event => {
    if (event.detail.source === 'overlay') {
      event.preventDefault();
    }
  });
</script>

import { useState } from 'react';
import { MOButton, MODialog } from '@metsooutotec/modes-web-components/dist/react';

const App = () => {
  const [open, setOpen] = useState(false);

  // Prevent the dialog from closing when the user clicks on the overlay
  function handleRequestClose(event) {
    if (event.detail.source === 'overlay') {
      event.preventDefault();
    }
  }

  return (
    <>
      <MODialog label="Dialog" open={open} onMoRequestClose={handleRequestClose} onMoAfterHide={() => setOpen(false)}>
        This dialog will not close when you click on the overlay.
        <MOButton slot="footer" variant="primary" onClick={() => setOpen(false)}>
          Close
        </MOButton>
      </MODialog>

      <MOButton onClick={() => setOpen(true)}>Open Dialog</MOButton>
    </>
  );
};

Customizing initial focus

By default, the dialog’s panel will gain focus when opened. This allows a subsequent tab press to focus on the first tabbable element in the dialog. If you want a different element to have focus, add the autofocus attribute to it as shown below.

Close Open Dialog 
<mo-dialog label="Dialog" class="dialog-focus">
  <mo-input autofocus placeholder="I will have focus when the dialog is opened"></mo-input>
  <mo-button slot="footer" variant="primary">Close</mo-button>
</mo-dialog>

<mo-button>Open Dialog</mo-button>

<script>
  const dialog = document.querySelector('.dialog-focus');
  const input = dialog.querySelector('mo-input');
  const openButton = dialog.nextElementSibling;
  const closeButton = dialog.querySelector('mo-button[slot="footer"]');

  openButton.addEventListener('click', () => dialog.show());
  closeButton.addEventListener('click', () => dialog.hide());
</script>

import { useState } from 'react';
import { MOButton, MODialog, MOInput } from '@metsooutotec/modes-web-components/dist/react';

const App = () => {
  const [open, setOpen] = useState(false);

  return (
    <>
      <MODialog label="Dialog" open={open} onMoAfterHide={() => setOpen(false)}>
        <MOInput autofocus placeholder="I will have focus when the dialog is opened" />
        <MOButton slot="footer" variant="primary" onClick={() => setOpen(false)}>
          Close
        </MOButton>
      </MODialog>

      <MOButton onClick={() => setOpen(true)}>Open Dialog</MOButton>
    </>
  );
};

Importing

If you’re using the autoloader or the traditional loader, you can ignore this section. Otherwise, feel free to use any of the following snippets to cherry pick this component.

Bundler React Script

To import this component using a bundler:

import '@metsooutotec/modes-web-components/dist/components/dialog/dialog.js';

To import this component as a React component:

import MODialog from '@metsooutotec/modes-web-components/dist/react/dialog/';

To import this component using a script tag:

<script type="module" src="https://modes-web.metso.com/dist/components/cdn/components/dialog/dialog.js"></script>

Slots

Name Description
(default) The dialog’s content.
label The dialog’s label. Alternatively, you can use the label prop.
footer The dialog’s footer, usually one or more buttons representing various options.

Learn more about using slots.

Properties

Name Description Reflects Type Default
open Indicates whether or not the dialog is open. You can use this in lieu of the show/hide methods. boolean false
label The dialog’s label as displayed in the header. You should always include a relevant label even when using no-header, as it is required for proper accessibility. string ''
noHeader
no-header 		Disables the header. This will also remove the default close button, so please ensure you provide an easy, accessible way for users to dismiss the dialog. boolean false
updateComplete A read-only promise that resolves when the component has finished updating.

Learn more about attributes and properties.

Events

Name React Event Description Event Detail
mo-show onMoShow Emitted when the dialog opens. -
mo-after-show onMoAfterShow Emitted after the dialog opens and all animations are complete. -
mo-hide onMoHide Emitted when the dialog closes. -
mo-after-hide onMoAfterHide Emitted after the dialog closes and all animations are complete. -
mo-initial-focus onMoInitialFocus Emitted when the dialog opens and is ready to receive focus. Calling event.preventDefault() will prevent focusing and allow you to set it on a different element, such as an input. -
mo-request-close onMoRequestClose Emitted when the user attempts to close the dialog by clicking the close button, clicking the overlay, or pressing escape. Calling event.preventDefault() will keep the dialog open. Avoid using this unless closing the dialog will result in destructive behavior such as data loss. { source: 'close-button' | 'keyboard' | 'overlay' }

Learn more about events.

Methods

Name Description Arguments
show() Shows the dialog. -
hide() Hides the dialog -

Learn more about methods.

Custom Properties

Name Description Default
--width The preferred width of the dialog. Note that the dialog will shrink to accommodate smaller screens.
--header-spacing The amount of padding to use for the header.
--body-spacing The amount of padding to use for the body.
--footer-spacing The amount of padding to use for the footer.

Learn more about customizing CSS custom properties.

Parts

Name Description
base The component’s internal wrapper.
overlay The overlay.
panel The dialog panel (where the dialog and its content is rendered).
header The dialog header.
title The dialog title.
close-button The close button.
close-button__base The close button’s base part.
body The dialog body.
footer The dialog footer.

Learn more about customizing CSS parts.

Animations

Name Description
dialog.show The animation to use when showing the dialog.
dialog.hide The animation to use when hiding the dialog.
dialog.denyClose The animation to use when a request to close the dialog is denied.
dialog.overlay.show The animation to use when showing the dialog’s overlay.
dialog.overlay.hide The animation to use when hiding the dialog’s overlay.

Learn more about customizing animations.

Dependencies

This component automatically imports the following dependencies.