xref: /expo/docs/pages/router/reference/hooks.mdx (revision 54bfa6bf) 
1---
2title: Hooks API
3description: Learn how to interact with the in-app URL in Expo Router.
4---
5
6import { FileTree } from '~/ui/components/FileTree';
7import { RouteUrlGroup, RouteUrl } from '~/ui/components/RouteUrl';
8
9<RouteUrlGroup>
10
11In Expo Router, there's always a valid URL that represents the currently focused route. Use hooks to observe changes and interact with the URL.
12
13## `usePathname`
14
15Returns the currently selected route location without search parameters. For example, `/acme?foo=bar` -> `/acme`. Segments will be normalized: `/[id]?id=normal` -> `/normal`
16
17<RouteUrl>/profile/baconbrix?extra=info</RouteUrl>
18
19```jsx app/profile/[user].tsx
20import { Text } from 'react-native';
21/* @info */
22import { usePathname } from 'expo-router';
23/* @end */
24
25export default function Route() {
26  /* @info <b>pathname = "/profile/baconbrix"</b> */
27  const pathname = usePathname();
28  /* @end */
29
30  return <Text>User: {user}</Text>;
31}
32```
33
34## `useLocalSearchParams`
35
36Returns the URL search parameters for the contextually selected route. Refer to the [local vs. global search params](/router/reference/search-parameters/#local-vs-global-search-parameters) guide for more information.
37
38<FileTree files={['app/_layout.tsx', 'app/[first]/home.tsx', 'app/[second]/shop.tsx']} />
39
40When `/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**.
41
42<RouteUrl>/profile/baconbrix?extra=info</RouteUrl>
43
44```jsx app/profile/[user].tsx
45import { Text } from 'react-native';
46/* @info */
47import { useLocalSearchParams } from 'expo-router';
48/* @end */
49
50export default function Route() {
51  /* @info */
52  const { user, extra } = useLocalSearchParams();
53  /* @end */
54  return <Text>User: {user}</Text>;
55}
56```
57
58## `useGlobalSearchParams`
59
60Returns the URL search parameters for the globally selected route. For example, `/acme?foo=bar` -> `{ foo: "bar" }`.
61
62Refer to the [local vs global search params](/router/reference/search-parameters/#local-vs-global-search-parameters) guide for more info.
63
64<RouteUrl>/profile/baconbrix?extra=info</RouteUrl>
65
66```jsx app/profile/[user].tsx
67import { Text } from 'react-native';
68/* @info */
69import { useGlobalSearchParams } from 'expo-router';
70/* @end */
71
72export default function Route() {
73  /* @info <b>user=baconbrix</b> & <b>extra=info</b> */
74  const { user, extra } = useGlobalSearchParams();
75  /* @end */
76  return <Text>User: {user}</Text>;
77}
78```
79
80### `Href` type
81
82The `Href` type is a union of the following types:
83
84- **string**: A full path like `/profile/settings` or a relative path like `../settings`.
85- **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.
86
87## `useSegments`
88
89Returns 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]"]`.
90
91```jsx app/profile/[user].tsx
92import { Text } from 'react-native';
93/* @info */
94import { useSegments } from 'expo-router';
95/* @end */
96
97export default function Route() {
98  /* @info <b>segments = ["profile", "[user]"]</b> */
99  const segments = useSegments();
100  /* @end */
101  return <Text>Hello</Text>;
102}
103```
104
105This function can be typed using an abstract of string arrays:
106
107```jsx app/profile/[user].tsx
108import { useSegments } from 'expo-router';
109
110export default function Route() {
111  /* @info */
112  const segments = useSegments<['profile'] | ['profile', '[user]']>();
113  /* @end */
114
115  return </>
116}
117```
118
119## `useNavigation`
120
121Access the underlying React Navigation [`navigation` prop](https://reactnavigation.org/docs/navigation-prop) to imperatively access layout-specific functionality like `navigation.openDrawer()` in a Drawer layout. [Learn more](https://reactnavigation.org/docs/navigation-prop/#navigator-dependent-functions).
122
123```jsx
124/* @info */
125import { useNavigation } from 'expo-router';
126/* @end */
127
128export default function Route() {
129  /* @info Access the current navigation object for the current route */
130  const navigation = useNavigation();
131  /* @end */
132  return (
133    <View>
134      <Text
135        onPress={() => {
136          /* @info Open the drawer view */
137          navigation.openDrawer();
138          /* @end */
139        }}>
140        Open Drawer
141      </Text>
142    </View>
143  );
144}
145```
146
147## `useFocusEffect`
148
149Given a function, the `useFocusEffect` hook will invoke the function whenever the route is "focused".
150
151```jsx
152/* @info */
153import { useFocusEffect } from 'expo-router';
154/* @end */
155
156export default function Route() {
157  useFocusEffect(() => {
158    /* @info Invoked whenever the route is focused */
159    console.log('Hello')
160    /* @end */
161  })
162
163  return </>
164}
165```
166
167</RouteUrlGroup>
168