Modals

Learn how to use modals in Expo Router.

Using Modals with Expo Router

Learn about the different ways to display content over the rest of your app.

Modals are a common user interface pattern in mobile apps. They are used to present content on top of the existing screen and is used for different purposes, such as displaying confirmation alerts or standalone forms. You can create modals in your app using the following methods:

• Use React Native's Modal component.
• Use Expo Router's special file-based syntax to create a modal screen within the app's navigation system.

Each approach has its specific use case. Understanding when to use each method is important for creating a positive user experience.

React Native's Modal component

The Modal component is part of React Native's core API. Common use cases include:

• Standalone interactions, such as self-contained tasks that don't need to be part of the navigation system.
• Temporary alerts or confirmation dialogs that are ideal for quick interactions.

Below is an example of a custom Modal component that overlays the current screen on different platforms:

For most use cases, you can use the Modal component and customize it according to your app's user interface requirements. For details on how to use the Modal component and its props, see the React Native documentation.

Modal screen using Expo Router

A modal screen is a file created inside the app directory and is used as a route within the existing stack. It is used for complex interactions that need to be part of the navigation system, such as multi-step forms where you can link to a specific screen after the process completes.

Below is an example of how a modal screen works on different platforms:

Usage

To implement a modal route, create a screen called modal.tsx inside the app directory. Here's an example file structure:

The above file structure produces a layout where the index is the first route in the stack. Inside the root layout file (app/_layout.tsx), you can add the modal route in the stack. To present it as a modal, set the presentation option to modal on the route.

import { Stack } from 'expo-router';

export default function Layout() {
  return (
    <Stack>
      <Stack.Screen name="index" />
      <Stack.Screen
        name="modal"
        options={{
          presentation: 'modal',
        }}
      />
    </Stack>
  );
}

You can use the Link component to navigate to the modal screen from the index.tsx file.

import { Link } from 'expo-router';
import { StyleSheet, Text, View } from 'react-native';

export default function Home() {
  return (
    <View style={styles.container}>
      <Text>Home screen</Text>
      <Link href="/modal" style={styles.link}>
        Open modal
      </Link>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    alignItems: 'center',
    justifyContent: 'center',
  },
  link: {
    paddingTop: 20,
    fontSize: 20,
  },
});

The modal.tsx presents the contents of the modal.

import { StyleSheet, Text, View } from 'react-native';

export default function Modal() {
  return (
    <View style={styles.container}>
      <Text>Modal screen</Text>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    alignItems: 'center',
    justifyContent: 'center',
  },
});

Modal presentation and dismiss behavior

A modal loses its previous context when it is the current screen in the navigator and is presented as a standalone screen. Its presentation and dismissal behavior are different on each platform:

• On Android, the modal slides on top of the current screen. To dismiss it, use the back button to navigate back to the previous screen.
• On iOS, the modal slides from the bottom of the current screen. To dismiss it, swipe it down from the top.
• On web, the modal is presented as a separate route, and the dismiss behavior has to be provided manually using router.canGoBack(). Here's an example of how to dismiss the modal:

import { Link, router} from 'expo-router';
import { StyleSheet, Text, View } from 'react-native';

export default function Modal() {
  const isPresented = router.canGoBack();

  return (
    <View style={styles.container}>
      <Text>Modal screen</Text>
      {isPresented && <Link href="../">Dismiss modal</Link>}
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    alignItems: 'center',
    justifyContent: 'center',
  },
});

Change status bar appearance on iOS

By default on iOS, the modal has a dark background which hides the status bar. To change the status bar appearance, you can use the Platform API to check if the current platform is iOS and then use the StatusBar component to change the appearance inside the modal.tsx file.

import { StyleSheet, Text, View, Platform } from 'react-native';
import { StatusBar } from 'expo-status-bar';

export default function Modal() {
  return (
    <View style={styles.container}>
      <Text>Modal screen</Text>
      <StatusBar style={Platform.OS === 'ios' ? 'light' : 'auto'} />
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    alignItems: 'center',
    justifyContent: 'center',
  },
});

Additional information

Presentation options

There are different options to present a modal screen using the presentation option on Android and iOS.