# Dialog

Displays a modal overlay with animated transitions and gesture-based dismissal.

## Import

```tsx
import { Dialog } from '@/heroui';
```

## Anatomy

```tsx
<Dialog>
  <Dialog.Trigger>...</Dialog.Trigger>
  <Dialog.Portal>
    <Dialog.Overlay>...</Dialog.Overlay>
    <Dialog.Content>
      <Dialog.Close>...</Dialog.Close>
      <Dialog.Title>...</Dialog.Title>
      <Dialog.Description>...</Dialog.Description>
    </Dialog.Content>
  </Dialog.Portal>
</Dialog>
```

- **Dialog**: Root component that manages open state and provides context to child components.
- **Dialog.Trigger**: Pressable element that opens the dialog when pressed.
- **Dialog.Portal**: Renders dialog content in a portal with centered layout and animation control.
- **Dialog.Overlay**: Background overlay that appears behind the dialog content, typically closes dialog when pressed.
- **Dialog.Content**: Main dialog container with gesture support for drag-to-dismiss.
- **Dialog.Close**: Close button for the dialog. Can accept custom children or uses default close icon.
- **Dialog.Title**: Dialog title text with semantic heading role.
- **Dialog.Description**: Dialog description text that provides additional context.

## Usage

### Basic Dialog

Simple dialog with title, description, and close button.

```tsx
<Dialog isOpen={isOpen} onOpenChange={setIsOpen}>
  <Dialog.Trigger asChild>
    <Button>Open Dialog</Button>
  </Dialog.Trigger>
  <Dialog.Portal>
    <Dialog.Overlay />
    <Dialog.Content>
      <Dialog.Close />
      <Dialog.Title>...</Dialog.Title>
      <Dialog.Description>...</Dialog.Description>
    </Dialog.Content>
  </Dialog.Portal>
</Dialog>
```

### Scrollable Content

Handle long content with scroll views.

```tsx
<Dialog isOpen={isOpen} onOpenChange={setIsOpen}>
  <Dialog.Trigger>...</Dialog.Trigger>
  <Dialog.Portal>
    <Dialog.Overlay />
    <Dialog.Content>
      <Dialog.Close />
      <Dialog.Title>...</Dialog.Title>
      <View className="h-[300px]">
        <ScrollView>...</ScrollView>
      </View>
    </Dialog.Content>
  </Dialog.Portal>
</Dialog>
```

### Form Dialog

Dialog with text inputs and keyboard handling.

```tsx
<Dialog isOpen={isOpen} onOpenChange={setIsOpen}>
  <Dialog.Trigger>...</Dialog.Trigger>
  <Dialog.Portal>
    <Dialog.Overlay />
    <KeyboardAvoidingView behavior="padding">
      <Dialog.Content>
        <Dialog.Close />
        <Dialog.Title>...</Dialog.Title>
        <TextField>...</TextField>
        <Button onPress={handleSubmit}>Submit</Button>
      </Dialog.Content>
    </KeyboardAvoidingView>
  </Dialog.Portal>
</Dialog>
```

## Example

```tsx
import { Button, Dialog } from '@/heroui';
import { View } from 'react-native';
import { useState } from 'react';

export default function DialogExample() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <Dialog isOpen={isOpen} onOpenChange={setIsOpen}>
      <Dialog.Trigger asChild>
        <Button variant="primary">Open Dialog</Button>
      </Dialog.Trigger>
      <Dialog.Portal>
        <Dialog.Overlay />
        <Dialog.Content>
          <Dialog.Close variant="ghost" />
          <View className="mb-5 gap-1.5">
            <Dialog.Title>Confirm Action</Dialog.Title>
            <Dialog.Description>
              Are you sure you want to proceed with this action? This cannot be
              undone.
            </Dialog.Description>
          </View>
          <View className="flex-row justify-end gap-3">
            <Button variant="ghost" size="sm" onPress={() => setIsOpen(false)}>
              Cancel
            </Button>
            <Button size="sm">Confirm</Button>
          </View>
        </Dialog.Content>
      </Dialog.Portal>
    </Dialog>
  );
}
```

