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

package/docs-md/containers/side-menu.md

@@ -0,0 +1,138 @@
+# Side menu
+
+What a side menu is, how to build one, how it opens and closes, how a pick in the menu changes the content, and how it looks on each platform.
+
+A side menu is a drawer beside the content of the app: the sections, the account, the settings, out of the way until the user pulls it in. `SideMenu` builds one from the content, its center, and a menu on a side:
+
+```ts
+import { createNavigation, SideMenu } from '@apexnative/navigation';
+import { MenuScreen } from './screens/Menu';
+import { HomeScreen } from './screens/Home';
+import { SettingsScreen } from './screens/Settings';
+
+export const Navigation = createNavigation({
+  screens: {
+    Menu: MenuScreen,
+    Home: HomeScreen,
+    Settings: SettingsScreen,
+  },
+  root: SideMenu({
+    left: 'Menu', // the menu
+    center: 'Home', // the content
+  }),
+});
+```
+
+Home shows. A swipe from the left edge brings Menu in over it.
+
+This page answers:
+
+1. [What a side menu is](#what), and its parts.
+2. [How to build one](#build).
+3. [How it opens and closes](#open).
+4. [How a pick in the menu changes the content](#pick).
+5. [How it looks](#look) on each platform, and [where the swipe is off](#swipe).
+
+## What a side menu is
+
+A side menu has **a center and a menu on one side or both**. The center is the app the user works in; the menu slides in over it, or moves it aside, and goes away again.
+
+- **The center is a [stack](./stack),** so it pushes as the root does: a screen named alone gets a stack.
+- **A menu is a screen on its own,** without a stack: a list of what the center can show.
+
+## Building a side menu
+
+`SideMenu` takes its parts, each a screen of `screens` by its name or a layout. The side methods take each menu's settings, such as its width:
+
+```ts
+SideMenu({ left: 'Menu', center: 'Home' }).left({ width: 300 });
+```
+
+A right menu is the same: `right: 'Filters'`, with `.right({ … })`. A side menu is a root most of the time, `root: main` or one of `roots`. It can also be a tab or the content of a modal.
+
+## Opening and closing
+
+The user opens a menu with a swipe from its edge. A swipe back, a tap on the content or the system back on (Android) closes it. The app does it with `openMenu` and `closeMenu`, such as from a button of the top bar:
+
+```ts
+import { defineScreen } from '@apexnative/navigation';
+
+export const HomeScreen = defineScreen({
+  component: Home,
+  options: (s) =>
+    s.leftButtons({
+      id: 'menu',
+      icon: require('../icons/menu.png'),
+      onPress: ({ navigation }) => navigation.openMenu('left'),
+    }),
+});
+```
+
+A tap on the button opens the menu. A button of the options gets the navigation of its screen in `onPress`, so the options need no import of `navigation`.
+
+`closeMenu()` closes whichever menu is open. Both resolve once the menu has moved.
+
+## A pick in the menu
+
+A menu is a screen without a stack, so **its commands act on the center**, and the menu closes once the center has changed. A pick usually switches the section, so the center starts over with it:
+
+```tsx
+import { Button, View } from 'react-native';
+import { useNavigation } from '@apexnative/navigation';
+
+function Menu() {
+  const navigation = useNavigation();
+  const open = (section: 'Home' | 'Settings') =>
+    navigation.replace(section);
+
+  return (
+    <View>
+      <Button title="Home" onPress={() => open('Home')} />
+      <Button title="Settings" onPress={() => open('Settings')} />
+    </View>
+  );
+}
+```
+
+A tap on Settings shows Settings in the center, and the menu closes. Which command to use depends on the way back:
+
+| From the menu | The center |
+| --- | --- |
+| `replace('Settings')` | Shows Settings alone: a new section, with no back to the one before. |
+| `push('Profile')` | Pushes Profile over its top screen, with back to it. |
+
+## How it looks
+
+| Platform | The menu |
+| --- | --- |
+| (iOS) | Over the content, which dims: `openMode: 'aboveContent'` of the side, the default. Or under it, with the content moved aside: `'pushContent'`. Then `animation(…)` says how the menu appears: `'parallax'`, `'slide'`, `'slide-and-scale'` or `'door'`. |
+| (Android) | The drawer of the platform: over the content, which dims. |
+
+`.ios()` keeps the settings that only iOS has apart from the others:
+
+```ts
+const main = SideMenu({ left: 'Menu', center: 'Home' })
+  .left({ width: 300 })
+  .ios((menu) =>
+    menu.left({ openMode: 'pushContent' }).animation('parallax'),
+  );
+```
+
+On iOS the content moves aside, and the menu comes in under it with a parallax; on Android the drawer slides over the content.
+
+(iOS) 26: `left({ glass: true })` puts the menu on Liquid Glass. The glass shows where the menu's screen has no background of its own.
+
+## Where the swipe is off
+
+A swipe from the edge can clash with the content, such as a map or a carousel. A screen turns it off **while it is on top of the center**, in its options:
+
+```ts
+export const MapScreen = defineScreen({
+  component: Map,
+  options: (s) => s.sideMenu({ left: { enabled: false } }),
+});
+```
+
+On the map the swipe pans the map, and the menu still opens with `openMenu`. On (iOS), `gesture('entireScreen')` lets the swipe start anywhere on the content, `'bezel'` only at the edge (the default).
+
+## API

package/docs-md/containers/split-view.md

@@ -0,0 +1,155 @@
+# Split view
+
+Columns side by side on iPad, how to build them, how a pick shows beside the list, how the sidebar shows and hides, and what iPhone and Android show.
+
+On a big screen a list and its item fit side by side: the mail and the message, the settings and the section, the folders and the files. A split view puts them in columns, and `SplitView` builds one:
+
+```ts
+import { createNavigation, SplitView } from '@apexnative/navigation';
+import { FoldersScreen } from './screens/Folders';
+import { PickAFolderScreen } from './screens/PickAFolder';
+import { FolderScreen } from './screens/Folder';
+
+export const Navigation = createNavigation({
+  screens: {
+    Folders: FoldersScreen, // the list of folders
+    PickAFolder: PickAFolderScreen, // until the user picks one
+    Folder: FolderScreen, // a picked folder
+  },
+  root: SplitView({
+    primary: 'Folders', // the sidebar
+    secondary: 'PickAFolder', // beside it, before the first pick
+  }),
+});
+```
+
+On iPad, Folders shows in a sidebar and PickAFolder beside it. On iPhone the same app shows one column at a time.
+
+This page answers:
+
+1. [What a split view is](#what), and its columns.
+2. [How to build one](#build).
+3. [How a pick shows beside the list](#show).
+4. [How the sidebar shows and hides](#sidebar).
+5. [What a phone and a narrow window show](#compact), and [Android](#android).
+
+## What a split view is
+
+A split view is columns side by side, each **with a stack of its own**. A pick in one column shows its item in the next. On (iPadOS) it is the system's `UISplitViewController`; (Android) has two panes of its own, see [Android](#android). Two screens that come together as one screen of a stack, such as a profile and its details, are a pair instead: see [A pair or a split view](./arrangement#split-view).
+
+## Building a split view
+
+`SplitView` takes its columns, and each column names a screen of `screens`, as in the example above. The column beside the list needs something to show **before the first pick**. There it is a screen with one line:
+
+```tsx
+import { Text } from 'react-native';
+
+function PickAFolder() {
+  return <Text>Pick a folder on the left</Text>;
+}
+```
+
+Once the user picks a folder, the folder takes its place: see [Showing beside the list](#show). The columns:
+
+- **`primary`** and **`secondary`** are needed; the others are not.
+- **`supplementary`** (iPadOS) adds the middle column: `primary: 'Folders', supplementary: 'Files', secondary: 'File'`.
+- **`inspector`** (iPadOS) 26 adds a column at the trailing edge, for facts about the item.
+- **`compact`** is what an iPhone and a narrow window show: see [A phone and a narrow window](#compact).
+
+A screen alone, by its name or with `Screen(…)`, gets a [stack](./stack) in each column, as in the root; the inspector is a screen on its own. Android has no middle column or inspector, and leaves them out.
+
+## Showing beside the list
+
+A pick in a column shows its item with `showInColumn`, from the screen where the user picked it. The item goes into the column beside, `secondary` by default, in place of what the column showed:
+
+```tsx
+import { Button, FlatList } from 'react-native';
+import { useNavigation } from '@apexnative/navigation';
+
+function Folders() {
+  const navigation = useNavigation();
+  const folders = useFolders(); // your own data
+
+  const open = (folderId: string) =>
+    navigation.showInColumn('Folder', { props: { folderId } });
+
+  return (
+    <FlatList
+      data={folders}
+      renderItem={({ item }) => (
+        <Button title={item.name} onPress={() => open(item.id)} />
+      )}
+    />
+  );
+}
+```
+
+A tap on a folder shows it beside the list, in place of PickAFolder. The column comes into view: a sidebar over it goes away. The folder is the first screen of its column's stack: a `push` from it opens the next screen inside that column, with the list still beside it.
+
+With three columns, a pick in the sidebar goes to the middle, `column: 'supplementary'`, and a pick there to `secondary`:
+
+```ts
+navigation.showInColumn('Files', {
+  props: { folderId },
+  column: 'supplementary',
+});
+```
+
+**Where there is one column**, on iPhone, in a narrow window and on a narrow Android screen, the same call pushes the screen over the list, and back returns to it: the back button, and `pop()` from the screen (`canPop()` is true there). That pop animates as the system back does, whatever `animations.pop`. One call works everywhere.
+
+A whole list-and-details app, step by step: [List and details](../flows/list-and-details).
+
+## How the sidebar shows
+
+(iPadOS) The split view's methods set how the sidebar shows:
+
+| Method | What it sets |
+| --- | --- |
+| `displayMode(…)` | How it starts: `'oneBesideSecondary'` side by side, `'oneOverSecondary'` the sidebar over the item, `'secondaryOnly'` the item alone. With three columns, `'twoBesideSecondary'` and the others. |
+| `splitBehavior(…)` | How a shown sidebar shares the space: `'tile'` beside, `'overlay'` over, `'displace'` pushing the item aside. |
+| `primaryColumn({ width, edge })` | The width of the sidebar, and `edge: 'trailing'` to put it on the right. |
+| `displayModeButton(…)`, `presentsWithGesture(…)` | The button of the bar that shows and hides the sidebar, and the swipe that brings it. |
+
+```ts
+const main = SplitView({ primary: 'Folders', secondary: 'PickAFolder' })
+  .displayMode('oneBesideSecondary')
+  .primaryColumn({ width: 320 });
+```
+
+The sidebar stays beside the item, 320 points wide.
+
+The app shows and hides a column itself with `showColumn` and `hideColumn`, such as an inspector behind a button:
+
+```ts
+await navigation.showColumn('inspector');
+await navigation.hideColumn('primary'); // the item alone
+```
+
+Each change, by the user or by the app, sends `splitViewDisplayModeChanged` (iOS only).
+
+## A phone and a narrow window
+
+On iPhone, and on iPad when the app shares the screen in a narrow window, there is room for one column. The columns collapse into one stack, in one of two ways:
+
+| The split view has | One column shows |
+| --- | --- |
+| `compact: 'Folders'` | That layout: Folders, and `showInColumn` pushes over it. |
+| No `compact` | The columns as one stack, with `compactTopColumn` on top: a pick in Folders pushes the folder, and back returns to Folders. |
+
+`compact` is the simpler one: the phone gets a layout of its own, as an app designed for the phone.
+
+```ts
+SplitView({
+  primary: 'Folders',
+  secondary: 'PickAFolder',
+  compact: 'Folders', // iPhone and a narrow window
+});
+```
+
+## Android
+
+(Android) The split view shows the primary and the secondary pane side by side when the width takes both: a tablet, a phone in landscape. On a narrower screen it shows the `compact` layout, or without it the secondary pane over the primary one. `showInColumn` works the same way on both platforms.
+
+Android reads three settings: the width of the primary pane (`primaryColumn({ width })`, 360 by default), `presentsWithGesture` and `compactTopColumn`. The others are iOS only.
+
+## API

package/docs-md/containers/stack.md

@@ -0,0 +1,156 @@
+# Stack
+
+What a stack is and where stacks live, how to build one, every command of a stack, the way back, and a whole stack at once for a deep link.
+
+The stack is the main container of an app: a list opens an item, the item opens its comments, and back goes the same way down. `Stack` builds one, and `push` and `pop` move in it:
+
+```ts
+import { createNavigation, Stack } from '@apexnative/navigation';
+import { HomeScreen } from './screens/Home';
+import { DetailsScreen } from './screens/Details';
+
+export const Navigation = createNavigation({
+  screens: { Home: HomeScreen, Details: DetailsScreen },
+  root: Stack('Home'),
+});
+```
+
+Home shows first, with a top bar. `navigation.push('Details')` from Home shows Details over it, and back returns to Home.
+
+This page answers:
+
+1. [What a stack is](#what), and where stacks live in an app.
+2. [How to build one](#build), starting with one screen or several.
+3. [The commands of a stack](#commands): push, back, replace.
+4. [The way back](#back): what the user does, and how the app knows.
+5. [A whole stack at once](#deep-link), for a deep link.
+
+## What a stack is
+
+A stack is **screens one over another**: the top one shows, and back goes to the one under it. The screens under the top one stay mounted, with their state and scroll, so back returns to them as they were.
+
+The stack is the platform's: a `UINavigationController` on (iOS), the library's own stack of views on (Android). It owns **one top bar** for all its screens. Each screen gives the bar its title and buttons through its options, so the bar changes with the screen as it comes in. See [Top bar](../screen-ui/top-bar).
+
+### Where stacks live
+
+Wherever the user moves on from a screen, there is a stack. A screen named alone in these places gets a stack around it, so it can push:
+
+| Place | The stack |
+| --- | --- |
+| The root | `root: 'Home'` is the same as `root: Stack('Home')`. |
+| Each tab | Each tab has its own stack, and keeps it while the user looks at other tabs. See [Tabs](./tabs). |
+| A modal | A modal has its own stack, unless `stack: false`. See [Modals](./modals). |
+| The center of a side menu, a column of a split view | The same as the root. See [Side menu](./side-menu), [Split view](./split-view). |
+
+Where nothing moves on, a screen stays on its own, without a stack and its top bar: the menus of a side menu, the inspector of a split view, an overlay.
+
+## Building a stack
+
+`Stack` takes its screens from the bottom one to the top one, each a screen of `screens` by its name. Most stacks start with one, as above.
+
+A stack can also start deeper, with the screens under the top one already in place. A screen with props goes as `Screen(name, props)`:
+
+```ts
+import { Screen, Stack } from '@apexnative/navigation';
+
+Stack('Inbox', Screen('Chat', { userId: '7' }));
+```
+
+Chat shows, and back goes to Inbox. A stack can start as deep as it needs, each screen with props of its own:
+
+```ts
+Stack(
+  Screen('Inbox', { folder: 'work' }),
+  Screen('Chat', { userId: '7' }),
+  Screen('Profile', { userId: '7' }),
+  Screen('Photo', { photoId: '42' }),
+);
+```
+
+Photo shows; back goes to Profile, Chat, then Inbox. Each screen gets only its own props, and TypeScript checks each against its screen.
+
+`Screen(…).options()` gives a screen options for this show only, over those of its definition:
+
+```ts
+Stack(
+  'Inbox',
+  Screen('Chat', { userId }).options((s) => s.hideBottomTabs()),
+);
+```
+
+The stack itself takes no options: they go on its screens, so a screen looks the same in every stack it is pushed into. A screen's own options go in `defineScreen`, those of many screens in a group or in `presentation.push`. See [Where a screen gets them](../fundamentals/screen-options#layers).
+
+## The commands of a stack
+
+A screen's commands act on the stack the screen is in. Each one changes the screens of the stack, and **the top one is what the user sees**:
+
+In a screen, `useNavigation` gives the commands:
+
+```tsx
+import { Button, View } from 'react-native';
+import { useNavigation } from '@apexnative/navigation';
+
+function Chat({ userId }: { userId: string }) {
+  const navigation = useNavigation();
+
+  const openProfile = () =>
+    navigation.push('Profile', { props: { userId } });
+
+  return (
+    <View>
+      <Button title="Profile" onPress={openProfile} />
+      <Button title="Back" onPress={() => navigation.pop()} />
+    </View>
+  );
+}
+```
+
+Profile comes in over Chat; Back on either screen goes one screen down.
+
+- **`push`** resolves with the id of the new screen. `popTo` takes such an id: keep it to come back to that screen later.
+- **`popToRoot`** goes back to the first screen of the stack, past all the others at once.
+- **`replace`** leaves the new screen **alone in the stack**, so there is no back. It comes in as a push does. After a payment, `replace('OrderPlaced')`, so back can't lead to a second payment.
+- **`setStack`** gives the stack several new screens at once: the last one shows, and back goes down the others. The screens that were there unmount, even one with the same name.
+
+Code outside a screen, such as a store or a timer, uses the `navigation` object of the package: its commands act on the stack the user is looking at. See [Where the commands come from](../fundamentals/moving-between-screens#where).
+
+`goBack()` and the checks `canPop()` and `canGoBack()` work on stacks too: see [Going back](../fundamentals/moving-between-screens#back). The way a screen comes in, such as `push('Details', { transition: 'fade' })`: see [Transitions](../architecture/transitions).
+
+## The way back
+
+The user goes back with the platform's controls, and they work without code:
+
+| Platform | Back |
+| --- | --- |
+| (iOS) | The back button of the top bar, and the swipe from the leading edge. |
+| (Android) | The back arrow of the top bar, the back gesture and the system back. |
+
+When a screen leaves its stack by any of them, or by `pop`, it gets the event `screenPopped` before it unmounts. It is the place for what should happen when the user goes back, such as keeping a draft:
+
+```tsx
+import { useScreenEvent } from '@apexnative/navigation';
+
+useScreenEvent('screenPopped', () => {
+  saveDraft(text); // your own step
+});
+```
+
+A custom back button, a swipe turned off, a screen that asks before the user leaves: see [Back and gestures](../screen-ui/back-and-gestures).
+
+## A whole stack at once
+
+A deep link opens a screen deep in the app. The screens the user would have passed on the way go under it, so back works as if they came by hand. `setStack` builds that stack in one command:
+
+```ts
+await navigation.setStack(
+  'Inbox',
+  Screen('Chat', { userId }),
+  Screen('Profile', { userId }),
+);
+```
+
+Profile shows; back goes to Chat, then to Inbox. Every screen of the new stack is new, so a link carries what each screen needs in its props. A link that lands in another tab or in another root builds the whole root: see [A root made on the go](../fundamentals/switching-roots#on-the-go) and [Deep links](../guides/deep-links).
+
+A full app with a list and its details, step by step: [List and details](../flows/list-and-details).
+
+## API

package/docs-md/containers/tabs.md

@@ -0,0 +1,187 @@
+# Tabs
+
+Tabs with a stack each, how to build them, how the app selects a tab, presses and badges, lazy tabs, and the tab bars of iOS 26, iPad and Android.
+
+Tabs are the sections of an app side by side: Home, Inbox, Profile. The user moves between them with one tap, and each section stays where the user left it. `Tabs` builds them, a `Tab` for each section:
+
+```ts
+import { createNavigation, Tab, Tabs } from '@apexnative/navigation';
+import { HomeScreen } from './screens/Home';
+import { InboxScreen } from './screens/Inbox';
+import { ProfileScreen } from './screens/Profile';
+
+export const Navigation = createNavigation({
+  screens: {
+    Home: HomeScreen,
+    Inbox: InboxScreen,
+    Profile: ProfileScreen,
+  },
+  root: Tabs(
+    Tab('Home').label('Home').icon(require('./icons/home.png')),
+    Tab('Inbox').label('Inbox').icon(require('./icons/inbox.png')),
+    Tab('Profile').label('Profile').icon(require('./icons/user.png')),
+  ),
+});
+```
+
+The app opens on Home, with the tab bar of the platform at the bottom. A tap on Inbox shows Inbox.
+
+This page answers:
+
+1. [What tabs are](#what): sections with a stack each.
+2. [How to build them](#build): labels, icons, the first tab.
+3. [How the app selects a tab](#select), and what a press can do.
+4. [Badges and dots](#badges).
+5. [When tabs are created](#lazy).
+6. [The tab bar on each platform](#platforms): iOS 26, iPad, Android.
+
+## What tabs are
+
+Each tab holds **a stack of its own**. A push goes into the stack of the tab the screen is in, so the user can go deep in Inbox, look at Home, and come back to Inbox where they were:
+
+The tab bar is the platform's: the system tab bar on (iOS), which becomes a bar at the top or a sidebar on (iPadOS) and a vertical bar at the side on iPhone Duo, and the Material bottom navigation on (Android).
+
+## Building tabs
+
+`Tabs` takes its tabs in order. Each `Tab` takes what it shows: a screen of `screens` by its name, which gets a [stack](./stack) around it. A tab's methods set what the tab bar shows for it:
+
+- **`label` and `icon`.** An icon is an image, `require('./home.png')`, or a symbol of each platform: `{ ios: 'house.fill', android: 'ic_home' }`, an SF Symbol on iOS and a drawable of the app on Android.
+- **`id`** names the tab, so commands can select it or give it a badge without knowing its place.
+
+`Tabs().selected()` is the tab the app opens on: its index, or its id. Without it, the first tab:
+
+```ts
+// icons: your own images, such as require('./icons/home.png')
+Tabs(
+  Tab('Home').label('Home').icon(icons.home),
+  Tab('Inbox').label('Inbox').icon(icons.inbox).id('inbox'),
+).selected('inbox');
+```
+
+The app opens on Inbox; Home is one tap away.
+
+A tab can hold any layout, not only a screen. `Tab(Stack('Inbox', Screen('Chat', { userId })))` opens with a chat already pushed over Inbox.
+
+The look of the tab items goes on all tabs at once with `Tabs().itemStyle({ … })`, and a tab's own `itemStyle` goes over it. The tab bar itself takes `Tabs().options({ … })`: see [the options](#options) below.
+
+### Screens without the tab bar
+
+A screen deep in a tab, such as a chat or a photo, often needs the whole height. `hideBottomTabs()` in its options hides the tab bar **while this screen is on top**. The bar comes back when the user goes back, because the screen under it doesn't hide it.
+
+```ts
+export const ChatScreen = defineScreen({
+  component: Chat,
+  options: (s) => s.hideBottomTabs(),
+});
+```
+
+## Selecting a tab
+
+The user selects a tab with a tap. The app selects one with `selectTab`, by its index or its id. It resolves once the tab shows, so the next command acts in that tab:
+
+```ts
+import { navigation } from '@apexnative/navigation';
+
+await navigation.selectTab('inbox');
+await navigation.push('Chat', { props: { userId } });
+```
+
+This is the app's `navigation`: its `push` goes to the stack the user sees, now the Inbox tab. A screen's own `useNavigation()` would push into that screen's stack instead.
+
+Inbox shows, and Chat comes in over it, in the stack of the Inbox tab.
+
+### A press on a tab
+
+A second tap on the selected tab is a convention of both platforms: **back to the start of the tab**. The navigation does it without code:
+
+| The user is | A second tap |
+| --- | --- |
+| Deep in the tab: Inbox → Chat → Profile | Goes back to Inbox, the first screen of the tab. |
+| On the first screen, scrolled down | Scrolls it back to the top. |
+
+`Tab().popToRootOnPress(false)` turns it off. A screen that wants to do something of its own on the tap, such as reload, listens with `useTabPress`:
+
+```tsx
+useTabPress(({ wasSelected }) => {
+  if (wasSelected) refetch(); // your own request
+});
+```
+
+A tab can also be a button, such as a New tab that opens a modal to write. A `Tab()` without content **never becomes current**, and `onPress` decides what it does:
+
+```ts
+import { navigation, Tab } from '@apexnative/navigation';
+
+Tab()
+  .label('New')
+  .icon(icons.plus)
+  .onPress(() => navigation.showModal('Compose'));
+```
+
+A tab with content can do the same now and then: with `selectOnPress(false)` a press keeps the current tab, and `onPress` decides.
+
+`popToRootOnBlur()` sends a tab back to its first screen when the user leaves it, so it always opens at its start.
+
+### Back on Android
+
+(Android) On the first screen of a tab, the system back does what `Tabs().backBehavior(…)` says: `'exit'` leaves the app, `'first'` goes to the first tab, `'previous'` to the tab the user came from. iOS has no system back, so the method does nothing there.
+
+## Badges and dots
+
+A badge is a number or a short text on the tab's icon; a dot is a badge without text.
+
+```ts
+Tab('Inbox').label('Inbox').id('inbox').badge(3);
+```
+
+The app changes it from anywhere, by the tab's id. A count goes as it is: `0` takes the badge away, and so does `null`. The text `'0'` shows "0".
+
+```ts
+navigation.setTabBadge(unread, 'inbox');
+```
+
+From a screen of the tab, `setTabBadge(count)` needs no id: it sets the badge of the screen's own tab. `Tab().dot()` shows a dot.
+
+## When tabs are created
+
+By default every tab is created with the tabs, so a switch shows it at once. `Tabs().lazy()` creates each tab the first time it shows. The app starts faster when its tabs are heavy, and a tab the user never opens costs nothing.
+
+```ts
+const main = Tabs(/* … */).lazy();
+```
+
+## The tab bar on each platform
+
+The tab bar follows the platform, and each platform has its own way:
+
+| Platform | The tab bar |
+| --- | --- |
+| (iOS) 26 | Liquid Glass. `Tabs().minimize('onScrollDown')` shrinks it to the selected tab as the content scrolls. `Tabs().accessory('Player')` puts a screen of `screens` above the tabs, as the mini player of a music app. |
+| (iPadOS) 18+ | A bar at the top that turns into a sidebar: `Tabs().sidebar('sidebar')`. With the sidebar, `Tabs().customizable(id)` lets the user arrange the tabs, and keeps the arrangement under the id. iPhone shows the tab bar. |
+| (iOS) 27 iPhone Duo | The tab bar is in the vertical bar at the trailing edge, folded and open, with the buttons of the top bar (`topBar.verticalBarKeeps` decides who keeps the room, see [Buttons on iPhone Duo](../screen-ui/bar-buttons#iphone-duo)). Open, `Tabs().sidebar('sidebar')` shows the sidebar too, as on iPad. |
+| (Android) | Material 3 bottom navigation. `layoutStyle: 'compact'` makes it a bar that floats over the content, `hideOnScroll` hides it as the content scrolls, when the scroll view is the root of the screen, with `nestedScrollEnabled`. |
+
+The colors go with the [theme](../architecture/theme-and-context): the selected tab takes the primary color, the bar the bar color. On iOS 26 the system draws the bar and the tabs not selected in its own colors.
+
+## Events
+
+| Event | When |
+| --- | --- |
+| `tabSelected` | A tab became current. |
+| `tabPressed` | A tap on a tab, the selected one too. |
+| `tabLongPressed` | A long press on a tab. |
+| `accessoryPlacementChanged` | (iOS) 26+: the accessory moved next to the shrunk tab bar (`'inline'`), or back above it (`'regular'`). |
+
+In a screen, `useTabPress` covers the presses of its own tab. See [Every event](../fundamentals/lifecycle-and-events#events).
+
+## Options
+
+The tab bar takes the options `bottomTabs`, each tab item `bottomTab`. The methods above cover the usual ones. `Tabs().options({ … })` and `Tab().options({ … })` take the rest, all listed in the API below:
+
+```ts
+Tabs(/* … */).options({ titleDisplayMode: 'alwaysShow' });
+```
+
+A whole app with tabs, step by step: [An app with tabs](../flows/an-app-with-tabs).
+
+## API