UnflowUI
Components

Modal

A general-purpose modal dialog with center, sidepanel, and bottom-sheet placements, draggable snap points, optional item navigation, and a hint checkbox.

Overview

Modal renders a dialog on top of a Backdrop. Unlike Alert (built for confirmations), Modal is a general-purpose container with a placement prop that controls where and how the panel appears — center, sidepanel, or bottomSheet. sidepanel automatically collapses into the same bottom-sheet treatment as bottomSheet below the md breakpoint (768px). A bottom sheet can also rest at snapPoints and be resized by dragging its handle.

For a docked, non-modal panel that sits beside the page instead of over it, use SidePanel.

Modal also supports an optional item-navigation control (previous/next + "N of X items") for browsing between records without closing the dialog, with built-in ArrowUp/ArrowDown keyboard support. That control is its own standalone, reusable component — see ItemNav.

Import

import { Modal } from '@unflowio/ui/components/Modal';

Props

PropTypeDefaultDescription
placement'center' | 'sidepanel' | 'bottomSheet''center'Panel layout. sidepanel collapses into bottomSheet below the md breakpoint
type'info' | 'success' | 'error' | 'warning' | 'destructive' | undefined—Semantic type; controls the default icon and colour scheme. Leave unset (or pass undefined) to render no status icon
openboolean—Controls visibility
titlestring—Heading text inside the header
subtitlestring—Secondary text below the title
descriptionstring—Body text below the header
actionsFooterAction[]—Array of buttons rendered in the footer
onClose() => void—Called when the close button, backdrop, Esc, or a drag below the lowest snap point is triggered
dismissiblebooleantrueSet to false to ignore the backdrop click, Esc and the drag-to-close gesture, and hide the close button. Applies to every placement
snapPoints(number | '${number}%')[]—Heights the bottom sheet rests at, in px or viewport percentages, e.g. ['40%', '90%']. Applies to bottomSheet, and to sidepanel on small viewports. Adds a drag handle
snapnumber—Controlled index into snapPoints, in the order given
defaultSnapnumber0Initial index into snapPoints when uncontrolled
onSnapChange(index: number) => void—Called with the new snap index after a drag, click or arrow key on the handle
hintstring—Optional hint message rendered in the footer area
hasHintCheckboxboolean—When true, renders hint as a checkbox instead of plain text
itemCountnumber—Total number of items being browsed. The nav control renders only when greater than 1
currentIndexnumber00-based index of the item currently displayed
onNavigate(index: number) => void—Called with the target index when the previous/next control is used
onPrevious / onNext() => void—Called alongside onNavigate for the respective direction
disableArrowKeysboolean—Disables the built-in ArrowUp/ArrowDown keydown handling
previousKeys / nextKeysstring[]—Additional hotkey combo (via useHotkey) that also triggers previous/next, e.g. ['k']/['j']. Arrow keys can't be registered here — see disableArrowKeys
disablePortalboolean—Render relative to parent instead of document.body
keepMountedboolean—Keep the panel mounted (invisible) in the DOM while closed, instead of unmounting it
autoFocusboolean—Move focus into the dialog when it opens
childrenReactNode—Custom content rendered inside the body, alongside description

FooterAction extends the Button props with an adjusted onClick, same shape as Alert's footerActions:

type FooterAction = Omit<IButton, 'onClick' | 'disabled'> & {
  onClick?: (e: MouseEvent, hintChecked: boolean) => void;
  disabled?: (hintChecked: boolean) => boolean;
};

Placement

Three placements are available. sidepanel is docked to the right edge on desktop and becomes a full-width bottom sheet below md.

<Modal placement="center"     title="..." description="..." open onClose={close} actions={actions} />
<Modal placement="sidepanel"  title="..." description="..." open onClose={close} actions={actions} />
<Modal placement="bottomSheet" title="..." description="..." open onClose={close} actions={actions} />

Snap points

Pass snapPoints to a bottom sheet to let it rest at several heights. A handle appears at the top of the sheet: drag it (a fast flick skips to the next point), click it to cycle through the points, or focus it and press ArrowUp/ArrowDown. Dragging below the lowest point closes the sheet unless dismissible is false. The body scrolls only at the highest point. snap, defaultSnap and onSnapChange index snapPoints in the order you pass them, so snapPoints={['90%', '40%']} with defaultSnap={0} opens at 90%.

const [snap, setSnap] = useState(0);

<Modal
  placement="bottomSheet"
  open={open}
  snapPoints={['40%', '90%']}
  snap={snap}
  onSnapChange={setSnap}
  title="Filters"
  onClose={() => setOpen(false)}
  actions={[{ label: 'Apply', onClick: () => setOpen(false) }]}
