‹ Modals

Types

Types

The types of modals.

SectionModalsDraftDocumented, not reviewed yet: the API can change.

ModalConfig

Interface

How showModal shows a screen.

interface ModalConfig

Member	Type	Description
style	`${OptionsModalPresentationStyle}`	The presentation style of the modal.
sheet	OptionsModalSheet	A sheet with detents (on Android the Material bottom sheet); it is a page sheet unless style says otherwise.
popover	OptionsModalPopover	A popover from a button or a view; it is a popover unless style says otherwise. iOSiPadOSAndroid (not supported)
contentSize	ModalOptions['contentSize']	The size of a form sheet. iOSiPadOSAndroid (not supported)
stack	boolean	false: the screen shows without a stack around it, so without a top bar.
closeButton	boolean	A close button at the leading edge of the modal's first screen, which dismisses the modal: the system one on iOS, an icon on Android. Its id and testID are CloseButton. Needs the stack. A new first screen of that stack, from setStack or replace, gets it too.
onDismiss	() => void	Called once the modal is gone, whatever dismissed it: a command, a swipe, a new root. setStack and replace inside the modal replace its first screen, and call it too.
transition	Transition	How the screen comes and goes: a preset ('fade', 'slideUp', 'scale'…), the zoom of iOS 18 out of a view, or views that move into the screen. The way back is the same in reverse. options.animations go over it.
options	ScreenOptionsInput<object>	Options of the screen for this show, over those of its definition.

Defined in src/api/commands/presentation.ts ↗

OptionsModalSheetDetent

Type

A stop of a sheet: 'medium' (about half of the screen), 'large' (the full height), a number (a height in points on iOS, in dp on Android) or 'content' (the height of the screen's content).

On iOS 'medium' and 'large' are the system stops; a number and 'content' need iOS 16 and are left out below it with a warning in the log. On Android 'medium' is half of the window, 'large' the full height under the status bar, a number is capped at 'large', and 'content' is the height of the content, measured as on iOS.

type OptionsModalSheetDetent = 'medium' | 'large' | 'content' | number

Defined in src/interfaces/options/modals.ts ↗

OptionsModalPresentationStyle

Type

How the platform presents a modal: 'pageSheet', 'formSheet', 'fullScreen', 'overFullScreen', 'overCurrentContext', 'currentContext' or 'popover'. It is read once, when the modal shows, from the modal's final options; mergeOptions afterwards doesn't change it, and neither does a change of theme or a rotation. Without it the platform decides: on iOS the automatic style of UIKit (a sheet on iPhone, a card on iPad), on Android the whole screen, or the Material bottom sheet when modal.sheet is set. An unknown string shows a full-screen modal on iOS and counts as not set on Android.

• 'pageSheet': a sheet that leaves the screen below visible. On iOS the screen below is pushed back, and on iPad the sheet is a wide card. On Android it is the Material modal bottom sheet over a dimmed screen, at the full height under the status bar (modal.sheet changes its stops), at most 640 dp wide and in the middle of a wider window.
• 'formSheet': on iOS a sheet on iPhone, a card in the middle on iPad whose size is modal.contentSize. On Android the same bottom sheet as 'pageSheet'; modal.contentSize does nothing there.
• 'fullScreen', 'currentContext': the whole screen; the screen below is taken off once the modal has come in. Both platforms treat the two alike. The modal comes up from the bottom: on Android with the system's motion of a window over another (300 ms up, 250 ms down), without a fade.
• 'overFullScreen', 'overCurrentContext': the same, with the screen below kept in place under the modal. It shows through only where the modal screen is transparent (layout.backgroundColor and layout.componentBackgroundColor both 'transparent'); the style does not make anything transparent by itself.
• 'popover': (iOS) a popover with an arrow on iPad, a sheet on iPhone unless modal.popover.adaptive is false. Android has no popovers and shows the bottom sheet of 'pageSheet'.

The options of the sheet (modal.sheet) apply with 'pageSheet', 'formSheet' and without a style, and on Android with 'popover' too.

type OptionsModalPresentationStyle =
  | 'pageSheet'
  | 'formSheet'
  | 'fullScreen'
  | 'overFullScreen'
  | 'overCurrentContext'
  | 'currentContext'
  | 'popover'

Defined in src/interfaces/options/modals.ts ↗

OptionsModalTransitionStyle

Type

The system transition a modal comes and goes with: 'coverVertical' (from below), 'crossDissolve' (a fade), 'flipHorizontal' (a flip) or 'partialCurl'. It is read when the modal shows and doesn't change afterwards; animations.showModal with values of its own, and the zoom of iOS 18, go over it. UIKit flips only a modal over the whole screen ('fullScreen', 'overFullScreen'): a sheet comes in as usual and flips only on its way out. UIKit curls only a 'fullScreen' modal over a screen that fills the window, so 'partialCurl' with any other modalPresentationStyle (or without one), or over a modal that doesn't fill the screen, shows as 'coverVertical'. A modal shown with 'partialCurl' can't show another modal over it: that showModal rejects. An unknown string means 'coverVertical'. Android doesn't read it.

type OptionsModalTransitionStyle =
  'coverVertical' | 'crossDissolve' | 'flipHorizontal' | 'partialCurl'

Defined in src/interfaces/options/modals.ts ↗

ModalDismissedEvent

Type

type ModalDismissedEvent = NavigationEvents['modalDismissed']

Member	Type	Description
modalsDismissedRequired	number	How many modals were closed.
screenRequired	ScreenRef

Defined in src/api/events/navigationEvents.ts ↗

ModalDismissAttemptedEvent

Type

type ModalDismissAttemptedEvent = NavigationEvents['modalDismissAttempted']

Member	Type	Description
screenRequired	ScreenRef

Defined in src/api/events/navigationEvents.ts ↗

SheetDetentChangedEvent

Type

type SheetDetentChangedEvent = NavigationEvents['sheetDetentChanged']

Member	Type	Description
detentRequired	'medium' | 'large' | 'content' | number	The detent the sheet stopped at: 'medium', 'large', 'content' (the detent that fits the content), or a height (points on iOS, dp on Android).
screenRequired	ScreenRef

Defined in src/api/events/navigationEvents.ts ↗