# AppBar (React Native)

> The bar at the top of a screen: title, back or menu button, and actions. Small, centred, medium and large-title variants.

GramproKit for React Native · Mobile · Beta · Source: https://kit.gramproindia.com/native/docs/app-bar

> **Beta:** React Native support is in beta. APIs may change or break between prereleases (npm tag `native`).

_Interactive demo:_ [open the live example](https://kit.gramproindia.com/native/docs/app-bar). The example's source:

```tsx
import { useState } from "react";
import { ScrollView, View } from "react-native";
import { AppBar, AppBarAction } from "@/component-lib/app-bar";
import { useKitTheme } from "@/component-lib/shared/native";
import { Section } from "./layout"; // Section and Row: page layout for the demo
import { FakeRows, MiniScreen, TextIcon } from "./mobileFrame";

export function AppBarDemo() {
  const { tokens } = useKitTheme();
  const [scrolled, setScrolled] = useState(false);
  const actions = [
    <AppBarAction key="search" aria-label="Search">
      <TextIcon glyph="⌕" color={tokens.fg} size={22} />
    </AppBarAction>,
    <AppBarAction key="more" aria-label="More options">
      <TextIcon glyph="⋮" color={tokens.fg} size={22} />
    </AppBarAction>,
  ];
  return (
    <>
      <Section title="AppBar · small, center, back">
        <View style={{ gap: 10 }}>
          <MiniScreen height={56}>
            <AppBar safeArea={false} title="Invoices" subtitle="12 unpaid" actions={actions} />
          </MiniScreen>
          <MiniScreen height={56}>
            <AppBar safeArea={false} variant="center" title="Settings" onBack={() => {}} actions={actions[1]} />
          </MiniScreen>
          <MiniScreen height={56}>
            <AppBar safeArea={false} title="Invoice #1042" onBack={() => {}} elevated />
          </MiniScreen>
        </View>
      </Section>

      <Section title="AppBar · large title, elevation on scroll">
        <MiniScreen>
          <AppBar
            safeArea={false}
            variant={scrolled ? "small" : "large"}
            title="Payments"
            scrolled={scrolled}
            actions={actions}
          />
          <ScrollView
            nestedScrollEnabled
            scrollEventThrottle={16}
            onScroll={(e) => setScrolled(e.nativeEvent.contentOffset.y > 8)}
          >
            <FakeRows count={10} prefix="Payment" />
          </ScrollView>
        </MiniScreen>
      </Section>

      <Section title="AppBar · medium">
        <MiniScreen height={112}>
          <AppBar safeArea={false} variant="medium" title="Customers" subtitle="Kerala region" onBack={() => {}} />
        </MiniScreen>
      </Section>
    </>
  );
}
```

## Install

```bash
npx @grampro/kit@native add AppBar
```

## Usage

```tsx
import { AppBar, AppBarAction } from "@/component-lib/app-bar";

<AppBar
  variant="large"
  title="Payments"
  onBack={() => router.back()}
  scrolled={scrolled}
  actions={
    <AppBarAction aria-label="Search" onPress={openSearch}>
      <SearchIcon />
    </AppBarAction>
  }
/>
```

## Props

### AppBarProps

| Prop | Type | Description |
|---|---|---|
| `variant` | `AppBarVariant` | Default `small`. `medium` and `large` put the title on its own row under the toolbar. |
| `title` | `ReactNode` |   |
| `subtitle` | `ReactNode` |   |
| `leading` | `ReactNode` | Before the title: a back or menu button. Overrides `onBack`. |
| `onBack` | `(event: GestureResponderEvent) => void` | Shows a back button that calls this. |
| `actions` | `ReactNode` | Buttons at the end, usually `AppBarAction`s. `children` are appended. |
| `children` | `ReactNode` |   |
| `elevated` | `boolean` | Always draw the raised surface and shadow. |
| `scrolled` | `boolean` | The content under the bar has scrolled: draw a divider and the raised surface. |
| `safeArea` | `boolean` | Pad the top by the safe-area inset (status bar, notch). Default true. |
| `style` | `StyleProp<ViewStyle>` |   |
| `styles` | `Partial<{ root: StyleProp<ViewStyle>; bar: StyleProp<ViewStyle>; title: StyleProp<TextS…` |   |
| `localeText` | `Partial<AppBarLocaleText>` |   |

### AppBarActionProps

| Prop | Type | Description |
|---|---|---|
| `onPress` | `(event: GestureResponderEvent) => void` |   |
| `disabled` | `boolean` |   |
| `children` (required) | `ReactNode` | The icon. |
| `style` | `StyleProp<ViewStyle>` |   |

## Notes

- Pads its top by `KitProvider`'s `insets.top`; pass `insets={useSafeAreaInsets()}` to the provider, or `safeArea={false}`.
- `scrolled` raises the bar with a divider while the content beneath it is scrolled.
- `AppBarAction` is a 44dp round icon button and needs an `aria-label`.
- Mobile only: there is no web version of this component.