/>

Leave out snap and onSnapChange (optionally passing defaultSnap) to let the sheet track its own snap index.

Item navigation

Pass itemCount (and currentIndex/onNavigate) to render a previous/next control in the header, backed by the standalone ItemNav component. While the modal is open, ArrowUp moves to the previous item and ArrowDown moves to the next — unless focus is on an editable element (input, textarea, select, or a contenteditable node), or disableArrowKeys is set. Pass previousKeys/nextKeys to additionally bind a custom combo (e.g. ['k']/['j']) alongside the arrows.

<Modal
  placement="sidepanel"
  open={open}
  title="INVO-2026-003"
  itemCount={30}
  currentIndex={currentIndex}
  onNavigate={setCurrentIndex}
  onClose={() => setOpen(false)}
/>

Checkbox hint

Set hasHintCheckbox to render hint as a checkbox the user must actively check. The checked state is forwarded as the second argument to each action.onClick, so you can guard a destructive action behind it.

<Modal
  type="destructive"
  open={open}
  title="Delete records"
  description="This will permanently delete the selected records. This action cannot be undone."
  hint="I understand that this action is irreversible."
  hasHintCheckbox
  onClose={() => setOpen(false)}
  actions={[
    { label: 'Cancel', variant: 'secondary', onClick: () => setOpen(false) },
    {
      label: 'Delete',
      variant: 'destructive',
      onClick: (e, hintChecked) => {
        if (!hintChecked) return;
        setOpen(false);
      },
      disabled: (hintChecked) => !hintChecked,
    },
  ]}
/>

Custom content

Use children to render arbitrary content inside the body alongside or instead of description, or slots.bodyComponent to replace the body content entirely (bypassing description/children).

<Modal
  open={open}
  title="Review before confirming"
  onClose={() => setOpen(false)}
  actions={[
    { label: 'Cancel', variant: 'secondary', onClick: () => setOpen(false) },
    { label: 'Confirm', onClick: () => setOpen(false) },
  ]}
>
  <ul className="text-sm text-grey-600 list-disc pl-4 space-y-1">
    <li>5 records will be updated</li>
    <li>Change will apply to all environments</li>
  </ul>
</Modal>

Customization (slots & slotProps)

SlotTypeDescription
headReactNodeFull override of the header row
footerReactNodeFull override of the footer row
bodyComponentReactNodeFull override of the body content (description/children are skipped)
startIcon / endIconReactNodeHeader icon overrides
arrowIconUp / arrowIconDownReactNodeIcon overrides for the built-in item nav control
itemNav(ctx) => ReactNodeFull override of the item nav control; receives { currentIndex, itemCount, isFirst, isLast, onPrevious, onNext }
Slot PropPropsDescription
headBaseHTMLProps<HTMLDivElement>Header row container
sheetHandleBaseHTMLProps<HTMLButtonElement>Drag handle rendered with snapPoints
closeButtonOmit<IIconButton, 'onClick'>Close icon button
iconBaseHTMLProps<HTMLDivElement>Start icon wrapper
titleBaseHTMLProps<HTMLHeadingElement>Title <h2> element
subtitleBaseHTMLProps<HTMLParagraphElement>Subtitle text element
bodyBaseHTMLProps<HTMLDivElement>Body container — a wrapper override only; use slots.bodyComponent to replace the content itself
descriptionBaseHTMLProps<HTMLParagraphElement>Description text element
hintTextBaseHTMLProps<HTMLParagraphElement>Hint label text
hintCheckboxBaseHTMLProps<HTMLDivElement>Checkbox indicator element
footerBaseHTMLProps<HTMLDivElement>Footer container
itemNavRootBaseHTMLProps<HTMLDivElement>Built-in item nav container
itemNavPreviousButton / itemNavNextButtonOmit<IIconButton, 'onClick'>Built-in item nav buttons
itemNavCounterBaseHTMLProps<HTMLParagraphElement>"N of X items" text element

Accessibility

  • Renders a <div role="dialog" aria-modal="true">, with aria-labelledby/aria-describedby pointing at the rendered title/subtitle/description.
  • Focus is trapped inside the dialog while open (via the underlying Backdrop and ClickAwayEvent), and restored to the previously focused element on close.
  • Clicking outside the dialog or pressing Esc triggers onClose, unless dismissible is false.
  • The snap-point handle is a <button> with a translated label ("Resize sheet"), operable with ArrowUp/ArrowDown and Enter/Space.
  • The close button always has an accessible label and is reachable by keyboard.
  • The item nav "N of X items" counter is an aria-live="polite" region, so screen reader users get position feedback without extra wiring.
  • Provide a meaningful title so screen readers can announce the dialog's purpose when focus enters.