Modal

Diese Dokumentation wird aktuell überarbeitet und befindet sich im Beta-Status. Inhalte können sich noch ändern.

Diese Komponente wird erneut auf Barrierefreiheit getestet. Der vollständige Test steht noch aus und kann erst nach einem abgeschlossenen Release erfolgen.

Synonyme: Dialog, Overlay, Popup

Beschreibung: Die Modal-Komponente stellt eine barrierefreie Overlay-Basis bereit, um beliebige HTML-Inhalte in einem modalen Fenster anzuzeigen. Sie deaktiviert beim Öffnen alle Elemente außerhalb des Modals und implementiert automatisch Fokus-Management sowie Tastatursteuerung. Das Modal wird standardmäßig versteckt und über Methoden (openModal(), closeModal()) oder Callbacks gesteuert.

⚠️ Deprecated: Diese Komponente ist zugunsten der veraltet, die verbesserte Barrierefreiheit und Konformität mit der HTML-Spezifikation bietet.

Beispiel

Darstellung der Komponente mit Beschriftung und Inhaltsbereich. Der Button öffnet das Modal, das Modal-Content kann beliebige HTML-Elemente enthalten.

preview.component.modal.content

<KolModal _label="preview.component.modal.label" ><p>preview.component.modal.content</p></KolModal>

Barrierefreiheit

Das Modal implementiert umfangreiche Barrierefreiheits-Features:

• Fokus-Sperrung: Beim Öffnen wird der Fokus auf das Modal gesetzt; Elemente außerhalb sind nicht mehr fokussierbar, bis das Modal geschlossen wird.
• Label-Pflicht: Das Attribut _label definiert die Beschriftung für Screenreader und sollte sinnvoll gesetzt sein.
• Maximal ein aktives Modal: Es gibt immer nur ein aktives Modal, alle selektierbaren Elemente außerhalb werden deaktiviert außer den Elementen im Modal selbst.
• Tastatursteuerung: Vollständig navigation mit Tab und ESC zum Schließen.
• Browser-Menü bleibt zugänglich: KoliBri deaktiviert nur Elemente im Seiten-Inhaltsbereich, nicht im Browser-Menü.

Links und Referenzen

Verwendung

Tastatursteuerung

Taste	Funktion
Tab	Navigiert durch die fokussierbaren Elemente innerhalb des geöffneten Modals.
Shift + Tab	Navigiert rückwärts durch die fokussierbaren Elemente.
ESC	Schließt das Modal.

Best Practices / Empfehlungen

• Verwenden Sie ein Modal, um weiterführende oder zusätzliche Informationen zu einem Thema anzuzeigen.
• Nutzen Sie ein Modal, um Inhalte optisch kompakter zu gestalten und Platz im Hauptseiten-Bereich zu sparen.
• Vermeiden Sie, kritische oder rechtliche Informationen ausschließlich in Modalen zu platzieren, wenn Nutzer:innen darauf reagieren müssen.
• Integrieren Sie einen gut sichtbaren Close-Button (z.B. oben rechts oder unten in einer Fußzeile), um das Schließen einfach zu machen.
• Nutzen Sie die Methoden openModal() und closeModal() über DOM-Referenzen, um das Modal programmatisch zu steuern.
• Setzen Sie die _width auf einen für den Inhalt sinnvollen Wert (z.B. 500px, 80%); das Modal wird immer zentriert angezeigt.

Anwendungsfälle

• Detaillierte Informationen oder Erklärungen zu Eingabefeldern in Formularen
• Ergänzende Inhalte, die erst auf Anforderung der Nutzer:innen angezeigt werden
• Bestätigungsmeldungen oder Feedback nach Formulareingaben (z.B. „Vielen Dank für Ihre Rückmeldung")
• Konfiguration oder Einstellungen, die sich deutlich vom Hauptinhalt unterscheiden
• Warnungen oder wichtige Mitteilungen, die Aufmerksamkeit erfordern

Konstruktion / Technik

Playground

preview.component.modal.content

<KolModal _label="preview.component.modal.label" ><p>preview.component.modal.content</p></KolModal>

Funktionalitäten (mit Code)

Beschriftung und Inhalt

Die Beschriftung wird über _label gesetzt und stellt den Titel/die Identifikation des Modals dar. Der Inhaltsbereich wird über den Standard-Slot befüllt.

preview.component.modal.content

<KolModal _label="preview.component.modal.label" ><p>preview.component.modal.content</p></KolModal>

Breite des Modals

Die Breite wird über das Attribut _width gesteuert (Standard: 100%). Das Modal wird immer zentriert auf dem Bildschirm angezeigt.

preview.component.modal.content

<KolModal _label="preview.component.modal.label" _width="500px" ><p>preview.component.modal.content</p></KolModal>

Varianten

Das Attribut _variant definiert die Variante des Modals (blank oder card).

preview.component.modal.content

<KolModal _label="preview.component.modal.label" _variant="card" ><p>preview.component.modal.content</p></KolModal>

Events

Zur Behandlung von Events bzw. Callbacks siehe .

Event	Auslöser	Value
close	Modal wird via closeModal() oder ESC-Taste geschlossen	-

API

[DEPRECATED] Use kol-dialog instead.

Overview

The Modal component has been superseded by kol-dialog, which provides improved accessibility and conforms to the HTML dialog specification. It is still available in version 2 for backwards compatibility.

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.

---