You can find more examples in the [GitHub repository](<https://github.com/heroui-inc/heroui-native/blob/rc/example/src/app/(home)/components/dialog.tsx>).

## API Reference

### Dialog

| prop            | type                       | default | description                                        |
| --------------- | -------------------------- | ------- | -------------------------------------------------- |
| `children`      | `React.ReactNode`          | -       | Dialog content and trigger elements                |
| `isOpen`        | `boolean`                  | -       | Controlled open state of the dialog                |
| `isDefaultOpen` | `boolean`                  | `false` | Initial open state when uncontrolled               |
| `animation`     | `AnimationRootDisableAll`  | -       | Animation configuration                            |
| `onOpenChange`  | `(value: boolean) => void` | -       | Callback when open state changes                   |
| `...ViewProps`  | `ViewProps`                | -       | All standard React Native View props are supported |

#### AnimationRootDisableAll

Animation configuration for dialog root component. Can be:

- `false` or `"disabled"`: Disable only root animations
- `"disable-all"`: Disable all animations including children
- `true` or `undefined`: Use default animations

### Dialog.Trigger

| prop                       | type                    | default | description                                                    |
| -------------------------- | ----------------------- | ------- | -------------------------------------------------------------- |
| `children`                 | `React.ReactNode`       | -       | Trigger element content                                        |
| `asChild`                  | `boolean`               | -       | Render as child element without wrapper                        |
| `...TouchableOpacityProps` | `TouchableOpacityProps` | -       | All standard React Native TouchableOpacity props are supported |

### Dialog.Portal

| prop                       | type                   | default | description                                                                                                                   |
| -------------------------- | ---------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `children`                 | `React.ReactNode`      | -       | Portal content (overlay and dialog)                                                                                           |
| `disableFullWindowOverlay` | `boolean`              | `false` | When true on iOS, uses View instead of FullWindowOverlay. Enables element inspector; overlay won't appear above native modals |
| `className`                | `string`               | -       | Additional CSS classes for portal container                                                                                   |
| `style`                    | `StyleProp<ViewStyle>` | -       | Additional styles for portal container                                                                                        |
| `hostName`                 | `string`               | -       | Optional portal host name for specific container                                                                              |
| `forceMount`               | `boolean`              | -       | Force mount when closed for animation purposes                                                                                |

### Dialog.Overlay

| prop                    | type                     | default | description                                                  |
| ----------------------- | ------------------------ | ------- | ------------------------------------------------------------ |
| `children`              | `React.ReactNode`        | -       | Custom overlay content                                       |
| `className`             | `string`                 | -       | Additional CSS classes for overlay                           |
| `style`                 | `ViewStyle`              | -       | Additional styles for overlay container                      |
| `animation`             | `DialogOverlayAnimation` | -       | Animation configuration                                      |
| `isAnimatedStyleActive` | `boolean`                | `true`  | Whether animated styles (react-native-reanimated) are active |
| `isCloseOnPress`        | `boolean`                | `true`  | Whether pressing overlay closes dialog                       |
| `forceMount`            | `boolean`                | -       | Force mount when closed for animation purposes               |
| `...PressableProps`     | `PressableProps`         | -       | All standard React Native Pressable props are supported      |

#### DialogOverlayAnimation

Animation configuration for dialog overlay component. Can be:

- `false` or `"disabled"`: Disable all animations
- `true` or `undefined`: Use default animations
- `object`: Custom animation configuration

| prop            | type                       | default                 | description                                                                  |
| --------------- | -------------------------- | ----------------------- | ---------------------------------------------------------------------------- |
| `state`         | `'disabled' \| boolean`    | -                       | Disable animations while customizing properties                              |
| `opacity.value` | `[number, number, number]` | `[0, 1, 0]`             | Opacity values [idle, open, close] (progress-based, for dialog presentation) |
| `entering`      | `EntryOrExitLayoutType`    | `FadeIn.duration(200)`  | Custom entering animation (for popover presentation)                         |
| `exiting`       | `EntryOrExitLayoutType`    | `FadeOut.duration(150)` | Custom exiting animation (for popover presentation)                          |

### Dialog.Content

| prop                    | type                     | default | description                                         |
| ----------------------- | ------------------------ | ------- | --------------------------------------------------- |
| `children`              | `React.ReactNode`        | -       | Dialog content                                      |
| `className`             | `string`                 | -       | Additional CSS classes for content container        |
| `style`                 | `StyleProp<ViewStyle>`   | -       | Additional styles for content container             |
| `animation`             | `DialogContentAnimation` | -       | Animation configuration                             |
| `isSwipeable`           | `boolean`                | `true`  | Whether the dialog content can be swiped to dismiss |
| `forceMount`            | `boolean`                | -       | Force mount when closed for animation purposes      |
| `...Animated.ViewProps` | `Animated.ViewProps`     | -       | All Reanimated Animated.View props are supported    |

#### DialogContentAnimation

Animation configuration for dialog content component. Can be:

- `false` or `"disabled"`: Disable all animations
- `true` or `undefined`: Use default animations
- `object`: Custom animation configuration

| prop       | type                    | default                                                                                     | description                                     |
| ---------- | ----------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| `state`    | `'disabled' \| boolean` | -                                                                                           | Disable animations while customizing properties |
| `entering` | `EntryOrExitLayoutType` | Keyframe with `scale: 0.96→1` and `opacity: 0→1` (200ms, easing: `Easing.out(Easing.ease)`) | Custom entering animation                       |
| `exiting`  | `EntryOrExitLayoutType` | Keyframe with `scale: 1→0.96` and `opacity: 1→0` (150ms, easing: `Easing.in(Easing.ease)`)  | Custom exiting animation                        |

### Dialog.Close

Dialog.Close extends [CloseButton](../close-button/close-button.md) and automatically handles dialog dismissal when pressed.

### Dialog.Title

| prop           | type              | default | description                                        |
| -------------- | ----------------- | ------- | -------------------------------------------------- |
| `children`     | `React.ReactNode` | -       | Title content                                      |
| `className`    | `string`          | -       | Additional CSS classes for title                   |
| `...TextProps` | `TextProps`       | -       | All standard React Native Text props are supported |

### Dialog.Description

| prop           | type              | default | description                                        |
| -------------- | ----------------- | ------- | -------------------------------------------------- |
| `children`     | `React.ReactNode` | -       | Description content                                |
| `className`    | `string`          | -       | Additional CSS classes for description             |
| `...TextProps` | `TextProps`       | -       | All standard React Native Text props are supported |

## Hooks

### useDialog

Hook to access dialog primitive context.

```tsx
const { isOpen, onOpenChange } = useDialog();
```

| property       | type                       | description                   |
| -------------- | -------------------------- | ----------------------------- |
| `isOpen`       | `boolean`                  | Current open state            |
| `onOpenChange` | `(value: boolean) => void` | Function to change open state |

### useDialogAnimation

Hook to access dialog animation context for advanced customization.

```tsx
const { progress, isDragging, isGestureReleaseAnimationRunning } =
  useDialogAnimation();
```

| property                           | type                   | description                                  |
| ---------------------------------- | ---------------------- | -------------------------------------------- |
| `progress`                         | `SharedValue<number>`  | Animation progress (0=idle, 1=open, 2=close) |
| `isDragging`                       | `SharedValue<boolean>` | Whether dialog is being dragged              |
| `isGestureReleaseAnimationRunning` | `SharedValue<boolean>` | Whether gesture release animation is running |

## Special Notes

### Element Inspector (iOS)

Dialog uses FullWindowOverlay on iOS. To enable the React Native element inspector during development, set `disableFullWindowOverlay={true}` on `Dialog.Portal`. Tradeoff: the dialog will not appear above native modals when disabled.