1# Search
2 
3## Header Search Bar
4 
5Add a search bar to the stack header with `headerSearchBarOptions`:
6 
7```tsx
8<Stack.Screen
9  name="index"
10  options={{
11    headerSearchBarOptions: {
12      placeholder: "Search",
13      onChangeText: (event) => console.log(event.nativeEvent.text),
14    },
15  }}
16/>
17```
18 
19### Options
20 
21```tsx
22headerSearchBarOptions: {
23  // Placeholder text
24  placeholder: "Search items...",
25 
26  // Auto-capitalize behavior
27  autoCapitalize: "none",
28 
29  // Input type
30  inputType: "text", // "text" | "phone" | "number" | "email"
31 
32  // Cancel button text (iOS)
33  cancelButtonText: "Cancel",
34 
35  // Hide when scrolling (iOS)
36  hideWhenScrolling: true,
37 
38  // Hide navigation bar during search (iOS)
39  hideNavigationBar: true,
40 
41  // Obscure background during search (iOS)
42  obscureBackground: true,
43 
44  // Placement
45  placement: "automatic", // "automatic" | "inline" | "stacked"
46 
47  // Callbacks
48  onChangeText: (event) => {},
49  onSearchButtonPress: (event) => {},
50  onCancelButtonPress: (event) => {},
51  onFocus: () => {},
52  onBlur: () => {},
53}
54```
55 
56## useSearch Hook
57 
58Reusable hook for search state management:
59 
60```tsx
61import { useEffect, useState } from "react";
62import { useNavigation } from "expo-router";
63 
64export function useSearch(options: any = {}) {
65  const [search, setSearch] = useState("");
66  const navigation = useNavigation();
67 
68  useEffect(() => {
69    navigation.setOptions({
70      headerShown: true,
71      headerSearchBarOptions: {
72        ...options,
73        onChangeText(e: any) {
74          setSearch(e.nativeEvent.text);
75          options.onChangeText?.(e);
76        },
77        onSearchButtonPress(e: any) {
78          setSearch(e.nativeEvent.text);
79          options.onSearchButtonPress?.(e);
80        },
81        onCancelButtonPress(e: any) {
82          setSearch("");
83          options.onCancelButtonPress?.(e);
84        },
85      },
86    });
87  }, [options, navigation]);
88 
89  return search;
90}
91```
92 
93### Usage
94 
95```tsx
96function SearchScreen() {
97  const search = useSearch({ placeholder: "Search items..." });
98 
99  const filteredItems = items.filter(item =>
100    item.name.toLowerCase().includes(search.toLowerCase())
101  );
102 
103  return (
104    <FlatList
105      data={filteredItems}
106      renderItem={({ item }) => <ItemRow item={item} />}
107    />
108  );
109}
110```
111 
112## Filtering Patterns
113 
114### Simple Text Filter
115 
116```tsx
117const filtered = items.filter(item =>
118  item.name.toLowerCase().includes(search.toLowerCase())
119);
120```
121 
122### Multiple Fields
123 
124```tsx
125const filtered = items.filter(item => {
126  const query = search.toLowerCase();
127  return (
128    item.name.toLowerCase().includes(query) ||
129    item.description.toLowerCase().includes(query) ||
130    item.tags.some(tag => tag.toLowerCase().includes(query))
131  );
132});
133```
134 
135### Debounced Search
136 
137For expensive filtering or API calls:
138 
139```tsx
140import { useState, useEffect, useMemo } from "react";
141 
142function useDebounce<T>(value: T, delay: number): T {
143  const [debounced, setDebounced] = useState(value);
144 
145  useEffect(() => {
146    const timer = setTimeout(() => setDebounced(value), delay);
147    return () => clearTimeout(timer);
148  }, [value, delay]);
149 
150  return debounced;
151}
152 
153function SearchScreen() {
154  const search = useSearch();
155  const debouncedSearch = useDebounce(search, 300);
156 
157  const filteredItems = useMemo(() =>
158    items.filter(item =>
159      item.name.toLowerCase().includes(debouncedSearch.toLowerCase())
160    ),
161    [debouncedSearch]
162  );
163 
164  return <FlatList data={filteredItems} />;
165}
166```
167 
168## Search with Native Tabs
169 
170When using NativeTabs with a search role, the search bar integrates with the tab bar:
171 
172```tsx
173// app/_layout.tsx
174<NativeTabs>
175  <NativeTabs.Trigger name="(home)">
176    <Label>Home</Label>
177    <Icon sf="house.fill" />
178  </NativeTabs.Trigger>
179  <NativeTabs.Trigger name="(search)" role="search">
180    <Label>Search</Label>
181  </NativeTabs.Trigger>
182</NativeTabs>
183```
184 
185```tsx
186// app/(search)/_layout.tsx
187<Stack>
188  <Stack.Screen
189    name="index"
190    options={{
191      headerSearchBarOptions: {
192        placeholder: "Search...",
193        onChangeText: (e) => setSearch(e.nativeEvent.text),
194      },
195    }}
196  />
197</Stack>
198```
199 
200## Empty States
201 
202Show appropriate UI when search returns no results:
203 
204```tsx
205function SearchResults({ search, items }) {
206  const filtered = items.filter(/* ... */);
207 
208  if (search && filtered.length === 0) {
209    return (
210      <View style={{ flex: 1, justifyContent: "center", alignItems: "center" }}>
211        <Text style={{ color: PlatformColor("secondaryLabel") }}>
212          No results for "{search}"
213        </Text>
214      </View>
215    );
216  }
217 
218  return <FlatList data={filtered} />;
219}
220```
221 
222## Search Suggestions
223 
224Show recent searches or suggestions:
225 
226```tsx
227function SearchScreen() {
228  const search = useSearch();
229  const [recentSearches, setRecentSearches] = useState<string[]>([]);
230 
231  if (!search && recentSearches.length > 0) {
232    return (
233      <View>
234        <Text style={{ color: PlatformColor("secondaryLabel") }}>
235          Recent Searches
236        </Text>
237        {recentSearches.map((term) => (
238          <Pressable key={term} onPress={() => /* apply search */}>
239            <Text>{term}</Text>
240          </Pressable>
241        ))}
242      </View>
243    );
244  }
245 
246  return <SearchResults search={search} />;
247}
248```
249