# React Native Header

> A React Native header (top app bar) for iOS, Android and the web: a back button, title, subtitle and actions, an iOS centered bar with a Back label, a Material 3 top app bar, and large titles.

# Header

A screen's top bar: a back button, the title and actions. On iOS the title is centred in a 44pt bar with a "Back" label beside the chevron; in Material it's a 64dp top app bar with the title at the start; on the web it's a bordered bar. `size="large"` adds a big title under the bar.

```tsx live

export default function Example() {
  return (
    <Header
      title="Settings"
      onBack={() => {}}
      actions={
        <Button variant="ghost" size="sm">
          Edit
        </Button>
      }
    />
  );
}
```

## Examples

Each example is live: edit the code and it runs.

### A photo album in select mode

A photo album's header has two states. Normally it shows the album and a Select button; in select mode the title counts the picks, Cancel takes the back button's place, and the actions act on the selection.

```tsx live
import { useState } from 'react';
import { Image, Pressable, View } from 'react-native';
import { Box, Button, HStack, Header } from 'patine-ui';
import { Icon } from '@patine-ui/icons';

const PHOTOS = [1015, 1016, 1018, 1019, 1020, 1021];

export default function Example() {
  const [photos, setPhotos] = useState(PHOTOS);
  const [selecting, setSelecting] = useState(false);
  const [picked, setPicked] = useState<number[]>([]);
  const done = () => {
    setSelecting(false);
    setPicked([]);
  };
  const toggle = (id: number) => setPicked((p) => (p.includes(id) ? p.filter((x) => x !== id) : [...p, id]));
  return (
    <Box border radius="lg" style={{ width: '100%', maxWidth: 400, overflow: 'hidden' }}>
      {selecting ? (
        <Header
          title={picked.length ? `${picked.length} selected` : 'Select photos'}
          leading={<Button variant="ghost" size="sm" onPress={done}>Cancel</Button>}
          actions={
            <HStack gap="xs">
              <Button size="icon" variant="ghost" accessibilityLabel="Share selected" disabled={!picked.length}>
                <Icon name="share" />
              </Button>
              <Button
                size="icon"
                variant="ghost"
                accessibilityLabel="Delete selected"
                disabled={!picked.length}
                onPress={() => {
                  setPhotos((all) => all.filter((id) => !picked.includes(id)));
                  done();
                }}
              >
                <Icon name="trash" color="danger" />
              </Button>
            </HStack>
          }
        />
      ) : (
        <Header title="Lisbon" subtitle={`${photos.length} photos`} onBack={() => {}} actions={<Button variant="ghost" size="sm" onPress={() => setSelecting(true)}>Select</Button>} />
      )}
      <View style={{ flexDirection: 'row', flexWrap: 'wrap', gap: 2 }}>
        {photos.map((id) => (
          <Pressable
            key={id}
            disabled={!selecting}
            onPress={() => toggle(id)}
            accessibilityRole={selecting ? 'checkbox' : 'image'}
            accessibilityState={{ checked: picked.includes(id) }}
            accessibilityLabel={`Photo ${id}`}
            style={{ width: '32.8%', aspectRatio: 1 }}
          >
            <Image source={{ uri: `https://picsum.photos/id/${id}/240/240` }} style={{ flex: 1, opacity: picked.includes(id) ? 0.6 : 1 }} />
            {picked.includes(id) ? (
              <View style={{ position: 'absolute', right: 6, bottom: 6, backgroundColor: '#fff', borderRadius: 12 }}>
                <Icon name="checkCircle" color="primary" />
              </View>
            ) : null}
          </Pressable>
        ))}
      </View>
    </Box>
  );
}
```

### An inbox with a large title

```tsx live
import { Header } from 'patine-ui';

