Modal

Ein Modal zeigt Inhalte zentriert als Overlay über der Hauptseite.

import {
  Action,
  ActionGroup,
  Button,
  Content,
  Heading,
  Label,
  Modal,
  ModalTrigger,
  Section,
  Text,
  TextField,
} from "@mittwald/flow-react-components";
import { sleepLong } from "@/content/04-components/actions/action/examples/lib";

<ModalTrigger>
  <Button>Modal öffnen</Button>
  <Modal>
    <Heading>Organisation anlegen</Heading>
    <Content>
      <Section>
        <Text>
          Eine Organisation kannst du dir wie ein
          Unternehmen vorstellen. An diesem Ort verwaltest
          du deine Mitarbeiter, Zahlungsmodalitäten und
          kannst deine Rechnungen einsehen.
        </Text>
        <TextField isRequired>
          <Label>Organisationsname</Label>
        </TextField>
      </Section>
    </Content>
    <ActionGroup>
      <Action closeModal>
        <Action onAction={sleepLong}>
          <Button color="accent">
            Organisation anlegen
          </Button>
        </Action>
        <Button variant="soft" color="secondary">
          Abbrechen
        </Button>
      </Action>
    </ActionGroup>
  </Modal>
</ModalTrigger>

Best Practices

Öffne ein Modal nur als Reaktion auf eine bewusste Aktion des Nutzers. Ein unerwartet erscheinendes Modal unterbricht ihn und zieht sofort seine gesamte Aufmerksamkeit auf sich.
Nutze für umfangreiche Prozesse ein OffCanvas. Ein Modal bleibt so kurz und fokussiert.
Formuliere eine prägnante Überschrift und halte den Inhalt leicht verständlich.
Vermeide es, mehrere Modals übereinander zu stapeln. Ein Modal über einem anderen ist im Einzelfall vertretbar, doch mit jeder weiteren Ebene verliert der Nutzer die Orientierung.

OffCanvas

Nutze die Variante OffCanvas für Modals mit viel Inhalt, bei dem gescrollt werden müsste.

Sizes

Ein Modal mit der Size Small (Breite 660 px) eignet sich gut für einfache Abfragen oder Bestätigungsmodals. Ein Modal mit der Size Medium (Breite 900 px) wird für komplexere Dialoge verwendet.

Ungespeicherte Änderungen

Eingaben in einem Modal gehen beim Schließen verloren. Damit das nicht unbemerkt passiert, kann bei Escape oder einem Klick außerhalb des Modals zuerst ein Bestätigungs-Dialog erscheinen. Aktionen im Footer und der Close-Button in der Überschrift schließen dagegen sofort.

Enthält das Modal eine Form (React Hook Form), passiert das automatisch, sobald sie ungespeicherte Änderungen enthält. Ohne Form – oder wenn du selbst entscheiden willst, wann es etwas zu verlieren gibt – setzt du confirmOnClose.

Show CloseButton

Standardmäßig wird der Close-Button in der Überschrift ausgeblendet, sobald das Modal eine <ActionGroup /> enthält – die Aktionen im Footer übernehmen dann das Schließen. Über das showCloseButton Property lässt sich das überschreiben.

Controller

Neben dem <ModalTrigger /> kann das Modal auch über einen Controller gesteuert werden.

Dieser Controller steht auch in Modals zur Verfügung, die über den ModalTrigger geöffnet wurden.

Kombiniere mit …

React Hook Form

Weitere Details zur Formularlogik und -validierung findest du in der Component Form (React Hook Form).

Properties

Property	Type	Default	Description
`size`	`"s" \| "m" \| "l"`	"s"	The size of the modal.
`offCanvas`	`boolean`	-	Whether the modal should be displayed as an off canvas.
`offCanvasOrientation`	`"left" \| "right"`	"right"	Whether the off canvas should be displayed on the right or left side of the screen.
`controller`	`OverlayController`	-	An overlay controller to control the modal state.
`slot`	`string`	-	Accepts "actionConfirm" to use the modal as a confirmation modal for an action.
`isDismissable`	`boolean`	-	Whether the modal can be closed by clicking outside of it.
`showCloseButton`	`boolean`	-	Whether the close button should be visible
`confirmOnClose`	`boolean`	-	Whether closing the modal must be confirmed – use it to protect unsaved changes.
`children`	`ReactNode`	-
`wrapWith`	`ReactElement<unknown, string \| JSXElementConstructor<any>>`	-	A React element the component is wrapped with. The element is cloned and receives the component as its only child — useful to render the component inside a link, a tooltip trigger or any other wrapper without changing the surrounding markup.
`ref`	`Ref<HTMLSpanElement>`	-	Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref). @see React Docs
`key`	`Key`	-
`className`	`string`	-	The elements class name.
`isOpen`	`boolean`	-	Whether the overlay is open. Use it to control the overlay state.
`isDefaultOpen`	`boolean`	false	Whether the overlay is open initially. Use it for an uncontrolled overlay.

Events

Property	Type	Default	Description
`onOpenChange`	`OverlayOpenStateHandler`	-	Called with the new open state whenever the overlay is opened or closed.
`onClose`	`OverlayCloseHandler`	-	Called when the overlay is closed.
`onOpen`	`OverlayOpenHandler`	-	Called when the overlay is opened.

Components

Integrations