@apexnative/navigation 0.0.0-stage → 1.0.0-alpha.0

package/docs-md/screen-ui/back-and-gestures.md

@@ -0,0 +1,178 @@
+# Back and gestures
+
+Every way the user goes back on each platform, the back button and its look, the swipe back, the system back of Android, and how to keep the user on a screen with unsaved changes.
+
+Going back is the move users make most, and each platform has its own ways for it. Every screen pushed on a stack gets them all without code. What an app changes is the look of the back button, and whether the user may leave a screen, such as one with an unsaved draft:
+
+```tsx
+import { defineScreen } from '@apexnative/navigation';
+
+export const DetailsScreen = defineScreen({
+  component: Details,
+  options: (s) => s.backButton({ title: 'Inbox' }),
+});
+```
+
+On iOS the back button of Details reads "Inbox". This page answers:
+
+1. [The ways back](#ways) on each platform.
+2. [The back button](#back-button): [its title](#title) and [its look](#look).
+3. [The swipe back](#swipe) of iOS, and [the system back](#system-back) of Android.
+4. [How to keep the user on a screen](#prevent) with unsaved changes.
+
+## The ways back
+
+| Platform | The user goes back with |
+| --- | --- |
+| (iOS) | The back button of the bar. A swipe from the left edge, and on iOS 26 from anywhere on the content. A long press on the back button opens the history, to jump back several screens. A swipe down closes a sheet. |
+| (Android) | The back arrow of the bar. The system back: a button, or a swipe from either edge. |
+
+Each of them goes back one step **where the user is**: a pushed screen pops, a modal closes. The app itself goes back with commands: see [Going back](../fundamentals/moving-between-screens#back).
+
+## The back button
+
+The back button shows by itself on every screen but the first of a stack. **A screen sets its own back button**, in its own options, as in the example above. In UIKit the screen underneath sets it; here the screen that has the button does, so its options say everything about it.
+
+### Its title
+
+(iOS) The back button can show the title of the screen it goes back to, "Back", or the arrow alone. When the bar is full, it gets shorter by itself:
+
+| Option | What it does |
+| --- | --- |
+| `title` | A title of its own instead of the one of the screen under it. |
+| `showTitle` | `true` shows the title of the screen under it, `false` the arrow alone. Without it the system decides: on iOS 26 the arrow alone. |
+| `displayMode` | How it gets shorter: `'default'` the title, then "Back", then the arrow; `'generic'` "Back", then the arrow; `'minimal'` the arrow alone. |
+
+An app that wants the arrow alone everywhere sets it once, in the app defaults:
+
+```ts
+export const Navigation = createNavigation({
+  // …
+  options: (s) => s.backButton({ showTitle: false }),
+});
+```
+
+(Android) The back arrow has no title: the bar shows the title of the screen itself next to it.
+
+### Its look
+
+| Option | What it does |
+| --- | --- |
+| `color` | The color of the arrow and the title. Without it, the `primary` color of the theme. |
+| `icon` | Another arrow: an image, or an icon for each platform, `{ ios: 'xmark', android: 'ic_close' }`. |
+| `visible: false` | No back button. |
+| `enableMenu: false` | (iOS) No history on a long press: the screen gets a back button of its own instead of the system one. |
+| `hideSharedBackground` | (iOS) 26: `false` puts the button on a glass capsule. |
+
+`fontSize`, `fontWeight` and `fontStyle` style the title, and `fontFamily` too on iOS.
+
+`visible: false` only hides the button. To keep the user on a screen, hide nothing: [hold the leave](#prevent) instead, which holds the swipe and the system back too.
+
+## The swipe back
+
+(iOS) A swipe from the left edge goes back, following the finger: the user can stop halfway and stay. On iOS 26 a swipe from anywhere on the content does the same. Content that swipes sideways itself, such as a carousel or a map, can clash with it, so a screen can narrow the swipe:
+
+```ts
+export const MapScreen = defineScreen({
+  component: Map,
+  options: (s) => s.popGesture('edge'),
+});
+```
+
+| `popGesture` | The swipe back |
+| --- | --- |
+| `true` | From the edge and from the content: the default. |
+| `'edge'` | From the edge only: a swipe on the content stays with the content. |
+| `false` | Off. The back button still works. |
+
+(Android) The system back swipes from either edge; the app doesn't change it.
+
+## The system back of Android
+
+(Android) The system back goes one step back where the user is, in this order:
+
+| Where | The system back |
+| --- | --- |
+| An open side menu | Closes it. |
+| A search field with focus | Closes the search. |
+| A pushed screen | Pops it. |
+| The first screen of a modal | Closes the modal. |
+| The first screen of a tab | What `Tabs().backBehavior(…)` says: leave the app, go to the first tab, or to the tab before. See [Back on Android](../containers/tabs#back). |
+| The first screen of the app | Leaves the app, as every Android app does, with the system's own animation ([below](#system-animation)). `usePreventLeave` doesn't hold it; to ask first, see [Asking before the user leaves the app](/api/back-and-gestures/usePreventLeave#leaving-the-app). |
+
+### Back to the home screen
+
+(Android) On the first screen of the app, with nothing left to go back to, the navigation leaves the back to the system. The system then plays its predictive back animation: as the user swipes, the app shrinks and the home screen shows behind it, and the user can still change their mind halfway. The system decides this as the swipe starts, so the navigation takes the back only while it has something to do with it: a screen to pop, a modal, a menu or a search to close, a tab to go to (`backBehavior`), or a [`BackHandler` listener](#back-handler) of the app.
+
+An app that targets Android 16 (API 36) gets the animation without a change. An app that targets an older API turns it on in `AndroidManifest.xml`; `npx apex-navigation setup` adds it:
+
+```xml
+<application
+  android:enableOnBackInvokedCallback="true"
+  …>
+```
+
+Without it, back on the first screen still leaves the app, at once. See [What setup changes](../start/installation#android-files).
+
+With the animation on, the system leaves the app itself: an `invokeDefaultOnBackPressed` of the app's `MainActivity` (such as `moveTaskToBack(true)`) isn't called on the first screen. Without it, and before Android 13, the back goes through the activity as before.
+
+### Handling back yourself: BackHandler
+
+(Android) React Native's `BackHandler` works on every screen, as in any React Native app. A listener runs before the navigation's own back: returning `true` takes the press, `false` passes it on to the next listener, then to the navigation.
+
+- **While a listener is registered, the navigation keeps the back,** on the first screen too, so the listener is called there. The system's animation back to the home screen doesn't play meanwhile. Listen only while the screen needs it, in [`useFocusEffect`](/api/lifecycle-and-events/useFocusEffect), as in [Asking before the user leaves the app](/api/back-and-gestures/usePreventLeave#leaving-the-app).
+- **`BackHandler.exitApp()` is the default back,** not a way to close the app from anywhere: the navigation goes back where it can (pops a screen, closes a modal), and on the first screen the app leaves. React Native calls it itself when no listener takes the press.
+- **A listener added before `createNavigation` runs isn't counted.** The navigation counts the listeners from that call on, so one added by a module that loads ahead of your navigation file runs only while the navigation keeps the back for another reason. On the first screen, back leaves the app without calling it. Import such a module after the navigation file, or add the listener in a component.
+
+iOS has no system back: `BackHandler` does nothing there.
+
+## Keeping the user on a screen
+
+A screen with unsaved changes, such as a draft or a form, shouldn't lose them on a careless swipe. `usePreventLeave` holds **every way back from this screen to another screen of the app** while its condition is true, and calls its handler instead, so the screen can ask:
+
+```tsx
+import { useState } from 'react';
+import { Alert, TextInput } from 'react-native';
+import {
+  useNavigation,
+  usePreventLeave,
+} from '@apexnative/navigation';
+
+function Compose() {
+  const navigation = useNavigation();
+  const [text, setText] = useState('');
+
+  usePreventLeave(text.length > 0, () => {
+    Alert.alert('Discard the draft?', undefined, [
+      { text: 'Keep editing' },
+      { text: 'Discard', onPress: () => navigation.goBack() },
+    ]);
+  });
+
+  return <TextInput value={text} onChangeText={setText} multiline />;
+}
+```
+
+While the draft has text, back asks "Discard the draft?". Keep editing stays; Discard leaves. With an empty draft back leaves at once.
+
+| It holds | On |
+| --- | --- |
+| The back button, the swipe back, the history menu | (iOS) |
+| The back arrow, the system back | (Android) |
+| The swipe down of the modal the screen is in, and its close button | Both |
+
+The commands of the app aren't held: the app has decided. So `goBack()` in Discard leaves, and so does a `switchTo` after a sign-out. Leaving the app isn't held either, as in React Navigation: on the first screen of the app the system back of (Android) leaves it, and the home gesture of (iOS) leaves it from any screen. To ask before the system back leaves the app, see [Asking before the user leaves the app](/api/back-and-gestures/usePreventLeave#leaving-the-app). A form in a modal, with Cancel, Save and this question, is walked through in [Forms in a modal](../flows/forms-in-a-modal).
+
+## Knowing the user went back
+
+A screen that leaves its stack, by the back button, a swipe or `pop`, sends `screenPopped`. It is the place for what should happen once the user went back, such as keeping a draft for later instead of asking:
+
+```tsx
+useScreenEvent('screenPopped', () => {
+  saveDraft(text); // your own step
+});
+```
+
+More: [The way back](../containers/stack#back) of a stack, and [Every event](../fundamentals/lifecycle-and-events#events).
+
+## API

package/docs-md/screen-ui/bar-buttons.md

@@ -0,0 +1,312 @@
+# Bar buttons
+
+The buttons of the top bar: adding one, what a button can be, where the press is handled, menus and the overflow menu, which buttons stay when the bar is short of room, a component as a button, buttons that change with the state, and the vertical bar of iPhone Duo.
+
+The buttons of the top bar are the actions of a screen: edit, share, add, a menu. They are the platform's own buttons, with its look, its press feedback and its accessibility. A screen lists them in its options, each with what its press does:
+
+```tsx
+import { defineScreen } from '@apexnative/navigation';
+
+export const HomeScreen = defineScreen({
+  component: Home,
+  options: (s) =>
+    s.title('Home').rightButtons({
+      id: 'settings',
+      icon: { ios: 'gearshape', android: 'ic_settings' },
+      onPress: ({ navigation }) => navigation.push('Settings'),
+    }),
+});
+```
+
+A gear shows at the trailing edge of the bar; a tap on it opens Settings. This page answers:
+
+1. [Where buttons go](#where) in the bar.
+2. [What a button can be](#kinds).
+3. [Where the press is handled](#press).
+4. [Menus](#menus), [the overflow menu](#overflow), and [which buttons stay](#priority) when the bar is short of room.
+5. [A component as a button](#component).
+6. [Buttons that change](#change) with the state of the screen.
+7. [Buttons on iPhone Duo](#iphone-duo), in the vertical bar at the side.
+
+## Where buttons go
+
+| Option | Place |
+| --- | --- |
+| `rightButtons` | The trailing edge: the actions of the screen. |
+| `leftButtons` | The leading edge. On a pushed screen they take the place of the back button. |
+| `centerButtons` | (iPadOS) 16+ The middle of the bar. See [Center buttons](#center). |
+
+Several buttons go in one call, from the edge inward:
+
+```ts
+s.rightButtons(
+  { id: 'share', icon: { ios: 'square.and.arrow.up' } },
+  { id: 'done', text: 'Done', style: 'prominent' },
+);
+```
+
+Every button has an `id`, and its press is told by it. **A list of buttons is replaced whole**: a later layer of options with `rightButtons` replaces all the right buttons before it, so a screen never shows a mix of its own buttons and the app's.
+
+## What a button can be
+
+A button is a text, an icon or a system item, and the platform draws it:
+
+| Option | The button |
+| --- | --- |
+| `text` | A text button. On iOS an icon button shows only its icon; the text names it in the overflow menu and for VoiceOver. |
+| `icon` | An image (`require('./star.png')`), or an icon for each platform: an SF Symbol and a drawable of the app, `{ ios: 'square.and.arrow.up', android: 'ic_share' }`. A platform left out shows no icon. |
+| `systemItem` | (iOS) A button of the system: `'done'`, `'cancel'`, `'edit'`, `'close'`…, in the user's language. On Android only `'close'` applies: a close icon. |
+| `component` | A React component, for what the others can't draw: see [A component as a button](#component). |
+
+The look and the state of a button:
+
+| Option | What it does |
+| --- | --- |
+| `color` | The color of this button. |
+| `enabled: false` | Dimmed; a press does nothing. |
+| `style: 'prominent'` | (iOS) The main action, such as Done or Send. On iOS 26 a filled capsule in the button's `color`; before, a bold title. |
+| `group` | (iOS) 26: buttons with the same group share one glass capsule; each other button has a capsule of its own. |
+| `badge` | (iOS) 26: a number, a short text, or `true` for a dot. |
+| `toggle`, `selected` | (iOS) A button that switches on and off at each tap; the press carries the new state as `selected`. |
+
+`topBar.rightButtonColor` and `leftButtonColor` color all the buttons of a side, and `*DisabledColor` the disabled ones. A `color` of one button wins over them. Without any of them the buttons take the `primary` color of the [theme](../architecture/theme-and-context), then the platform's.
+
+## Where the press is handled
+
+A button gets its press **where it is defined**. A button that is always on the screen is defined with the screen, with `onPress`, as in the first example. It is in the bar from the first frame, and `onPress` gets the navigation of the screen, so the options need no import.
+
+When the press needs the state of the component, the component handles it with `useNavigationButton`, by the button's id. Here Share sends the text of the note, which only the component knows:
+
+```tsx
+import { useState } from 'react';
+import { Share, TextInput } from 'react-native';
+import {
+  defineScreen,
+  useNavigationButton,
+} from '@apexnative/navigation';
+
+export const NoteScreen = defineScreen({
+  component: Note,
+  options: (s) =>
+    s.rightButtons({
+      id: 'share',
+      icon: { ios: 'square.and.arrow.up', android: 'ic_share' },
+    }),
+});
+
+function Note() {
+  const [text, setText] = useState('');
+  useNavigationButton('share', () => Share.share({ message: text }));
+  return <TextInput value={text} onChangeText={setText} multiline />;
+}
+```
+
+| The press needs | Handle it with |
+| --- | --- |
+| Nothing of the component: open a screen, a menu | `onPress` in the options of `defineScreen`. |
+| The state of the component | `useNavigationButton(id, handler)` in the component. |
+| To be heard by the whole app, such as for analytics | The event `buttonPressed`, with the screen and the id: see [Where to listen](../fundamentals/lifecycle-and-events#where). |
+
+## Menus
+
+A button with a `menu` opens it on a tap. Each item has an `id`, and its own `onPress`:
+
+```ts
+s.rightButtons({
+  id: 'new',
+  icon: { ios: 'plus', android: 'ic_add' },
+  menu: {
+    items: [
+      {
+        id: 'new-note',
+        title: 'Note',
+        onPress: ({ navigation }) => navigation.showModal('NewNote'),
+      },
+      {
+        id: 'new-folder',
+        title: 'Folder',
+        onPress: ({ navigation }) => navigation.showModal('NewFolder'),
+      },
+    ],
+  },
+});
+```
+
+A tap on + opens a menu of Note and Folder; a pick opens its screen in a modal. A pick also sends the press with the id of the item, so a component handles it with `useNavigationButton` when it needs its state. Item ids and button ids share one space: keep them different.
+
+A menu that picks one of several, such as a sort order, has `singleSelection: true`: the check moves to the picked item, and the screen keeps it when it shows again.
+
+```tsx
+// in the options: a Sort button whose menu has singleSelection,
+// with the items 'sort-date' and 'sort-name'
+useNavigationButton('sort-date', () => setSort('date'));
+useNavigationButton('sort-name', () => setSort('name'));
+```
+
+`menuOnLongPress: true` opens the menu on a long press instead, so a tap stays the button's own press. An item can have an `icon`, `destructive: true` for red, `disabled: true`, and a submenu is an item with `items` of its own.
+
+| Platform | The menu |
+| --- | --- |
+| (iOS) | The system menu, with SF Symbols, submenus and a check on the picked item. |
+| (Android) | The Material popup menu under the button, with the same items, without the `title` of the menu. |
+
+## The overflow menu
+
+Actions that are used less go into the overflow menu at the end of the bar: "•••" on iOS 16+, "⋮" on Android. `overflowMenu` gives it its items. They are plain options, without `onPress`, so the component handles each pick by the item's id:
+
+```tsx
+export const NoteScreen = defineScreen({
+  component: Note,
+  options: {
+    topBar: {
+      overflowMenu: {
+        items: [
+          { id: 'export', title: 'Export' },
+          { id: 'delete', title: 'Delete', destructive: true },
+        ],
+      },
+    },
+  },
+});
+
+function Note() {
+  useNavigationButton('export', () => exportNote()); // your own
+  useNavigationButton('delete', () => deleteNote()); // your own
+  // …
+}
+```
+
+When the bar has no room, the platform moves right buttons into the menu too. `pinned: true` keeps a button out of it, at the trailing edge.
+
+### Which buttons stay
+
+A bar has room for few buttons: a phone in portrait, a long title, the vertical bar of [iPhone Duo](#iphone-duo). `priority` says which leave for the overflow menu last: `'high'` stays the longest, `'low'` goes first, `'standard'` by default.
+
+```ts
+s.rightButtons(
+  {
+    id: 'share',
+    icon: { ios: 'square.and.arrow.up', android: 'ic_share' },
+    priority: 'low',
+  },
+  { id: 'copy', icon: { ios: 'doc.on.doc', android: 'ic_copy' } },
+  {
+    id: 'bookmark',
+    icon: { ios: 'bookmark', android: 'ic_bookmark' },
+    priority: 'high',
+  },
+);
+```
+
+With room for two, Bookmark and Copy stay and Share goes into the menu.
+
+| Platform | `priority` |
+| --- | --- |
+| (iOS) 27+ | UIKit's `visibilityPriority`, in every bar. Before iOS 27 it has no effect, and UIKit decides by itself. |
+| (Android) | The right buttons that stay in the bar are taken by priority, then in their order; the bar keeps their order, and the others go into "⋮". |
+
+`pinned` is a promise and `priority` a preference: a pinned button never goes into the menu, a high one goes last.
+
+## A component as a button
+
+Some buttons are more than a text or an icon, such as the avatar of the user that opens the profile. A React component draws them, in the same three steps as [a component in place of the title](./top-bar#title-component).
+
+**1. The component.** It handles its own touches, so it is a `Pressable`:
+
+```tsx
+import { Image, Pressable } from 'react-native';
+import { navigation } from '@apexnative/navigation';
+
+export function AvatarButton(props: { avatar: string }) {
+  // push shows Profile in the stack the user sees: this bar's
+  return (
+    <Pressable onPress={() => navigation.push('Profile')}>
+      <Image
+        source={{ uri: props.avatar }}
+        style={{ width: 32, height: 32, borderRadius: 16 }}
+      />
+    </Pressable>
+  );
+}
+```
+
+**2. Its registration** in `screens`:
+
+```ts
+export const Navigation = createNavigation({
+  screens: { Home: HomeScreen, Profile: ProfileScreen, AvatarButton },
+  root: 'Home',
+});
+```
+
+**3. The button** names it in `component`:
+
+```ts
+s.rightButtons({
+  id: 'avatar',
+  component: { name: 'AvatarButton', passProps: { avatar } },
+});
+```
+
+The bar sends no press for it: the component's own `onPress` is the press. On (iOS) 26 it has no glass capsule; `hideSharedBackground: false` puts it on one. On (Android) `component.width` and `height` size it.
+
+## Buttons that change
+
+A button that depends on the state is built from the state with `useScreenOptions`. Here Save stays off while the note is empty, and turns on with the first letter:
+
+```tsx
+function NewNote() {
+  const [text, setText] = useState('');
+
+  useScreenOptions((s) =>
+    s.rightButtons({
+      id: 'save',
+      text: 'Save',
+      enabled: text.length > 0,
+      onPress: () => saveNote(text), // your own save
+    }),
+  );
+
+  return <TextInput value={text} onChangeText={setText} multiline />;
+}
+```
+
+The options are built on each render and applied before the screen paints when they changed, so the bar never lags behind the state. `onPress` sees the state of the same render. A full form in a modal, with Cancel and Save, is walked through in [Forms in a modal](../flows/forms-in-a-modal).
+
+On (iOS) `animateRightButtons` and `animateLeftButtons` fade the new buttons in. On iOS 26 buttons that share a capsule (several with one `group`) change at once: UIKit has no animation for groups of buttons.
+
+## Buttons on iPhone Duo
+
+(iOS) 27.1 iPhone Duo, folded and open, has a vertical bar at the trailing edge of the window: a strip that holds the status bar, the tab bar and the buttons of the bars. The title stays in the row at the top, and the screen goes under the strip ([The vertical bar of iPhone Duo](./system-ui#vertical-bar)). UIKit decides what goes where, and the app doesn't need to:
+
+- **The left and right buttons and the toolbar's items** go into the vertical bar. With few buttons UIKit may keep them in the row.
+- **`component` buttons and `pinned` buttons** stay in the row of the title.
+- **Center buttons** go into the overflow menu "•••".
+- **The large title** stays in the row.
+- **The vertical bar holds few buttons**: of ten right buttons about four stay, the rest go into "•••", the toolbar's items first. [`priority`](#priority) decides which stay.
+
+Three options change it:
+
+| Option | What it does |
+| --- | --- |
+| `vertical` of a button | `true`: the button may go into the vertical bar, a `component` button too, squeezed to the bar's width. `false`: only the row of the title. Unset: UIKit decides. |
+| `topBar.verticalBarKeeps` | When the tabs and the buttons share the vertical bar and it has no room for all: `'tabs'`, the default, keep their place and buttons go into "•••"; `'buttons'` keep theirs and the tabs shrink. |
+| `layout.verticalBars: false` | The screen's bars and the status bar stay horizontal, as on any iPhone. Set it once for a screen: Apple asks apps not to switch it with the state of the screen. |
+
+```ts
+s.rightButtons({
+  id: 'avatar',
+  component: { name: 'AvatarButton', passProps: { avatar } },
+  vertical: true, // into the vertical bar with the others
+}).options({ topBar: { verticalBarKeeps: 'buttons' } });
+```
+
+(Android) Android has no vertical bars: `vertical`, `verticalBarKeeps` and `verticalBars` do nothing there.
+
+## Center buttons
+
+(iPadOS) 16+ This section is rarely needed: it is for document apps on iPad. `centerButtons` sit in the middle of the bar with the `'browser'` or `'editor'` [layout](./top-bar#layout). On iPhone, and with the `'navigator'` layout, UIKit puts them in the overflow menu, so an icon button there needs a `text`.
+
+`topBar.customizationId` lets the user arrange them, from Customize Toolbar of the system menu. Each button's `customization` (`'fixed'`, `'movable'`, `'optional'`) says what the user can do with it, and UIKit keeps the arrangement under the id.
+
+## API

package/docs-md/screen-ui/search.md

@@ -0,0 +1,181 @@
+# Search
+
+The search field of the platform in the top bar: adding it and filtering with it, where it sits, what shows while searching, scopes, tokens, suggestions and a results screen.
+
+A list of mail, contacts or places needs a search field at the top. The search of a screen is the platform's own field in its top bar: `UISearchController` on (iOS), the Material 3 search on (Android). It looks, opens and closes as in system apps; **the screen only gets the text and shows what matches**. This page answers:
+
+1. [How to add search](#add) and filter with it.
+2. [Where the field sits](#placement) on each platform.
+3. [What shows while searching](#while).
+4. [Narrowing the search](#narrow): scopes, tokens, suggestions.
+5. [A results screen](#results) of its own.
+
+A whole search screen, with recent searches and a results screen, is walked through in [A search screen](../flows/a-search-screen).
+
+## Adding search
+
+A screen turns the field on in its options, and listens to the text with `useSearchBar`. Here an inbox filters its messages as the user types:
+
+```tsx
+import { useState } from 'react';
+import { FlatList, Text } from 'react-native';
+import { defineScreen, useSearchBar } from '@apexnative/navigation';
+
+export const InboxScreen = defineScreen({
+  component: Inbox,
+  options: (s) =>
+    s
+      .title('Inbox')
+      .searchBar({ visible: true, placeholder: 'Search mail' }),
+});
+
+function Inbox() {
+  const messages = useMessages(); // your own data
+  const [query, setQuery] = useState('');
+
+  useSearchBar({
+    onChange: ({ text }) => setQuery(text),
+    onCancel: () => setQuery(''),
+  });
+
+  const shown = messages.filter((message) =>
+    message.subject.toLowerCase().includes(query.toLowerCase()),
+  );
+
+  return (
+    <FlatList
+      data={shown}
+      contentInsetAdjustmentBehavior="automatic"
+      renderItem={({ item }) => <Text>{item.subject}</Text>}
+    />
+  );
+}
+```
+
+A field "Search mail" shows under the title. As the user types, the list keeps the messages that match; Cancel brings them all back.
+
+| Handler | Called |
+| --- | --- |
+| `onChange` | On every change of the text, and of the scope or the tokens. |
+| `onSubmit` | On the Search key of the keyboard; the keyboard hides. |
+| `onCancel` | When the search closes. |
+| `onSuggestion` | When the user picks a [suggestion](#suggestions). |
+
+## Where the field sits
+
+`placement` puts the field where the platform does in its own apps:
+
+| `placement` | (iOS) 16+ | (Android) |
+| --- | --- | --- |
+| `'stacked'` | Under the title. The default. | Under the title. |
+| `'automatic'` | As the system picks: on iPhone with iOS 26 at the bottom of the screen, on iPad in the bar. | Under the title. |
+| `'integrated'` | In the bar; on iPhone with iOS 26 at the bottom, or a magnifier in the bar when the bottom has no room, such as over a tab bar. | A magnifier among the buttons; the field opens in the bar. |
+| `'integratedButton'` | As `'integrated'`, but on iPad the closed search is always a magnifier. | As `'integrated'`. |
+| `'integratedCentered'` | As `'integrated'`, but centered in the bar on iPad. | As `'integrated'`. |
+
+Before iOS 26 every `integrated` value is the field in the bar.
+
+| Option | What it does |
+| --- | --- |
+| `hideOnScroll` | The field goes up with the content as it scrolls, and comes back at the top. On Android the bar hides with it. |
+| `focus: true` | The search opens with the keyboard, as on a screen made for searching. |
+| `placeholder` | The text of the empty field; the system "Search" without it. |
+| `backgroundColor`, `tintColor` | The color of the field, and of the cursor and the selected text. |
+
+## While searching
+
+| Option | While the search is open |
+| --- | --- |
+| `hideTopBarOnFocus` | (iOS) The bar hides, and the field moves to the top. On Android the open field always takes the bar. |
+| `obscuresBackgroundDuringPresentation` | The screen dims until the user types; a tap on it closes the search. |
+| `text` | Sets the text of the field from the app, such as a search the user ran before. No `onChange` follows: the app knows the text. |
+
+## Narrowing the search
+
+### Scopes
+
+Scopes narrow the search to a part: All, Unread, Flagged. They are segments under the field on (iOS), filter chips on (Android). The selected one comes in `onChange` as `scope`:
+
+```ts
+s.searchBar({
+  visible: true,
+  scopes: [
+    { id: 'all', title: 'All' },
+    { id: 'unread', title: 'Unread' },
+  ],
+  selectedScope: 'all',
+});
+```
+
+```tsx
+useSearchBar({
+  onChange: ({ text, scope }) => setFilter({ text, scope }), // your own
+});
+```
+
+`scopeBarActivation` says when they show: `'onSearchActivation'` as soon as the search opens, `'onTextEntry'` once the user types. A scope the user picks stays picked when the screen shows again.
+
+On (iOS) 26 the segments make the bar taller, and the system's edge effect, the blur that content scrolling under the bar fades into, goes down with them. UIKit draws it, as in any app; `scrollEdgeEffect` doesn't change it.
+
+### Tokens
+
+(iOS) Tokens are filters inside the field, before the text, such as a sender the user picked:
+
+```ts
+s.searchBar({
+  visible: true,
+  tokens: [{ id: 'from-anna', text: 'Anna' }],
+});
+```
+
+The user sees them and deletes them with the backspace. `onChange` carries the ids of the ones left as `tokens`. Closing the search clears the field with its tokens, as UIKit does. On Android there are no tokens: use [scopes](#scopes) for a filter there.
+
+### Suggestions
+
+(iOS) 16+ and (Android) A list of suggestions while the user types, such as recent searches or completions. The screen sets them from the text, with `useScreenOptions`:
+
+```tsx
+const [query, setQuery] = useState('');
+
+useScreenOptions((s) =>
+  s.searchBar({
+    // completions: your own list of words for the text
+    suggestions: completions(query).map((word) => ({
+      id: word,
+      title: word,
+    })),
+  }),
+);
+
+useSearchBar({
+  onChange: ({ text }) => setQuery(text),
+  onSuggestion: (id) => openSuggestion(id), // your own step
+});
+```
+
+A pick keeps the text, and comes to `onSuggestion` with the id of the suggestion. The list goes when the user picks one or types on, and the next render sets new ones. On iOS the list is UIKit's own, in the system's colors: the app gives it the items, not its look.
+
+## A results screen
+
+A search can show its results on a screen of its own, over the screen, from the moment it opens until it closes: recent places while the field is empty, then the places that match. `resultsComponent` names a component of `screens`:
+
+```ts
+s.searchBar({
+  visible: true,
+  resultsComponent: { name: 'PlaceResults' },
+  resultsActivation: 'onSearchActivation',
+});
+```
+
+The component gets the search events itself, with `useSearchBar`, as a screen of its own. `resultsActivation: 'onTextEntry'` shows it only once the field has text; until then the screen stays.
+
+| Platform | The results screen |
+| --- | --- |
+| (iOS) | Covers the whole screen, under the search field and to the bottom edge, so its background fills it. It keeps its content clear of the bar itself: a list with `contentInsetAdjustmentBehavior="automatic"`, other content with `useSafeAreaInsets`. |
+| (Android) | The search opens over the whole screen, the field at the top and the component under it. |
+
+## In the toolbar
+
+(iOS) 26 The field can sit in the toolbar, between its buttons, with `{ systemItem: 'searchField' }` among the buttons of the toolbar, whatever `placement` says. See [Toolbar and FAB](./toolbar-and-fab#toolbar).
+
+## API