HomeGuidesReferenceLearn
ArchiveExpo SnackDiscord and ForumsNewsletter

Hooks API

Learn how to interact with the in-app URL in Expo Router.


In Expo Router, there's always a valid URL that represents the currently focused route. Use hooks to observe changes and interact with the URL.

Hooks

useFocusEffect

Given a function, the useFocusEffect hook will invoke the function whenever the route is "focused".

import { useFocusEffect } from 'expo-router';
import { useCallback } from 'react';

export default function Route() {
  useFocusEffect(
    useCallback(() => {
      console.log('Hello, I am focused!');

      return () => {
        console.log('This route is now unfocused.');
      }
    }, []);
  );

  return </>;
}

useGlobalSearchParams

Returns the URL search parameters for the globally selected route. For example, /acme?foo=bar -> { foo: "bar" }.

Refer to the local vs global search params guide for more info.

acme://profile/baconbrix?extra=info
app/profile/[user].tsx
import { Text } from 'react-native';
import { useGlobalSearchParams } from 'expo-router';

export default function Route() {
  const { user, extra } = useGlobalSearchParams();

  return <Text>User: {user}</Text>;
}

useLocalSearchParams

Returns the URL search parameters for the contextually selected route. Refer to the local versus global search params guide for more information.

app
_layout.tsx
[first]
  home.tsx
[second]
  shop.tsx

When /abc/home pushes /123/shop, useGlobalSearchParams returns { first: undefined, second: '123' } on /app/[first]/home.tsx because the global URL has changed. However, you may want the params to remain { first: 'abc' } to reflect the context of the screen. In this case, you can use useLocalSearchParams to ensure the params { first: 'abc' } are still returned in /app/[first]/home.tsx.

acme://profile/baconbrix?extra=info
app/profile/[user].tsx
import { Text } from 'react-native';
import { useLocalSearchParams } from 'expo-router';

export default function Route() {
  const { user, extra } = useLocalSearchParams();

  return <Text>User: {user}</Text>;
}

useNavigation

Access the underlying React Navigation navigation prop to imperatively access layout-specific functionality like navigation.openDrawer() in a Drawer layout. Learn more.

import { useNavigation } from 'expo-router';

export default function Route() {
  const navigation = useNavigation();

  return (
    <View>
      <Text
        onPress={() => {
          navigation.openDrawer();
        }}>
        Open Drawer
      </Text>
    </View>
  );
}

When using nested layouts, you can access higher-order layouts by passing a secondary argument denoting the layout route. For example:

app
_layout.jsuseNavigation('/')
orders
  _layout.jsuseNavigation('/orders')
  menu
   _layout.jsuseNavigation('/orders/menu')
app/orders/menu/index.tsx
import { useNavigation } from 'expo-router';

export default function MenuRoute() {
  const rootLayout = useNavigation('/');

  const ordersLayout = useNavigation('/orders');

  // Same as the default results of `useNavigation()` when invoked in this route.
  const parentLayout = useNavigation('/orders/menu');

  %%placeholder-start%%... %%placeholder-end%%
}

If you attempt to access a layout that doesn't exist, an error such as Could not find parent navigation with route "/non-existent". is thrown.

usePathname

Returns the currently selected route location without search parameters. For example, /acme?foo=bar -> /acme. Segments will be normalized: /[id]?id=normal -> /normal

acme://profile/baconbrix?extra=info
app/profile/[user].tsx
import { Text } from 'react-native';
import { usePathname } from 'expo-router';

export default function Route() {
  const pathname = usePathname();

  return <Text>User: {user}</Text>;
}

useSegments

Returns a list of segments for the currently selected route. Segments are not normalized so that they will be the same as the file path. For example, /[id]?id=normal -> ["[id]"].

app/profile/[user].tsx
import { Text } from 'react-native';
import { useSegments } from 'expo-router';

export default function Route() {
  const segments = useSegments();

  return <Text>Hello</Text>;
}

This function can be typed using an abstract of string arrays:

app/profile/[user].tsx
import { useSegments } from 'expo-router';

export default function Route() {
  const segments = useSegments<['profile'] | ['profile', '[user]']>();

  return </>
}

Types

Href

The Href type is a union of the following types:

  • string: A full path like /profile/settings or a relative path like ../settings.
  • object: An object with a pathname and optional params object. The pathname can be a full path like /profile/settings or a relative path like ../settings. The params can be an object of key/value pairs.