AwesomeDialog

Compound dialog rendered as a centred modal, an edge sheet or a swipe-to-dismiss drawer, with pattern chrome, header avatar / icon, toolbar menus, fullscreen and minimise-to-bar.

Edit on GitHubEditllms.txt

iOSAndroid

Preview AwesomeDialog on your device

Scan with Expo Go

iOS Android

Download Expo Go, then scan the QR code to preview native components.

Installation

pnpm dlx @docyrus/cli add @docyrus/rn-awesome-dialog

Required Packages(4 packages)

pnpm add react-native-svg react-native-reanimated react-native-gesture-handler react-native-safe-area-context

Usage

import {
  AwesomeDialog,
  AwesomeDialogHeader,
  AwesomeDialogBody,
  AwesomeDialogFooter,
} from '@/components/docyrus-native/awesome-dialog';

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

<AwesomeDialog open={open} onOpenChange={setOpen} size="lg">
  <AwesomeDialogHeader title="Edit record" description="Changes are saved on confirm" icon="fal pen" />
  <AwesomeDialogBody>
    <Text>Dialog content</Text>
  </AwesomeDialogBody>
  <AwesomeDialogFooter>
    <Button variant="outline" onPress={() => setOpen(false)}>Cancel</Button>
    <Button onPress={() => setOpen(false)}>Save</Button>
  </AwesomeDialogFooter>
</AwesomeDialog>

Containers

{/* Edge sheet (no swipe) */}
<AwesomeDialog container="sheet" side="right" open={open} onOpenChange={setOpen}>…</AwesomeDialog>

{/* Drawer — swipe towards its edge to dismiss (top / bottom: swipe the grab handle) */}
<AwesomeDialog container="drawer" side="bottom" open={open} onOpenChange={setOpen}>…</AwesomeDialog>

preventOutsideClose ignores backdrop taps on every container; on the drawer it also disables swipe-to-dismiss and the Android back button.

Header avatar and icon

<AwesomeDialogHeader
  title="Acme Inc."
  avatar={{ color: 'indigo-500', icon: 'fal building' }} />

<AwesomeDialogHeader title="Report" icon="chart-pie" iconLib="fal" />

Web's desktop menubar becomes a horizontal chip row; each chip opens its actions in an ActionSheet. Separators are dropped and shortcut hints are not shown.

<AwesomeDialogToolbar
  menus={[
    { label: 'File', items: [{ label: 'Save', onClick: save }, { label: 'Archive', disabled: true }] },
    { label: 'Edit', items: [{ label: 'Undo', onClick: undo }] },
  ]} />

