Skip to main content

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​

Storybook

Destructive​

Storybook

Saving​

Storybook
Storybook

Open From Button​

Storybook

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​

VariantWhat it is
formFields, Cancel and Save.
confirmShort question, two buttons.
destructiveWarning icon, record summary, solid red confirm with the verb ("Void Claim").
sizessm 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​

PropTypeDefaultDescription
openbooleantrueWhether the dialog is shown
title *ReactNode—Dialog title; names the dialog. Required.
kindModalKind'form''form' | 'confirm' | 'destructive'; form is a dialog, the others alertdialog
sizeModalSize'md''sm' 420px | 'md' 640px | 'wide' 980px
childrenReactNode—Dialog body
primaryLabelstring"Save"Primary button label, a verb ("Void Claim")
cancelLabelstring"Cancel"Cancel button label
onPrimary() => voidnonePrimary button handler
onClose() => voidnoneCalled by Cancel, the x button, Escape and (when `closeOnScrim`) a scrim press
loadingbooleanfalseShows a spinner on the primary button
primaryDisabledbooleanfalseDisables the primary button
footerReactNodeCancel + primary footer; `null` removes the footer; default the two buttonsReplaces the
closeOnScrimbooleantrueClose when the scrim is pressed (set false for forms with typed input)
inlinebooleanfalseRender 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>
KindNameDescription
attributeopenWhether the dialog is shown; default true
attributekind'form' | 'confirm' | 'destructive'; form is a dialog, the others alertdialog; default 'form'
attributesize'sm' 420px | 'md' 640px | 'wide' 980px; default 'md'
attributeprimary-label / primaryLabelPrimary button label, a verb ("Void Claim"); default "Save"
attributecancel-label / cancelLabelCancel button label; default "Cancel"
attributeloadingShows a spinner on the primary button; default false
attributeprimary-disabled / primaryDisabledDisables the primary button; default false
attributeclose-on-scrim / closeOnScrimClose when the scrim is pressed (set false for forms with typed input); default true
attributeinlineRender in place for docs: no portal, focus trap, scroll lock or Escape; default false
attributedefault-checked / defaultChecked
property / JSON attributedefault-value / defaultValue
attributeauto-focus / autoFocus
eventco-primaryPrimary button handler; default none (React: onPrimary)
eventco-closeCalled by Cancel, the x button, Escape and (when `closeOnScrim`) a scrim press; default none (React: onClose)
slottitleDialog title; names the dialog. Required. Plain text also works as the `title` attribute.
slot(default)Dialog body
slotfooterReplaces the default Cancel + primary footer; `null` removes the footer; default the two buttons Plain text also works as the `footer` attribute.