Router settings

Edit this page

Learn how to configure layouts with static properties in Expo Router.

Warning: unstable_settings currently do not work with async routes (development-only). This is why the feature is designated unstable.

`initialRouteName`

When deep linking to a route, you may want to provide a user with a "back" button. The initialRouteName sets the default screen of the stack and should match a valid filename (without the extension).

app

_layout.tsx

index.tsx

other.tsx

app/_layout.tsx

import { Stack } from 'expo-router';

export const unstable_settings = {
  // Ensure any route can link back to `/`
  initialRouteName: 'index',
};

export default function Layout() {
  return <Stack />;
}

Now deep linking directly to /other or reloading the page will continue to show the back arrow.

When using array syntax (foo,bar) you can specify the name of a group in the unstable_settings object to target a particular segment.

other.tsx

export const unstable_settings = {
  // Used for `(foo)`
  initialRouteName: 'first',
  // Used for `(bar)`
  bar: {
    initialRouteName: 'second',
  },
};

The initialRouteName is only used when deep-linking to a route. During app navigation, the route you are navigating to will be the initial route. You can disable this behavior using the initial prop on the <Link /> component or by passing the option to the imperative APIs.

// If this navigates to a new _layout, don't override the initial route
<Link href="/route" initial={false} />;

router.push('/route', { overrideInitialScreen: false });