Wrap the app in GlobalDialogProvider, mount one GlobalDialogBar, and give a dialog minimizable + a dialogId. Minimising hides the dialog (its open stays true) and docks a pill in the bar; tapping the pill restores it, the × closes it (calls the dialog's onOpenChange(false)).

<GlobalDialogProvider persist>
  <App />
  <GlobalDialogBar className="bottom-24" /> {/* above a tab bar */}
</GlobalDialogProvider>

<AwesomeDialog dialogId="invoice-42" minimizable open={open} onOpenChange={setOpen}>…</AwesomeDialog>

persist stores minimised / fullscreen states in the synchronous 'local' Docyrus key-value store (lib/storage — register a backend with DocyStorageProvider; without one it lives in memory for the process lifetime).

Native differences from web: side defaults to 'bottom' (web: 'right'); resizable is accepted but ignored (pointer-only); the root title is a native fallback used by AwesomeDialogHeader when it has no title and no children; header icon also accepts a ReactNode; the global registry merges repeat register() calls and adds close(id).

API Reference

AwesomeDialogProps

Prop	Type	Default	Description
`open`	`boolean`	`false`	Controlled open state
`onOpenChange`	`(open: boolean) => void`	-	Open state change handler
`children`	`ReactNode`	-	Dialog content (Header / Toolbar / Body / Footer)
`container`	`'modal' \| 'sheet' \| 'drawer'`	`'modal'`	Centred modal, edge sheet, or edge drawer with swipe-to-dismiss
`side`	`'left' \| 'right' \| 'top' \| 'bottom'`	`'bottom'`	Edge for sheet / drawer containers
`size`	`'sm' \| 'default' \| 'lg' \| 'xl' \| 'full'`	`'default'`	Size preset
`pattern`	`boolean`	`true`	Show the SVG pattern background
`patternStyle`	`'stripes' \| 'dots' \| 'grid' \| 'crosshatch' \| 'zigzag'`	`'stripes'`	Pattern motif
`resizable`	`boolean`	`false`	Accepted for web parity; ignored on native
`fullscreenable`	`boolean`	`false`	Show the maximize / restore button in the header
`defaultFullscreen`	`boolean`	`false`	Start in fullscreen mode
`minimizable`	`boolean`	`false`	Show the minimize button (needs `GlobalDialogProvider` + `dialogId`)
`preventOutsideClose`	`boolean`	`false`	Ignore backdrop taps (and swipe / back button for the drawer)
`dialogId`	`string`	-	Unique ID for `GlobalDialogProvider` tracking
`title`	`string`	-	Fallback title for `AwesomeDialogHeader` (native only)
`className`	`string`	-	Classes for the inner dialog card

Size Presets

Size	Modal (width / max height)	Top / bottom panel height	Left / right panel width
`sm`	75% / 50%	35%	50%
`default`	85% / 70%	50%	65%
`lg`	92% / 85%	70%	80%
`xl`	96% / 92%	85%	90%
`full`	100% / 100%	100%	100%

AwesomeDialogHeaderProps

Prop	Type	Default	Description
`title`	`string`	root `title`	Dialog title text
`description`	`string`	-	Text below the title
`icon`	`string \| ReactNode`	-	DocyrusIcon identifier (or a custom node)
`iconLib`	`string`	-	DocyrusIcon library
`avatar`	`{ name?: string; color?: string; icon?: string; image?: string }`	-	Rendered through `AvatarThumbnail` (`image` is a URL)
`closable`	`boolean`	`true`	Show the close button
`headerButtons`	`ReactNode`	-	Buttons rendered before the built-in ones
`onClose`	`() => void`	-	Custom close handler (defaults to `onOpenChange(false)`)
`children`	`ReactNode`	-	Custom content shown in place of the title when no `title` is set
`className`	`string`	-	Additional CSS classes

AwesomeDialogToolbarProps

Prop	Type	Default	Description
`menus`	`ToolbarMenuItem[]`	-	Menu chips, each opening an action sheet
`children`	`ReactNode`	-	Custom toolbar content (after the chips)
`className`	`string`	-	Classes for the chip row content

ToolbarMenuItem / ToolbarMenuAction

Field	Type	Description
`ToolbarMenuItem.label`	`string`	Chip label / sheet title
`ToolbarMenuItem.items`	`ToolbarMenuAction[]`	Actions
`ToolbarMenuAction.label`	`string`	Action label
`ToolbarMenuAction.onClick`	`() => void`	Called when picked
`ToolbarMenuAction.disabled`	`boolean`	Greys the row out
`ToolbarMenuAction.separator`	`boolean`	Dropped on native
`ToolbarMenuAction.shortcut`	`string`	Web parity; not shown on native

AwesomeDialogBodyProps / AwesomeDialogFooterProps

Prop	Type	Default	Description
`children`	`ReactNode`	-	Content (the body scrolls)
`className`	`string`	-	Additional CSS classes (body: scroll content container)

AwesomeDialogContentProps

The patterned two-layer surface AwesomeDialog renders around its children; use it only when composing a custom container.

Prop	Type	Default	Description
`children`	`ReactNode`	-	Dialog parts
`pattern`	`boolean`	`true`	Show the pattern
`patternStyle`	`PatternStyle`	`'stripes'`	Pattern motif
`isFullscreen`	`boolean`	`false`	Drop the frame padding / radius
`className`	`string`	-	Classes for the inner card

GlobalDialogProviderProps

Prop	Type	Default	Description
`children`	`ReactNode`	-	App subtree
`persist`	`boolean`	`false`	Persist minimised / fullscreen states to the `'local'` Docyrus store
`storageKey`	`string`	`'awesome-dialog-states'`	Storage key

GlobalDialogBarProps

Prop	Type	Default	Description
`className`	`string`	-	Positioning overrides (defaults to `absolute bottom-4 left-4 right-4`)

Hooks

Hook	Returns	Description
`useAwesomeDialog()`	`AwesomeDialogContextValue`	Dialog state (`container`, `side`, `size`, `isFullscreen`, `setFullscreen`, `toggleFullscreen`, `fullscreenable`, `minimizable`, `resizable`, `onClose`, `dialogId`, `title`, `fillsHeight`). Throws outside an `AwesomeDialog`
`useGlobalDialog()`	`GlobalDialogContextValue`	Global registry (`dialogs`, `register`, `unregister`, `minimize`, `restore`, `bringToFront`, `toggleFullscreen`, `getZIndex`, `isMinimized`, `isFullscreen`, `minimizedDialogs`, `close`). Throws outside the provider
`useOptionalGlobalDialog()`	`GlobalDialogContextValue \| null`	Same, `null` without a provider

Components

Component	Description
`AwesomeDialog`	Root (container, sizing, global registration)
`AwesomeDialogHeader`	Title / description / icon / avatar + fullscreen, minimize and close buttons
`AwesomeDialogToolbar`	Menu chip row
`AwesomeDialogBody`	Scrollable content
`AwesomeDialogFooter`	Action row
`AwesomeDialogContent`	Patterned surface (rendered by the root)
`GlobalDialogProvider`	Registry for minimisable dialogs
`GlobalDialogBar`	Floating pill stack of minimised dialogs

Type Exports

Type	Description
`AwesomeDialogProps`	Root props
`AwesomeDialogHeaderProps`	Header props
`AwesomeDialogHeaderAvatar`	Header avatar config
`AwesomeDialogBodyProps`	Body props
`AwesomeDialogFooterProps`	Footer props
`AwesomeDialogToolbarProps`	Toolbar props
`AwesomeDialogContentProps`	Content surface props
`AwesomeDialogContextValue`	`useAwesomeDialog()` value
`DialogContainer`	`'modal' \| 'sheet' \| 'drawer'`
`DialogSide`	`'left' \| 'right' \| 'top' \| 'bottom'`
`DialogSize`	`'sm' \| 'default' \| 'lg' \| 'xl' \| 'full'`
`DialogState`	Registry entry (`dialogId`, `minimized`, `fullscreen`, `zIndex`, `title?`, `icon?`)
`GlobalDialogContextValue`	Registry API
`GlobalDialogProviderProps`	Provider props
`GlobalDialogRegisterMeta`	`register()` meta (`title?`, `icon?`, `onClose?`)
`GlobalDialogBarProps`	Bar props
`ToolbarMenuItem`	Toolbar menu
`ToolbarMenuAction`	Toolbar menu action
`PatternStyle`	Pattern motif union
`AwesomeDialogSize` / `AwesomeDialogContainer` / `AwesomeDialogSheetSide`	Deprecated aliases of `DialogSize` / `DialogContainer` / `DialogSide`