# rn-awesome-dialog
URL: /docs/native/docyrus/awesome-dialog

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.

## Installation

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

**Dependencies:**
- [react-native-svg](https://www.npmjs.com/package/react-native-svg)
- [react-native-reanimated](https://www.npmjs.com/package/react-native-reanimated)
- [react-native-gesture-handler](https://www.npmjs.com/package/react-native-gesture-handler)
- [react-native-safe-area-context](https://www.npmjs.com/package/react-native-safe-area-context)

## Usage

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

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

  
  
    
  

```

### Containers

```tsx
{/* Edge sheet (no swipe) */}

{/* Drawer — swipe towards its edge to dismiss (top / bottom: swipe the grab handle) */}

```

`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

```tsx

```

### Toolbar menus

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.

```tsx

```

### Minimise to a global bar

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)`).

```tsx

```

`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).

## 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` |