Modal components

Q: How do I install the modal component and the examples?

Add the base modal.tsx with npx untitledui add modal. The examples on this page are PRO and install one at a time with the command shown on each, for example npx untitledui@latest add modals/stacked-left-aligned.

Q: How do I control modal visibility?

Put the isOpen and onOpenChange props directly on ModalOverlay and drive them from your own state: <ModalOverlay isOpen={isOpen} onOpenChange={setIsOpen} isDismissable>. Anything inside the modal can then close it by calling setIsOpen(false), and a CloseButton closes it without a handler because it fills React Aria's "close" slot.

Q: What components make up a modal?

Three components from modal.tsx, nested in this order: ModalOverlay (holds the open state through isOpen/onOpenChange and renders the backdrop and positioning), Modal (the container, including the zoom animations), and Dialog (the content wrapper). Add a CloseButton inside the Dialog yourself if you want a close icon in the corner.

Q: How do I prevent users from closing a modal?

Leave isDismissable off ModalOverlay (it defaults to false) so clicking the backdrop does nothing, and pass isKeyboardDismissDisabled to stop Escape from closing it. Neither prop affects a CloseButton, so remove that too if the examples you copied include one.

Q: How do I customize modal animations?

ModalOverlay fades in over 300ms and out over 200ms, and Modal zooms in from and out to 95% scale with the same timings. Both accept a className function that receives isEntering and isExiting, and your classes are merged last with tailwind-merge, so they override the defaults.

Q: How do modals behave on small screens?

Below the sm breakpoint the overlay aligns the modal to the bottom of the screen; from sm up it is centered. The modal's max height is capped to the visible viewport minus the overlay padding, and Dialog scrolls its content when it is taller than that.

Q: What do I need to do to make a modal accessible?

Give each Dialog an accessible name, either with a React Aria Heading using slot="title", as the examples do, or with aria-label. React Aria handles the rest: focus is contained inside the modal while it is open and returns to the previously focused element when it closes, and Escape closes it unless isKeyboardDismissDisabled is set.

Powerful and customizable React modal components built for modern applications and websites. These modals are built using React Aria and styled with Tailwind CSS.

Installation

You can add this modal component using our CLI or manually:

CLI

Manual

npx untitledui add modal

Modals examples

Below are examples and variations of this modals component:

API reference

DatePickerModal

Import DatePickerModal from @/components/application/modals/date-picker-modal. Renders React Aria’s DateRangePicker — all of its props are supported.

DatePickerModal props
Prop	Type	Default	Description
`onApply`	`(() => void)`	—	Called when the user presses Apply, just before the modal closes. Use it to commit the range reported by `onChange`.
`onCancel`	`(() => void)`	—	Called when the user presses Cancel, just before the modal closes. Use it to revert to the range you held before the modal opened.

Props from React Aria (41)

