Modal

Synonyms: dialogue, prompt

Using the Modal component, additional information or input forms can be displayed in a dialog window. An open modal can be closed via ESC. The Modal component is hidden by default. It is usually only displayed after clicking on a button or other trigger. The background of the window is deactivated and only the content of the modal window is active.

How it works

The Modal creates the basis for barrier-free overlays and makes it possible to display any HTML content. For example, a Dialog component would be a composition of a Card component inserted into a Modal component.

As soon as a modal is opened, all selectable elements in the website are deactivated, except those within the active modal.

Construction

Code

<kol-modal id="test-modal" _label="Beschreibung zur Modalbox">
 <kol-card _label="Vorgang löschen">
  <div>
   <p>Wollen Sie den Vorgang wirklich löschen?</p>
   <kol-button class="close-modal" _label="Ok" _variant="primary"></kol-button>
   <kol-button class="close-modal" _label="Abbrechen"></kol-button>
  </div>
 </kol-card>
</kol-modal>

<kol-button id="modal-open-button" _label="Modal öffnen"></kol-button>

<script>
 const modal = document.querySelector('#test-modal');
 const modalOpenButton = document.querySelector('#modal-open-button');

 document.querySelectorAll('.close-modal').forEach((buttonElement) => {
  buttonElement._on = {
   onClick: () => modal.closeModal(),
  };
 });
 modalOpenButton._on = { onClick: () => modal.openModal() };
</script>

Events

For the handling of events or callbacks, see .

Event	trigger	Value
close	Component is closing	-

Usage

Use the _width attribute to specify the desired width of the modal box. It is always displayed in the middle of the screen in the selected size.

Since the modal is decoupled from the actual page content but provides partial blocking of the content, it must also provide a way to enable closing (unblocking) from the modal context.

Es wird empfohlen einen Close-Button oben rechts einzubauen.

To open the modal you can use openModal method using a DOM reference, to close closeModal.

Best practices

• Use the modal box to display further information on a topic.
• Use Modalbox to make large content visually more compact.
• Avoid placing important information such as legal topics that users need to respond to in modal boxes.

Use cases

• Use the modal box to help explain individual input fields in forms.
• Use the modal box to display additional information only after the user requests it.
• Use the modal box to display feedback on save processes or similar, e.g. Thank you for your feedback after submitting a form.

Accessibility

The standard optical output of the component is optimized to implement accessibility. If you use your own custom styles, this may limit accessibility.

The modal is implemented so that the focus is on it when it is opened. Elements outside the modal can then no longer be focused.

For optimal output of the Modal component in screen readers, make sure to set the aria-label attribute correctly.

Furthermore, there is only ever a maximum of one active modal, which deactivates all selectable elements except those within its own modal. It is important to note that KoliBri only disables elements that are in the browser side area. Focusing the browser menu is still possible.

Keyboard controls

button	Function
Tab	When the modal is open, all focusable elements are jumped to in order.
ESC	Closes the modal.

Links and references

Overview

https://en.wikipedia.org/wiki/Modal_window

Properties

Property	Attribute	Description	Type	Default
_label (required)	_label	Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.).	string	undefined
_on	--	Defines the modal callback functions.	undefined | ({ onClose?: (() => void) | undefined; })	undefined
_variant	_variant	Defines the variant of the modal.	"blank" | "card" | undefined	'blank'
_width	_width	Defines the width of the modal. (max-width: 100%)	string | undefined	'100%'

Methods

closeModal

closeModal() => Promise<void>

Closes the modal dialog.

Returns

Type: Promise<void>

openModal() => Promise<void>

Opens the modal dialog.

Returns

Type: Promise<void>

Slots

Slot	Description
	The modal's contents.

---

View example