export default function Example() {
  return <Header title="Inbox" subtitle="3 unread" size="large" />;
}
```

### A chat header with an avatar

`subtitle` adds a line under the title, and `leading` replaces the back button with anything, such as an avatar in a chat.

```tsx live
import { Avatar, Button, Header, HStack } from 'patine-ui';
import { Icon } from '@patine-ui/icons';

export default function Example() {
  return (
    <Header
      title="Leo Martin"
      subtitle="Online"
      leading={<Avatar size="sm" name="Leo Martin" src="https://picsum.photos/id/1005/160/160" />}
      actions={
        <HStack gap="xs">
          <Button size="icon" variant="ghost" accessibilityLabel="Call">
            <Icon name="phone" />
          </Button>
          <Button size="icon" variant="ghost" accessibilityLabel="Video call">
            <Icon name="video" />
          </Button>
        </HStack>
      }
    />
  );
}
```

### A new post, in a modal

In a sheet or a full-screen modal, put Cancel in `leading` and the confirming action at the end, as iOS does.

```tsx live
import { useState } from 'react';
import { Button, Header, TextArea, VStack } from 'patine-ui';

export default function Example() {
  const [text, setText] = useState('');
  return (
    <VStack gap="md" style={{ maxWidth: 420, width: '100%' }}>
      <Header
        title="New post"
        leading={<Button variant="ghost" size="sm">Cancel</Button>}
        actions={<Button size="sm" disabled={!text.trim()}>Post</Button>}
      />
      <TextArea label="What's on your mind?" value={text} onValueChange={setText} maxLength={280} showCount />
    </VStack>
  );
}
```

## In real apps

Patine Pro screens built with it. Each opens on that screen, live, in the screens gallery.

## Designs

iOS centers the title and writes the back label beside the chevron; Material puts the title at the start beside an arrow; Patine and the web are compact bars with a hairline under them.

<DesignsGrid
  example={
    <>

    </>
  }
/>

## Guidelines

<Do preview={<></>}>

**Keep one or two actions.** More go in a menu behind a ⋯ button.

<Dont preview={<></>}>

**Don't fill the bar with buttons.** The title gets squeezed and the targets shrink.

<Do preview={<></>}>

**Name the screen you go back to.** On iOS, the back label says where it leads.

<Dont preview={<></>}>

**Don't write long titles.** They truncate in a 44pt bar; use the large size for a long one.

### Safe area

Header doesn't add the status bar inset, so it works inside any navigator. Pad it yourself, e.g. `style={{ paddingTop: insets.top }}`, or render it inside your navigator's own header slot.

## Accessibility

| | Behaviour |
| --- | --- |
| Role | The title is a heading; the back button is a `button` named by `backLabel` ("Back" by default). |
| Announced | The actions you pass keep their own states. |
| Keyboard (web) | The back button and actions take Tab focus with a focus ring. |
| Touch target | The back button has a 44pt touch target. |
| Reduce motion | Nothing moves. |

## API

### Header

Header also takes `View` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | — | The screen's title. |
| `subtitle` | `string` | — | A line under the title. |
| `onBack` | `() => void` | — | Shows a back button that calls this. |
| `backLabel` | `string` | `'Back'` | The back button's text on iOS and its name for screen readers. |
| `leading` | `ReactNode` | — | Replaces the back button, e.g. a close button. |
| `actions` | `ReactNode` | — | Buttons at the end. |
| `size` | `'default' \| 'large'` | `'default'` | `'large'` puts a big title under the bar. |
| `styles` | `{ title?: StyleProp<TextStyle> }` | — | Style slots: `title` is the title's text. |
| `theme` | `DeepPartial<Theme>` | — | Theme override. |
| `design` | `'brand' \| 'ios' \| 'material' \| 'web' \| 'native'` | from `PatineProvider` | The look to follow: [brand, iOS, Material or web](../guides/designs), or `'native'` for the platform's own. |

Right to left and custom styles work the same on every component: see [Internationalization and right to left](../guides/i18n-rtl) and [Styling](../guides/styling).