DatePickerModal inherited props
Prop	Type	Default	Description
`onBlur`	`((e: FocusEvent<Element, Element>) => void)`	—	Handler that is called when the element loses focus.
`onFocus`	`((e: FocusEvent<Element, Element>) => void)`	—	Handler that is called when the element receives focus.
`onFocusChange`	`((isFocused: boolean) => void)`	—	Handler that is called when the element's focus status changes.
`autoFocus`	`boolean`	—	Whether the element should receive focus on render.
`onKeyDown`	`((e: KeyboardEvent) => void)`	—	Handler that is called when a key is pressed.
`onKeyUp`	`((e: KeyboardEvent) => void)`	—	Handler that is called when a key is released.
`form`	`string`	—	The `<form>` element to associate the input with. The value of this attribute must be the id of a `<form>` in the same document.
`allowsNonContiguousRanges`	`boolean`	—	When combined with `isDateUnavailable`, determines whether non-contiguous ranges, i.e. ranges containing unavailable dates, may be selected.
`defaultOpen`	`boolean`	—	Whether the overlay is open by default (uncontrolled).
`defaultValue`	`RangeValue<DateValue> \| null`	—	The default value (uncontrolled).
`description`	`ReactNode`	—	A description for the field. Provides a hint such as specific requirements for what to choose.
`endName`	`string`	—	The name of the end date input element, used when submitting an HTML form.
`errorMessage`	`ReactNode \| ((v: ValidationResult) => ReactNode)`	—	An error message for the field.
`firstDayOfWeek`	`"sun""mon""tue""wed""thu""fri""sat"`	—	The day that starts the week.
`granularity`	`"day""hour""minute""second"`	—	Determines the smallest unit that is displayed in the date picker. By default, this is `"day"` for dates, and `"minute"` for times.
`hideTimeZone`	`boolean`	`false`	Whether to hide the time zone abbreviation.
`hourCycle`	`1224`	—	Whether to display the time in 12 or 24 hour format. By default, this is determined by the user's locale.
`id`	`string`	—	The element's unique identifier.
`isDateUnavailable`	`((date: DateValue, anchorDate: CalendarDate \| null) => boolean)`	—	Callback that is called for each date of the calendar. If it returns true, then the date is unavailable.
`isDisabled`	`boolean`	—	Whether the input is disabled.
`isInvalid`	`boolean`	—	Whether the input value is invalid.
`isOpen`	`boolean`	—	Whether the overlay is open by default (controlled).
`isReadOnly`	`boolean`	—	Whether the input can be selected but not changed by the user.
`isRequired`	`boolean`	—	Whether user input is required on the input before form submission.
`label`	`ReactNode`	—	The content to display as the label.
`maxValue`	`DateValue \| null`	—	The maximum allowed date that a user may select.
`minValue`	`DateValue \| null`	—	The minimum allowed date that a user may select.
`onChange`	`((value: RangeValue<DateValue> \| null) => void)`	—	Handler that is called when the value changes.
`onOpenChange`	`((isOpen: boolean) => void)`	—	Handler that is called when the overlay's open state changes.
`pageBehavior`	`"single""visible"`	`visible`	Controls the behavior of paging. Pagination either works by advancing the visible page by visibleDuration (default) or one unit of visibleDuration.
`placeholderValue`	`DateValue \| null`	—	A placeholder date that influences the format of the placeholder shown when no value is selected. Defaults to today's date at midnight.
`shouldForceLeadingZeros`	`boolean`	—	Whether to always show leading zeros in the month, day, and hour fields. By default, this is determined by the user's locale.
`startName`	`string`	—	The name of the start date input element, used when submitting an HTML form.
`validate`	`((value: RangeValue<DateValue>) => ValidationError \| true \| null \| undefined)`	—	A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if `validationBehavior="native"`. For realtime validation, use the `isInvalid` prop instead.
`validationBehavior`	`"aria""native"`	`"aria"`	Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA.
`validationState`	`"valid""invalid"`	—	Deprecated.—
`value`	`RangeValue<DateValue> \| null`	—	The current value (controlled).
`aria-describedby`	`string`	—	Identifies the element (or elements) that describes the object.
`aria-details`	`string`	—	Identifies the element (or elements) that provide a detailed, extended description for the object.
`aria-label`	`string`	`"Date range picker"`	Defines a string value that labels the current element.
`aria-labelledby`	`string`	—	Identifies the element (or elements) that labels the current element.

Dialog

Import Dialog from @/components/application/modals/modal. Renders React Aria’s Dialog — all of its props are supported.

Dialog props
Prop	Type	Default	Description
`children`	`ReactNode \| ((opts: DialogRenderProps) => ReactNode)`	—	Children of the dialog. A function may be provided to access a function to close the dialog.
`id`	`string`	—	The element's unique identifier.

Styling (4)

Dialog styling props
Prop	Type	Default	Description
`slot`	`string \| null`	—	A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent.
`className`	`string`	—	The CSS className for the element.
`render`	`DOMRenderFunction<"section", undefined>`	—	Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components.Requirements: You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). Only a single root DOM element can be rendered (no fragments). You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate.
`style`	`CSSProperties`	—	The inline style for the element.

Accessibility (5)

Dialog accessibility props
Prop	Type	Default	Description
`aria-describedby`	`string`	—	Identifies the element (or elements) that describes the object.
`aria-details`	`string`	—	Identifies the element (or elements) that provide a detailed, extended description for the object.
`aria-label`	`string`	—	Defines a string value that labels the current element.
`aria-labelledby`	`string`	—	Identifies the element (or elements) that labels the current element.
`role`	`"dialog""alertdialog"`	`"dialog"`	The accessibility role for the dialog.

Also accepts the global HTML attributes (dir, lang, hidden, inert, translate), all standard React DOM event handlers.

Modal

Import Modal from @/components/application/modals/modal. Renders React Aria’s Modal — all of its props are supported.

Modal props
Prop	Type	Default	Description
`defaultOpen`	`boolean`	—	Whether the overlay is open by default (uncontrolled).
`isDismissable`	`boolean`	`false`	Whether to close the modal when the user interacts outside it.
`isEntering`	`boolean`	—	Whether the modal is currently performing an entry animation.
`isExiting`	`boolean`	—	Whether the modal is currently performing an exit animation.
`isKeyboardDismissDisabled`	`boolean`	`false`	Whether pressing the escape key to close the modal should be disabled.
`isOpen`	`boolean`	—	Whether the overlay is open by default (controlled).
`onOpenChange`	`((isOpen: boolean) => void)`	—	Handler that is called when the overlay's open state changes.
`shouldCloseOnInteractOutside`	`((element: Element) => boolean)`	—	When user interacts with the argument element outside of the overlay ref, return true if onClose should be called. This gives you a chance to filter out interaction with elements that should not dismiss the overlay. By default, onClose will always be called on interaction outside the overlay ref.

