What does the component do?

A dialogue is an overlay that overlays the main content of the page and presents a focused interaction or important information until users have completed the action or closed the dialogue.

When should the component be used?

• To convey important information or confirmations to users.
• To prompt users to take an action before continuing with the main content of the page.
• To display complex forms or content that should not be integrated into the main page.

Rules

• A dialogue should be reduced as much as possible and focus on a single task/information or a single form.
• The dialogue should be easy to close, either by a close button or by clicking outside the dialogue.
• If no actions are defined in the dialogue footer, users must always be able to close the dialogue.
• Dialogues can also always be closed with the ESC key.

Playground

The sbb-dialog component provides a way to present content on top of the app's content mainly to interact with the user.

The component creates a backdrop to prevent interaction with content behind the modal, disables page scrolling while open,
manages focus by setting it to the first focusable element, and automatically adds the appropriate ARIA roles.

The dialog should always consist of a title and content. Optionally, a close button and actions can be provided.

<sbb-dialog>
  <sbb-dialog-title>Title</sbb-dialog-title>
  <sbb-dialog-content>Dialog content.</sbb-dialog-content>
</sbb-dialog>

Slots

Consumers don't need to directly assign any slots; the dedicated components take care of assigning the correct slot.

The component supports slotting the sbb-dialog-title, sbb-dialog-close-button, sbb-dialog-content and an sbb-dialog-actions elements.

<sbb-dialog>
  <sbb-dialog-title>Title</sbb-dialog-title>
  <sbb-dialog-close-button></sbb-dialog-close-button>
  <sbb-dialog-content>Dialog content.</sbb-dialog-content>
  <sbb-dialog-actions>
    <sbb-secondary-button sbb-dialog-close>Cancel</sbb-secondary-button>
    <sbb-button sbb-dialog-close sbb-focus-initial>Confirm</sbb-button>
  </sbb-dialog-actions>
</sbb-dialog>

Interactions

To display the dialog, a trigger can be connected via the trigger property,
or the open() method on the sbb-dialog component can be called.

<sbb-button id="dialog-trigger">Open dialog</sbb-button>

<sbb-dialog trigger="dialog-trigger">
  <sbb-dialog-title>Title</sbb-dialog-title>
  <sbb-dialog-content>Dialog content.</sbb-dialog-content>
  <sbb-dialog-actions><sbb-button sbb-dialog-close>Close</sbb-button></sbb-dialog-actions>
</sbb-dialog>

Closing the dialog

The dialog can be closed in several ways:

1. Close button: Add an <sbb-dialog-close-button> component to provide a dedicated close button.
   This is recommended for dialogs with complex content.

   <sbb-dialog>
     <sbb-dialog-title>Title</sbb-dialog-title>
     <sbb-dialog-close-button></sbb-dialog-close-button>
     <sbb-dialog-content>Dialog content.</sbb-dialog-content>
   </sbb-dialog>
   

2. sbb-dialog-close attribute: Add the sbb-dialog-close attribute to any element within the dialog
   (typically buttons in the actions section) to close the dialog when clicked. You can optionally provide a result value:

   <sbb-dialog>
     <sbb-dialog-title>Title</sbb-dialog-title>
     <sbb-dialog-content>Dialog content.</sbb-dialog-content>
     <sbb-dialog-actions>
       <sbb-secondary-button sbb-dialog-close="cancel">Cancel</sbb-secondary-button>
       <sbb-button sbb-dialog-close="confirm">Confirm</sbb-button>
     </sbb-dialog-actions>
   </sbb-dialog>
   

   Alternatively, you can use the assignDialogResult() helper to programmatically assign a complex result to an element:

   import { assignDialogResult } from '@sbb-esta/lyne-elements/dialog.js';
   
   const confirmButton = document.querySelector('sbb-button');
   assignDialogResult(confirmButton, { action: 'confirm', otherProp: 'any value' });
   

3. Backdrop click: By default, clicking on the backdrop will close the dialog.
   This behavior can be disabled by setting backdrop-action="none".

4. Escape key: Pressing the Esc key will close the dialog.

5. Programmatically: Call the close(result?: any) method on the sbb-dialog element.
   This method closes the dialog and emits beforeclose and close events with the provided result as a payload.

   const dialog = document.querySelector('sbb-dialog');
   dialog.close({ confirmed: true });
   

Handling close events

When the dialog closes, it emits two events:

• beforeclose: Emitted before the closing transition begins. This event is cancelable by calling event.preventDefault().
• close: Emitted after the dialog has fully closed.

Both events are of type SbbDialogCloseEvent and provide access to:

• result: The result value passed to close(), assigned via assignDialogResult(), or the value of the sbb-dialog-close attribute
• closeTarget: The element that triggered the close action (e.g., the clicked button), or null if closed programmatically or via Escape key

dialog.addEventListener('close', (event) => {
  console.log('Result:', event.result);
  console.log('Close target:', event.closeTarget);
});

Style

It's possible to display the component in negative variant using the self-named property.

<sbb-dialog negative>
  <sbb-dialog-title>Title</sbb-dialog-title>
  <sbb-dialog-content>Dialog content.</sbb-dialog-content>
</sbb-dialog>

Accessibility

We recommend to place at maximum two actions in the sbb-dialog-actions component.
More elements can potentially confuse users.

If there is more complex content than just a simple text / question, we recommend to slot the sbb-dialog-close-button.
This either provides an initial focus at the dialog start and also provides as a second exit possibility.

Controlling initial focus

The first element with the attribute sbb-focus-initial will receive focus on opening.
If the attribute is not used, the first focusable element receives focus.
In case there is no sbb-dialog-close-button and complex content,
there should be a focusable element at the dialog start, e.g. the title itself.
This prevents screen reader users having to navigate backwards from the dialog actions.

Focus restoration

When closed, the dialog restores focus to the element that previously held focus when the
dialog opened by default. However, focus restoration can be disabled
by setting the skipFocusRestoration property to true.
As this is an accessibility feature, it is recommended to focus
an alternative element by listening to the didClose event.

Properties

Methods

Events

CSS Properties

Slots