# React Native BottomTabBar and NavigationRail

> A React Native bottom tab bar and navigation rail for iOS, Android and the web: iOS's UITabBar, Material 3's navigation bar with its pill indicator, badges, safe-area inset, and a rail for tablets. Works with any navigator.

# BottomTabBar & NavigationRail

The bar of an app's main destinations: along the bottom on a phone (`BottomTabBar`), down the side on a tablet or desktop (`NavigationRail`). Icons over labels, with count or dot badges, drawn as iOS's tab bar or Material 3's navigation bar. It draws the bar; your navigator, or a `useState`, shows the screen.

```tsx
import { BottomTabBar, NavigationRail } from 'patine-ui';
```

```tsx live
import { BottomTabBar, Box, Center, Heading } from 'patine-ui';
import { Icon } from '@patine-ui/icons';

const TABS = [
  { value: 'home', label: 'Home', icon: ({ color }) => <Icon name="home" color={color} /> },
  { value: 'search', label: 'Search', icon: ({ color }) => <Icon name="search" color={color} /> },
  { value: 'inbox', label: 'Inbox', badge: 3, icon: ({ color }) => <Icon name="mail" color={color} /> },
  { value: 'profile', label: 'Profile', badge: true, icon: ({ color }) => <Icon name="user" color={color} /> },
];

export default function Example() {
  const [tab, setTab] = React.useState('home');
  const current = TABS.find((t) => t.value === tab);
  return (
    <Box border radius="lg" style={{ width: '100%', maxWidth: 360, height: 300, overflow: 'hidden' }}>
      <Center fill>
        <Heading level={3}>{current.label}</Heading>
      </Center>
      <BottomTabBar items={TABS} value={tab} onValueChange={setTab} />
    </Box>
  );
}
```

## Example: a shop app

A shop's tab bar: Add to cart on the Shop tab raises the Cart tab's badge, and each tab keeps its own screen.

```tsx live
import { useState } from 'react';
import { BottomTabBar, Box, Button, HStack, Text, VStack } from 'patine-ui';
import { Icon } from '@patine-ui/icons';

const PRODUCTS = [
  { name: 'Linen shirt', price: 59 },
  { name: 'Canvas tote', price: 24 },
  { name: 'Wool beanie', price: 19 },
];

export default function Example() {
  const [tab, setTab] = useState('shop');
  const [cart, setCart] = useState<string[]>([]);
  const tabs = [
    { value: 'shop', label: 'Shop', icon: ({ color }) => <Icon name="store" color={color} /> },
    { value: 'search', label: 'Search', icon: ({ color }) => <Icon name="search" color={color} /> },
    { value: 'cart', label: 'Cart', badge: cart.length || undefined, icon: ({ color }) => <Icon name="bag" color={color} /> },
    { value: 'account', label: 'Account', icon: ({ color }) => <Icon name="user" color={color} /> },
  ];
  return (
    <Box border radius="lg" style={{ width: '100%', maxWidth: 380, height: 340, overflow: 'hidden' }}>
      <VStack gap="sm" padding="md" style={{ flex: 1 }}>
        {tab === 'shop'
          ? PRODUCTS.map((p) => (
              <HStack key={p.name} justify="space-between" align="center">
                <VStack>
                  <Text weight="medium">{p.name}</Text>
                  <Text size="sm" color="textSecondary">${p.price}</Text>
                </VStack>
                <Button size="sm" variant="outline" onPress={() => setCart((c) => [...c, p.name])}>
                  Add to cart
                </Button>
              </HStack>
            ))
          : null}
        {tab === 'cart' ? (
          cart.length ? (
            <>
              {cart.map((item, i) => <Text key={i}>{item}</Text>)}
              <Button onPress={() => setCart([])}>Check out</Button>
            </>
          ) : (
            <Text color="textSecondary">Your cart is empty.</Text>
          )
        ) : null}
        {tab === 'search' ? <Text color="textSecondary">Search shirts, bags and hats.</Text> : null}
        {tab === 'account' ? <Text color="textSecondary">Signed in as maya@example.com</Text> : null}
      </VStack>
      <BottomTabBar items={tabs} value={tab} onValueChange={setTab} />
    </Box>
  );
}
```

## With React Navigation

Render it as the navigator's `tabBar`, and pass the safe area's bottom inset so it clears the home indicator:

```tsx
<Tab.Navigator
  tabBar={({ state, navigation }) => (
    <BottomTabBar
      items={state.routes.map((r) => ({ value: r.name, label: r.name, icon: ICONS[r.name] }))}
      value={state.routes[state.index].name}
      onValueChange={(name) => navigation.navigate(name)}
      bottomInset={insets.bottom}
    />
  )}
>
```

Pressing the selected tab calls `onValueChange` again, so you can scroll its screen to the top or pop it to its root, as iOS apps do.

## NavigationRail

The same items down the side, for a tablet or a desktop window: swap it in for `BottomTabBar` when the screen is wide. `header` goes above the items, such as a menu button or a FAB.

```tsx live
import { Box, Button, NavigationRail, Text } from 'patine-ui';
import { Icon } from '@patine-ui/icons';

const TABS = [
  { value: 'mail', label: 'Mail', badge: 12, icon: ({ color }) => <Icon name="mail" color={color} /> },
  { value: 'chat', label: 'Chat', icon: ({ color }) => <Icon name="messageSquare" color={color} /> },
  { value: 'meet', label: 'Meet', icon: ({ color }) => <Icon name="video" color={color} /> },
];

export default function Example() {
  return (
    <Box border radius="lg" row style={{ height: 320, overflow: 'hidden' }}>
      <NavigationRail items={TABS} defaultValue="mail" header={<Button size="icon" variant="secondary" accessibilityLabel="Compose"><Icon name="edit" /></Button>} />
      <Box flex={1} padding="lg">
        <Text color="textSecondary">Content</Text>
      </Box>
    </Box>
  );
}
```

## Designs

| Design | Look |
| --- | --- |
| brand | 64pt, a hairline on top, the selected icon and label in the primary color |
| iOS | UITabBar: 49pt, a hairline on top, small labels, the selected item tinted |
| Material 3 | Navigation bar: 80dp on a tonal surface, a 64×32 pill behind the selected icon, bold label |
| web | 56pt with a top border |

## Accessibility

- A `tablist` of `tab`s, the current one selected. Badges are read with the label: "Inbox, 3 new".
- Each tab fills its share of the bar, well over 44pt. On the web, Tab reaches the bar and arrow keys move along it.

## Props

Both take `View` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` | `{ value, label, icon?, badge?, disabled? }[]` | — | The destinations. `icon` is a node or `({ selected, color }) => node`; `badge` a count or `true` for a dot. |
| `value` | `string` | — | The selected item, controlled. |
| `defaultValue` | `string` | the first item | The selected item when uncontrolled. |
| `onValueChange` | `(value: string) => void` | — | Called when the user picks an item, also the selected one. |
| `bottomInset` | `number` | `0` | BottomTabBar: space under the bar for the home indicator. |
| `header` | `ReactNode` | — | NavigationRail: above the items. |
| `topInset` | `number` | `0` | NavigationRail: space above, for the status bar. |
| `accessibilityLabel` | `string` | `'Tabs'` | Names the bar. |
| `theme`, `design` | | | As every component. |