Styling (5)

Modal styling props
Prop	Type	Default	Description
`style`	`StyleOrFunction<ModalRenderProps>`	—	The inline style for the element. A function may be provided to compute the style based on component state.
`children`	`ChildrenOrFunction<ModalRenderProps>`	—	The children of the component. A function may be provided to alter the children based on component state.
`slot`	`string \| null`	—	A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent.
`className`	`ClassNameOrFunction<ModalRenderProps>`	—	The CSS className for the element. A function may be provided to compute the class based on component state.
`render`	`DOMRenderFunction<"div", ModalRenderProps>`	—	Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components.Requirements: You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). Only a single root DOM element can be rendered (no fragments). You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate.

Also accepts the global HTML attributes (dir, lang, hidden, inert, translate), all standard React DOM event handlers.

ModalOverlay

Import ModalOverlay from @/components/application/modals/modal. Renders React Aria’s ModalOverlay — all of its props are supported.

ModalOverlay props
Prop	Type	Default	Description
`defaultOpen`	`boolean`	—	Whether the overlay is open by default (uncontrolled).
`isDismissable`	`boolean`	`false`	Whether to close the modal when the user interacts outside it.
`isEntering`	`boolean`	—	Whether the modal is currently performing an entry animation.
`isExiting`	`boolean`	—	Whether the modal is currently performing an exit animation.
`isKeyboardDismissDisabled`	`boolean`	`false`	Whether pressing the escape key to close the modal should be disabled.
`isOpen`	`boolean`	—	Whether the overlay is open by default (controlled).
`onOpenChange`	`((isOpen: boolean) => void)`	—	Handler that is called when the overlay's open state changes.
`shouldCloseOnInteractOutside`	`((element: Element) => boolean)`	—	When user interacts with the argument element outside of the overlay ref, return true if onClose should be called. This gives you a chance to filter out interaction with elements that should not dismiss the overlay. By default, onClose will always be called on interaction outside the overlay ref.

Styling (5)

ModalOverlay styling props
Prop	Type	Default	Description
`style`	`StyleOrFunction<ModalRenderProps>`	—	The inline style for the element. A function may be provided to compute the style based on component state.
`children`	`ChildrenOrFunction<ModalRenderProps>`	—	The children of the component. A function may be provided to alter the children based on component state.
`slot`	`string \| null`	—	A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent.
`className`	`ClassNameOrFunction<ModalRenderProps>`	—	The CSS className for the element. A function may be provided to compute the class based on component state.
`render`	`DOMRenderFunction<"div", ModalRenderProps>`	—	Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components.Requirements: You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). Only a single root DOM element can be rendered (no fragments). You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate.

Also accepts the global HTML attributes (dir, lang, hidden, inert, translate), all standard React DOM event handlers.

FAQs

Please refer to our frequently asked questions page for more.

Add the base modal.tsx with npx untitledui add modal. The examples on this page are PRO and install one at a time with the command shown on each, for example npx untitledui@latest add modals/stacked-left-aligned.

Put the isOpen and onOpenChange props directly on ModalOverlay and drive them from your own state: <ModalOverlay isOpen={isOpen} onOpenChange={setIsOpen} isDismissable>. Anything inside the modal can then close it by calling setIsOpen(false), and a CloseButton closes it without a handler because it fills React Aria's "close" slot.

Three components from modal.tsx, nested in this order: ModalOverlay (holds the open state through isOpen/onOpenChange and renders the backdrop and positioning), Modal (the container, including the zoom animations), and Dialog (the content wrapper). Add a CloseButton inside the Dialog yourself if you want a close icon in the corner.

Leave isDismissable off ModalOverlay (it defaults to false) so clicking the backdrop does nothing, and pass isKeyboardDismissDisabled to stop Escape from closing it. Neither prop affects a CloseButton, so remove that too if the examples you copied include one.

ModalOverlay fades in over 300ms and out over 200ms, and Modal zooms in from and out to 95% scale with the same timings. Both accept a className function that receives isEntering and isExiting, and your classes are merged last with tailwind-merge, so they override the defaults.

Below the sm breakpoint the overlay aligns the modal to the bottom of the screen; from sm up it is centered. The modal's max height is capped to the visible viewport minus the overlay padding, and Dialog scrolls its content when it is taller than that.

Give each Dialog an accessible name, either with a React Aria Heading using slot="title", as the examples do, or with aria-label. React Aria handles the rest: focus is contained inside the modal while it is open and returns to the previously focused element when it closes, and Escape closes it unless isKeyboardDismissDisabled is set.

Metrics Notifications