Types
The types of screen options.
OptionsChain
The modifiers of the options of a screen. Each modifier returns a copy with the options merged over the ones before, so the last one wins; options() takes anything the modifiers don't cover.
class OptionsChain
| Member | Type | Description |
|---|---|---|
| options | options(options: Options): this | Any options. |
| topBar | topBar(topBar: OptionsTopBar): this | |
| largeTitle | largeTitle(largeTitle: boolean | OptionsTopBarLargeTitle = true): this | iOSiPadOSAndroid (not supported) |
| backButton | backButton(backButton: OptionsTopBarBackButton): this | |
| hideTopBar | hideTopBar(hidden = true): this | Hides the top bar; |
| hideBottomTabs | hideBottomTabs(hidden = true): this | Hides the tab bar under this screen; |
| layout | layout(layout: OptionsLayout): this | |
| safeArea | safeArea(...edges: SafeAreaEdge[]): this | The edges on which the screen keeps its content out of its safe area (bars, status bar, home indicator, cutout); none with no edge. Without it: the top and the sides, but those where the content goes under a bar; the bottom is free, and a list keeps clear of it with |
| backgroundColor | backgroundColor(backgroundColor: Color): this | |
| orientation | orientation(...orientation: LayoutOrientation[]): this | |
| verticalBars | verticalBars(verticalBars = true): this |
|
| statusBar | statusBar(statusBar: OptionsStatusBar): this | |
| navigationBar | navigationBar(navigationBar: NavigationBarOptions): this | |
| scrollEdgeEffect | scrollEdgeEffect(scrollEdgeEffect: OptionsScrollEdgeEffect): this | iOSiPadOSAndroid (not supported) |
| popGesture | popGesture(popGesture: boolean | 'edge'): this | iOSiPadOSAndroid (not supported) |
| hardwareBackButton | hardwareBackButton(hardwareBackButton: HardwareBackButtonOptions): this | |
| animations | animations(animations: Pick<AnimationOptions, 'push' | 'pop'>): this | |
| bottomTabs | bottomTabs(bottomTabs: OptionsBottomTabs): this | |
| sideMenu | sideMenu(sideMenu: OptionsSideMenu): this | |
| ios | ios(build: (options: this) => this): this | Modifiers for iOS only. |
| android | android(build: (options: this) => this): this | Modifiers for Android only. |
ScreenOptionsInput
The options of a screen: options as they are, or a chain built from its props, the theme and the context.
type ScreenOptionsInput<Props> =
Options | ((options: ScreenOptions, props: Props, app: OptionsEnvironment) => ScreenOptions)
| Member | Type | Description |
|---|---|---|
| topBar | OptionsTopBar | The bar at the top of a screen in a stack: its title, buttons, back button, search and look. |
| toolbar | OptionsToolbar | The toolbar at the bottom of a screen in a stack. |
| scrollEdgeEffect | OptionsScrollEdgeEffect | (iOS 26+) How the content fades or blurs where it scrolls under a bar. |
| bottomTabs | OptionsBottomTabs | The tab bar of the tabs the screen is in, while the screen shows. |
| bottomTab | OptionsBottomTab | The tab of a screen that is a tab of a tab bar (or the first screen of a stack that is one). |
| modal | ModalOptions | A screen shown as a modal: how it is presented, how it can be dismissed, its sheet. |
| modalPresentationStyle | OptionsModalPresentationStyle | How a modal is presented: full screen, as a page sheet, a form sheet, a popover… |
| modalTransitionStyle | OptionsModalTransitionStyle | The system transition of a modal: cover vertical, flip horizontal, cross dissolve, partial curl. |
| overlay | OverlayOptions | A screen shown as an overlay: whether touches outside its content go through to what is below. |
| sideMenu | OptionsSideMenu | The side menus of the side menu the screen is in: their visibility, width, gestures. |
| splitView | OptionsSplitView | The split view the screen is in: its columns, their widths, how they show. |
| layout | OptionsLayout | The screen's layout: its background, safe area, orientation. |
| statusBar | OptionsStatusBar | The status bar while the screen shows. |
| navigationBar | NavigationBarOptions | The navigation bar while the screen shows. |
| animations | AnimationOptions | The transitions of the commands: push, pop, modals, the root, and elements that move between screens. |
| popGesture | boolean | 'edge' | The swipe back in the stack: |
| hardwareBackButton | HardwareBackButtonOptions | What the system back button and the back gesture do on the screen. |
| fab | OptionsFab | The floating action button of the screen. |
| keyCommands | OptionsKeyCommand[] | The keyboard shortcuts of the screen, shown by the system when a hardware keyboard is held. |
| blurOnUnmount | boolean | Whether a text field of the screen loses the focus, and the keyboard hides, as the screen leaves: when the transition that takes it away starts (a pop, a modal's dismiss, a new stack root or app root), so the keyboard doesn't stay up during the transition. |
| preview | PreviewOptions | The preview of a pushed screen, for a view of the screen it is pushed from (iOS). Set by |
OptionsEnvironment
What the options of a screen can read besides its props, as they are when a command shows the screen.
interface OptionsEnvironment
| Member | Type | Description |
|---|---|---|
| themeRequired | NavigationTheme | |
| contextRequired | RegisteredContext |
Options
The options of a screen or a container. A screen shows its own options over those of its containers (its stack, its tabs, its side menu), and all of them over the default options of the app. Objects merge key by key, arrays and values replace what was there, and a key left out keeps what the layers below give.
interface Options
| Member | Type | Description |
|---|---|---|
| topBar | OptionsTopBar | The bar at the top of a screen in a stack: its title, buttons, back button, search and look. |
| toolbar | OptionsToolbar | The toolbar at the bottom of a screen in a stack. |
| scrollEdgeEffect | OptionsScrollEdgeEffect | (iOS 26+) How the content fades or blurs where it scrolls under a bar. |
| bottomTabs | OptionsBottomTabs | The tab bar of the tabs the screen is in, while the screen shows. |
| bottomTab | OptionsBottomTab | The tab of a screen that is a tab of a tab bar (or the first screen of a stack that is one). |
| modal | ModalOptions | A screen shown as a modal: how it is presented, how it can be dismissed, its sheet. |
| modalPresentationStyle | OptionsModalPresentationStyle | How a modal is presented: full screen, as a page sheet, a form sheet, a popover… |
| modalTransitionStyle | OptionsModalTransitionStyle | The system transition of a modal: cover vertical, flip horizontal, cross dissolve, partial curl. |
| overlay | OverlayOptions | A screen shown as an overlay: whether touches outside its content go through to what is below. |
| sideMenu | OptionsSideMenu | The side menus of the side menu the screen is in: their visibility, width, gestures. |
| splitView | OptionsSplitView | The split view the screen is in: its columns, their widths, how they show. |
| layout | OptionsLayout | The screen's layout: its background, safe area, orientation. |
| statusBar | OptionsStatusBar | The status bar while the screen shows. |
| navigationBar | NavigationBarOptions | The navigation bar while the screen shows. |
| animations | AnimationOptions | The transitions of the commands: push, pop, modals, the root, and elements that move between screens. |
| popGesture | boolean | 'edge' | The swipe back in the stack: |
| hardwareBackButton | HardwareBackButtonOptions | What the system back button and the back gesture do on the screen. |
| fab | OptionsFab | The floating action button of the screen. |
| keyCommands | OptionsKeyCommand[] | The keyboard shortcuts of the screen, shown by the system when a hardware keyboard is held. |
| blurOnUnmount | boolean | Whether a text field of the screen loses the focus, and the keyboard hides, as the screen leaves: when the transition that takes it away starts (a pop, a modal's dismiss, a new stack root or app root), so the keyboard doesn't stay up during the transition. |
| preview | PreviewOptions | The preview of a pushed screen, for a view of the screen it is pushed from (iOS). Set by |
Color
A color of an option: a color string ('#1E88E5', 'rgba(0,0,0,0.5)', 'red'), a PlatformColor or DynamicColorIOS, or { light, dark } for each appearance. null takes the color away: the element shows as the platform draws it without the option, also over a color its stack, its tabs or the default options give. A color string the app can't parse counts as not set.
type Color = ColorValue | ThemeColor | null
| Member | Type | Description |
|---|---|---|
| light | ColorValue | The color in the light appearance: a color string or a |
| dark | ColorValue | The color in the dark appearance: a color string or a |
ImageResource
An image of an option: require('./icon.png'), a source with a uri (a file, an asset of the app's bundle, a data: address on iOS), the name of an Android drawable resource, or a different icon for each platform ({ ios, android }). Remote addresses (https:) are not loaded, apart from Metro's assets in development; an image that doesn't load leaves its element without an icon and reports the error in development.
type ImageResource = ImageRequireSource | ImageURISource | string | PlatformIcon
| Member | Type | Description |
|---|---|---|
| ios | string | ImageRequireSource | ImageURISource | The icon on iOS: the name of an SF Symbol, or an image. |
| android | string | ImageRequireSource | ImageURISource | The icon on Android: the name of a drawable resource of the app, or an image. |
PlatformIcon
A different icon for each platform: { ios: 'square.and.arrow.up', android: 'ic_share' }. A string is the name of an SF Symbol on iOS and of a drawable resource of the app on Android; an image source works on either side. A platform without its side shows no icon.
interface PlatformIcon
| Member | Type | Description |
|---|---|---|
| ios | string | ImageRequireSource | ImageURISource | The icon on iOS: the name of an SF Symbol, or an image. |
| android | string | ImageRequireSource | ImageURISource | The icon on Android: the name of a drawable resource of the app, or an image. |