Message dialog

A dialog for displaying messages or asking for confirmation.

Usage

Code

Accessibility

Show message

  <sl-button>Show message</sl-button>
  <script type="module">
    import { MessageDialog } from '@sl-design-system/message-dialog';

    document.querySelector('sl-button')?.addEventListener('click', () => {
      MessageDialog.alert('This is a message dialog');
    });
  </script>

When to use

The message dialog should be used to present critical information or ask for decisions. For instance, when confirming a high-risk action (e.g., deleting data), a message dialog ensures user attention.

When not to use

The message dialog should not be used to present complex data or complex interactions. Keep them concise. If you have a need for complex interactions, consider using the dialog component.

You should also not use this component to interrupt the user unnecessarily. Only show a message dialog when the user explicitly triggers it and when there is no other alternative (for example an inline-message).

Show message

<sl-button>Show message</sl-button>
<script>
  document.querySelector('sl-button')?.addEventListener('click', () => {
    const result = await MessageDialog.show({
      title: 'Custom buttons',
      message: 'This is a message with custom buttons. Are you sure you want to press any buttons?',
      buttons: [
        { text: 'No, run away!', autofocus: true, fill: 'outline', value: 'NO', variant: 'primary' },
        { text: `Yes, I don't care what it does`, value: 'YES', variant: 'danger' }
      ]
    });

    if (result === 'YES') {
      // ...
    }
  });
</script>

Alert

The MessageDialog.alert() API is used to show a message dialog with a single "OK" button. Use this for informing the user about something important. Do not use this just for anything, as you are interrupting the workflow of the user.

By default, the alert dialog will have a title of "Alert". You can change that by passing a second parameter specifying the title.

The method returns a promise that resolves when the user clicks "OK" or cancels the dialog.

Confirm

The MessageDialog.confirm() API is used to show a message dialog with two buttons: "OK" and "Cancel". Use this for asking the user to confirm an action.

If you are using this, you probably want to customize the buttons further, since "Cancel" and "OK" are not very descriptive. If so, look at the MessageDialog.show() API below.

The method returns a promise that resolves with true if the user clicks "OK", false if the user clicks "Cancel" and undefined is the dialog is cancelled.

Show

The MessageDialog.show() API is the most flexible of the three. It allows you to pass a configuration object with the following properties:

title (string): The title of the dialog.
subtitle (string): The subtitle of the dialog.
message (string): The message of the dialog.
buttons (array): An array of button objects. Each button object can have the following properties:
- autofocus (boolean): Whether the button should get focus when the dialog opens.
- text (string): The text of the button.
- value (string): The value of the button. This is what will be returned when the button is clicked.
- variant (string): The variant of the button. This can be "primary", "success", "info", "warning", or "danger".
disableCancel (boolean): Determines whether the user can cancel the message dialog using the Escape key or by clicking on the backdrop.

The MessageDialog.show() API returns a promise that resolves with the value of the button that was clicked. This allows you to perform different actions based on the button that was clicked.

API

Properties

Name	Attribute	Type	Default	Description
`config`	-	`MessageDialogConfig<T> \| undefined`		The configuration of the message dialog.

Methods

Name	Parameters	Return	Description
`alert`	`message: stringtitle:`	`Promise<void>`	Shows an alert message to the user with an OK button by default.
`confirm`	`message: stringtitle:`		Shows a confirmation dialog to the user with OK and Cancel buttons by default.
`show`	`config: MessageDialogConfig<T>`		Shows a message dialog to the user. Use this method to display custom dialogs with any number of buttons.
`showModal`		`void`	Show the message dialog as a modal, in the top layer, with a backdrop.
`close`		`void`	Close the message dialog.

Role

The message dialog has a role of alertdialog by default, which is appropriate for a dialog that requires immediate attention from the user. This role is announced by screen readers and is used to indicate that the dialog is a modal dialog that requires immediate attention from the user.

Since the message dialog is just a utility built on top of the dialog component, it inherits all of the same keyboard interactions and WAI-ARIA attributes. See the dialog accessibility page for more information.

Interactive example