Modal

Centre alignment

<Modal
open={open}
onClose={() => setOpen(false)}
alignment="centre"
title="Delete item?"
subtitle="This can't be undone."
primaryActionLabel="Delete"
primaryActionOnClick={handleDelete}
secondaryActionLabel="Cancel"
secondaryActionOnClick={() => setOpen(false)}
>
<p>Deleting this item will remove it permanently.</p>
</Modal>

Left alignment, large width

<Modal
open={open}
onClose={() => setOpen(false)}
alignment="left"
maxWidth="lg"
title="Delete item?"
subtitle="This can't be undone."
primaryActionLabel="Delete"
primaryActionOnClick={handleDelete}
secondaryActionLabel="Cancel"
secondaryActionOnClick={() => setOpen(false)}
>
<p>Deleting this item will remove it permanently.</p>
</Modal>

Header content

<Modal
open={open}
onClose={() => setOpen(false)}
title="Delete item?"
subtitle="This can't be undone."
headerContent={<span>🗑️</span>}
primaryActionLabel="Delete"
primaryActionOnClick={handleDelete}
secondaryActionLabel="Cancel"
secondaryActionOnClick={() => setOpen(false)}
>
<p>Deleting this item will remove it permanently.</p>
</Modal>

Stacked footer

<Modal
open={open}
onClose={() => setOpen(false)}
footerDirection="column"
title="Cancel your booking?"
subtitle="Your tradesperson will be notified straight away."
primaryActionLabel="Cancel booking"
primaryActionOnClick={() => setOpen(false)}
secondaryActionLabel="Message tradesperson"
secondaryActionOnClick={() => setOpen(false)}
tertiaryActionLabel="Keep booking"
tertiaryActionOnClick={() => setOpen(false)}
>
<p>Your tradesperson will be notified straight away.</p>
</Modal>

Footer content

<Modal
open={open}
onClose={() => setOpen(false)}
alignment="left"
title="Update your details"
footerContent={<Link onClick={() => {}}>Privacy policy</Link>}
primaryActionLabel="Save"
primaryActionOnClick={() => setOpen(false)}
secondaryActionLabel="Cancel"
secondaryActionOnClick={() => setOpen(false)}
>
<p>Update your details and we'll keep your booking in sync.</p>
</Modal>

When to use

Use Modal for confirmations, short forms, and focused tasks that need to interrupt the current flow. It is a centered overlay panel, portal-mounted via Backdrop, with a scrim and built-in dismiss handling (backdrop click, Escape, close button).

Alignment

• Left (default): left-aligned header text. Use for forms and content-heavier tasks.
• Centre: centered header text. Use for short confirmations — “Delete item?”, “Log out?”.

alignment only affects the header title/subtitle text alignment — the panel itself always renders centered on screen (it is not a screen-position axis), and it no longer affects footer layout at all. The footer always renders as a fixed two-group row layout (or a fixed stacked order via footerDirection="column") — see “Footer layout” below.

Footer layout

Footer actions render as a fixed two-group layout, independent of alignment:

• Row (default): two visual groups spread across the row — tertiary and footerContent on the left, secondary and primary on the right, with primary rightmost. Tab/DOM order is always primary → secondary → tertiary → footerContent, regardless of alignment.
• Stack (footerDirection="column"): the visual top-to-bottom order is footerContent → secondary → primary → tertiary, while Tab/DOM order is primary → secondary → tertiary → footerContent, so the primary action stays reachable first. The two deliberately differ, using CSS order (which never affects tab order) — the same technique the row layout uses.

This replaces the previous alignment-driven layout (equal-width centre-fill row, right-aligned auto-width row, primary-first stack) entirely.

Width

maxWidth ranges from sm to 2xl, plus a full value that is a fixed 896px panel — not literal 100% viewport width — and a fit-content value that sizes the panel to its own content width, capped at that same 896px. Default is fit-content.

Scrollable content (native only)

On native, the panel is capped at 90% of the app window’s height (resolved via useWindowDimensions, so it stays correct under Android split-screen/multi-window and on foldables). By default (scrollable omitted or true), content taller than that scrolls inside the panel instead of overflowing past the screen edge. Set scrollable={false} when children renders its own FlatList, SectionList, or another ScrollView — a ScrollView parent gives its children unbounded height, which breaks list virtualisation (worst on Android). There’s no web equivalent yet — scrollable isn’t a prop on the web Modal.

Scrollable content you own must be imported from react-native-gesture-handler, not react-native. This is the one setup mistake here that fails silently: gesture-handler installs its own recognisers at the GestureHandlerRootView level, so a plain react-native ScrollView — or a FlatList/SectionList, which wrap one — never claims the pan inside these components. It renders, it is correctly height-bounded, and it simply will not scroll, with no warning. Use the drop-in replacements, which take the same props:

import { FlatList, ScrollView } from 'react-native-gesture-handler';

This applies whenever your children own the scrolling — i.e. with scrollable={false}. The default path needs nothing from you, because the ScrollView Modal wraps children in already comes from gesture-handler.

Keyboard avoidance (native)

Automatic, with no prop to configure or disable it, and no consumer setup beyond the Unistyles 3 peer dependency Modal already requires. Focusing a TextInput inside the panel shifts it above the on-screen keyboard, and the panel is also bounded to the space the keyboard leaves — so the shift can never push the panel’s own top edge off-screen. Content that no longer fits absorbs the difference and scrolls, keeping the header and close button reachable. BottomSheet shares this behaviour via ModalSurface.

When not to use

• A bottom-anchored panel on mobile-sized viewports: use BottomSheet instead — it shares the same underlying anatomy (ModalSurface) but anchors to the bottom of the screen.
• A non-blocking, dismissable overlay that doesn’t need header/footer chrome: compose Backdrop directly.
• A destructive action that doesn’t need a confirmation step: don’t add a Modal just for the sake of it — reserve it for genuinely interruptive tasks.

Props

Import

Web

import { Modal } from '@checkatrade/components-web';

Native

import { Modal } from '@checkatrade/components-native';

Basic usage

const [open, setOpen] = useState(false);

<Modal
  open={open}
  onClose={() => setOpen(false)}
  title="Delete item?"
  subtitle="This can't be undone."
  primaryActionLabel="Delete"
  primaryActionOnClick={handleDelete}
  secondaryActionLabel="Cancel"
  secondaryActionOnClick={() => setOpen(false)}
>
  <p>Deleting this item will remove it permanently.</p>
</Modal>;

Left alignment, larger width

<Modal
  open={open}
  onClose={() => setOpen(false)}
  alignment="left"
  maxWidth="lg"
  title="Update your details"
  primaryActionLabel="Save"
  primaryActionOnClick={handleSave}
  secondaryActionLabel="Cancel"
  secondaryActionOnClick={() => setOpen(false)}
>
  <MyForm />
</Modal>

Platform status

Accessibility

Renders role="dialog" and aria-modal="true", with aria-label set to the title prop.

Focus trap and scroll-lock are not yet implemented — this is a pre-existing gap carried over from the original proof-of-concept and tracked as a follow-up, not a regression introduced by this component.

Screen-reader containment is available via BackdropAccessibilityBoundary (native, opt-in): wrap your app content in it, as a sibling of the PortalHost, and assistive technology cannot reach the app behind an open overlay. This is needed because accessibilityViewIsModal is iOS-only in React Native — on Android it is a silent no-op, and TalkBack would otherwise walk out of the panel into the content behind it. It hides content from screen readers; it is not a focus trap, so on web Tab can still leave the panel.

No releases yet.