Modal
BasicOverlays
<co-modal>Modal asks for input or a decision in a centered dialog: form, confirm and destructive kinds.
import { Modal } from 'health-components';
Examples
Kinds
Destructive
Saving
Custom Footer
Open From Button
Usage
<Modal title="Void this claim?" kind="destructive" primaryLabel="Void Claim" onPrimary={voidClaim} onClose={close}>
<DescriptionList items={[["Claim", "CLM-20871"]]} />
</Modal>
When to use
- Short focused forms (Add Appointment Type), confirms ("Discard unsaved changes on this page?"), destructive actions (Void Claim).
When not to use
- Long forms or reference panels: Drawer.
- Multi-step flows over 3 steps: a page with Stepper.
Variants and states
| Variant | What it is |
|---|---|
| form | Fields, Cancel and Save. |
| confirm | Short question, two buttons. |
| destructive | Warning icon, record summary, solid red confirm with the verb ("Void Claim"). |
| sizes | sm 420px, md 640px, wide 980px. |
Accessibility
- dialog (form) or alertdialog (confirm, destructive), aria-modal, labelled by the title.
- Escape and the x close it; scrim click closes forms only when nothing was typed (app rule).
- Move focus into the dialog on open and back to the trigger on close.
- Renders through a portal, traps Tab inside and locks page scroll. Pass
closeOnScrim={false}for forms once something was typed.
Do and don't
- Do: Destructive: name the record ("Void CLM-20871 for Henna West?") and the consequence.
- Don't: Stacked modals.
- Don't: "Are you sure?" with OK and Cancel.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
open | boolean | true | Whether the dialog is shown |
title * | ReactNode | — | Dialog title; names the dialog. Required. |
kind | ModalKind | 'form' | 'form' | 'confirm' | 'destructive'; form is a dialog, the others alertdialog |
size | ModalSize | 'md' | 'sm' 420px | 'md' 640px | 'wide' 980px |
children | ReactNode | — | Dialog body |
primaryLabel | string | "Save" | Primary button label, a verb ("Void Claim") |
cancelLabel | string | "Cancel" | Cancel button label |
onPrimary | () => void | none | Primary button handler |
onClose | () => void | none | Called by Cancel, the x button, Escape and (when `closeOnScrim`) a scrim press |
loading | boolean | false | Shows a spinner on the primary button |
primaryDisabled | boolean | false | Disables the primary button |
footer | ReactNode | Cancel + primary footer; `null` removes the footer; default the two buttons | Replaces the |
closeOnScrim | boolean | true | Close when the scrim is pressed (set false for forms with typed input) |
inline | boolean | false | Render in place for docs: no portal, focus trap, scroll lock or Escape |
Also accepts native attributes, including defaultChecked, defaultValue, autoFocus, plus className and event handlers on the root element.
Angular, Vue and HTML
Register the elements once (Angular guide), then use <co-modal>. Attributes take strings; arrays and objects are set as properties (Angular [prop], Vue :prop) or as JSON attributes. Callbacks are DOM events with the value in event.detail.
Angular template
<co-modal open kind="…" [defaultValue]="defaultValue" (co-primary)="onPrimary($event.detail)">…</co-modal>
| Kind | Name | Description |
|---|---|---|
| attribute | open | Whether the dialog is shown; default true |
| attribute | kind | 'form' | 'confirm' | 'destructive'; form is a dialog, the others alertdialog; default 'form' |
| attribute | size | 'sm' 420px | 'md' 640px | 'wide' 980px; default 'md' |
| attribute | primary-label / primaryLabel | Primary button label, a verb ("Void Claim"); default "Save" |
| attribute | cancel-label / cancelLabel | Cancel button label; default "Cancel" |
| attribute | loading | Shows a spinner on the primary button; default false |
| attribute | primary-disabled / primaryDisabled | Disables the primary button; default false |
| attribute | close-on-scrim / closeOnScrim | Close when the scrim is pressed (set false for forms with typed input); default true |
| attribute | inline | Render in place for docs: no portal, focus trap, scroll lock or Escape; default false |
| attribute | default-checked / defaultChecked | |
| property / JSON attribute | default-value / defaultValue | |
| attribute | auto-focus / autoFocus | |
| event | co-primary | Primary button handler; default none (React: onPrimary) |
| event | co-close | Called by Cancel, the x button, Escape and (when `closeOnScrim`) a scrim press; default none (React: onClose) |
| slot | title | Dialog title; names the dialog. Required. Plain text also works as the `title` attribute. |
| slot | (default) | Dialog body |
| slot | footer | Replaces the default Cancel + primary footer; `null` removes the footer; default the two buttons Plain text also works as the `footer` attribute. |