Usage

import { Modal } from "@heroui/react";

Anatomy

import {Modal, Button} from "@heroui/react";

export default () => (
  <Modal>
    <Button>Open Modal</Button>
    <Modal.Backdrop>
      <Modal.Container>
        <Modal.Dialog>
          <Modal.CloseTrigger /> {/* Optional: Close button */}
          <Modal.Header>
            <Modal.Icon /> {/* Optional: Icon */}
            <Modal.Heading />
          </Modal.Header>
          <Modal.Body />
          <Modal.Footer />
        </Modal.Dialog>
      </Modal.Container>
    </Modal.Backdrop>
  </Modal>
);

Examples

Sizes

Placement

Scroll Behavior

Inside

Outside

Controlled State

With React.useState()

Control the modal using React's useState hook for simple state management. Perfect for basic use cases.

Status: closed

With useOverlayState()

Use the useOverlayState hook for a cleaner API with convenient methods like open(), close(), and toggle().

Status: closed

With Form

Custom Trigger

Settings

Manage your preferences

Backdrop Variants

Custom Backdrop

Dismiss Behavior

isDismissable

Controls whether the modal can be dismissed by clicking the overlay backdrop. Defaults to true. Set to false to require explicit close action.

isKeyboardDismissDisabled

Controls whether the ESC key can dismiss the modal. When set to true, the ESC key will be disabled and users must use explicit close actions.

Close Methods

Using slot="close"

The simplest way to close a modal. Add slot="close" to any Button component within the modal. When clicked, it will automatically close the modal.

Using Dialog render props

Access the close method from the Dialog's render props. This gives you full control over when and how to close the modal, allowing you to add custom logic before closing.

@layer components {
  .modal__backdrop {
    @apply bg-gradient-to-br from-black/50 to-black/70;
  }

  .modal__dialog {
    @apply rounded-2xl border border-white/10 shadow-2xl;
  }

  .modal__header {
    @apply text-center;
  }

  .modal__close-trigger {
    @apply rounded-full bg-white/10 hover:bg-white/20;
  }
}

.modal__trigger - Trigger element that opens the modal
.modal__backdrop - Overlay backdrop behind the modal
.modal__container - Positioning wrapper with placement support
.modal__dialog - Modal content container
.modal__header - Header section for titles and icons
.modal__body - Main content area
.modal__footer - Footer section for actions
.modal__close-trigger - Close button element

Backdrop Variants

.modal__backdrop--opaque - Opaque colored backdrop (default)
.modal__backdrop--blur - Blurred backdrop with glass effect
.modal__backdrop--transparent - Transparent backdrop (no overlay)

Scroll Variants

.modal__container--scroll-outside - Enables scrolling the entire modal
.modal__dialog--scroll-inside - Constrains modal height for body scrolling
.modal__body--scroll-inside - Makes only the body scrollable
.modal__body--scroll-outside - Allows full-page scrolling

Interactive States

The component supports these interactive states:

Focus: :focus-visible or [data-focus-visible="true"] - Applied to trigger, dialog, and close button
Hover: :hover or [data-hovered="true"] - Applied to close button on hover
Active: :active or [data-pressed="true"] - Applied to close button when pressed
Entering: [data-entering] - Applied during modal opening animation
Exiting: [data-exiting] - Applied during modal closing animation
Placement: [data-placement="*"] - Applied based on modal position (auto, top, center, bottom)

API Reference

Prop	Type	Default	Description
`children`	`ReactNode`	-	Trigger and container elements

Modal.Trigger

Prop	Type	Default	Description
`children`	`ReactNode`	-	Custom trigger content
`className`	`string`	-	CSS classes

Modal.Backdrop

Prop	Type	Default	Description
`variant`	`"opaque" \| "blur" \| "transparent"`	`"opaque"`	Backdrop overlay style
`isDismissable`	`boolean`	`true`	Close on backdrop click
`isKeyboardDismissDisabled`	`boolean`	`false`	Disable ESC key to close
`isOpen`	`boolean`	-	Controlled open state
`onOpenChange`	`(isOpen: boolean) => void`	-	Open state change handler
`className`	`string \| (values) => string`	-	Backdrop CSS classes
`UNSTABLE_portalContainer`	`HTMLElement`	-	Custom portal container

Modal.Container

Prop	Type	Default	Description
`placement`	`"auto" \| "center" \| "top" \| "bottom"`	`"auto"`	Modal position on screen
`scroll`	`"inside" \| "outside"`	`"inside"`	Scroll behavior
`size`	`"xs" \| "sm" \| "md" \| "lg" \| "cover" \| "full"`	`"md"`	Modal size variant
`className`	`string \| (values) => string`	-	Container CSS classes

Modal.Dialog

Prop	Type	Default	Description
`children`	`ReactNode \| ({close}) => ReactNode`	-	Content or render function
`className`	`string \| (values) => string`	-	CSS classes
`role`	`string`	`"dialog"`	ARIA role
`aria-label`	`string`	-	Accessibility label
`aria-labelledby`	`string`	-	ID of label element
`aria-describedby`	`string`	-	ID of description element

Modal.Header

Prop	Type	Default	Description
`children`	`ReactNode`	-	Header content
`className`	`string`	-	CSS classes

Modal.Body

Prop	Type	Default	Description
`children`	`ReactNode`	-	Body content
`className`	`string`	-	CSS classes

Modal.Footer

Prop	Type	Default	Description
`children`	`ReactNode`	-	Footer content
`className`	`string`	-	CSS classes

Modal.CloseTrigger

Prop	Type	Default	Description
`children`	`ReactNode`	-	Custom close button
`className`	`string \| (values) => string`	-	CSS classes

useOverlayState Hook

import {useOverlayState} from "@heroui/react";

const state = useOverlayState({
  defaultOpen: false,
  onOpenChange: (isOpen) => console.log(isOpen),
});

state.isOpen; // Current state
state.open(); // Open modal
state.close(); // Close modal
state.toggle(); // Toggle state
state.setOpen(); // Set state directly