# Liquid tab bar

> A tab bar whose indicator is a liquid blob: on a tab change the leading lobe shoots to the target, the surface behind it sinks into a neck and the rest snaps in with one overshoot, and a finger dragged along the bar scrubs the blob 1:1.

- Type: Component (navigation)
- Access: Pro
- Page: https://goodui.dev/native/components/liquid-tab-bar
- Markdown: https://goodui.dev/native/components/liquid-tab-bar.md
- Registry item: https://goodui.dev/native/r/liquid-tab-bar.json
- Dependencies: react-native-gesture-handler, react-native-reanimated, react-native-svg
- Keywords: react native liquid tab bar, gooey tab bar, animated bottom tabs expo, blob tab indicator, metaball navigation bar, fluid tab bar reanimated svg

## When to use

- The main navigation of a consumer app where the bar is part of the brand: travel, music, social, fitness.
- Two to five top-level destinations that people switch between many times a session.
- A floating bar over full-bleed content (maps, feeds, photos), where the solid blob stays readable.

## When not to use

- Dense, utilitarian apps where navigation should recede: use tab-bar.
- Switching views inside one screen: use segmented-control or top-tabs.
- More than five destinations: move the rest into a drawer or a More tab.

## Installation

With the shadcn CLI (needs a components.json in the Expo app), then `npx expo install --fix` so native dependencies match your Expo SDK. The foundation comes along the first time.

```bash
npx shadcn@latest add @goodui-native-pro/liquid-tab-bar
npx expo install --fix
```

Pro: add `"@goodui-native-pro": { "url": "https://goodui.dev/native/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${GOODUI_LICENSE_KEY}" } }` to the `registries` of components.json and put your license key in .env.local.

The component lands in `components/goodui-native/liquid-tab-bar/` and imports the foundation from `components/goodui-native/foundation/` with relative paths; it also installs locale.

Built-in strings follow `<GooduiLocaleProvider>` (one [language pack](https://goodui.dev/native/r/locale-tr.json) translates the whole kit); the `labels` prop overrides them for one instance.

## Usage

```tsx
import { useState } from "react";
import { LiquidTabBar } from "@/components/goodui-native/liquid-tab-bar/liquid-tab-bar";
import { HomeIcon, SearchIcon, HeartIcon, UserIcon } from "@/components/icons";

type Tab = "home" | "search" | "saved" | "profile";

export function AppTabs() {
  const [tab, setTab] = useState<Tab>("home");
  return (
    <LiquidTabBar
      accessibilityLabel="Main"
      value={tab}
      onChange={setTab}
      items={[
        { value: "home", label: "Home", icon: (p) => <HomeIcon {...p} /> },
        { value: "search", label: "Search", icon: (p) => <SearchIcon {...p} /> },
        { value: "saved", label: "Saved", icon: (p) => <HeartIcon {...p} />, badge: 3 },
        { value: "profile", label: "Profile", icon: (p) => <UserIcon {...p} /> },
      ]}
    />
  );
}
```

## Examples

### Docked, with labels and badges

```tsx
<LiquidTabBar variant="docked" showLabels value={tab} onChange={setTab} onReselect={scrollToTop} items={items} />
```

### Soft tone: a tinted blob with accent icons

```tsx
<LiquidTabBar tone="soft" value={tab} onChange={setTab} items={items} />
```

### Uncontrolled, no scrubbing

```tsx
<LiquidTabBar defaultValue="home" draggable={false} onChange={(tab) => router.navigate(tab)} items={items} />
```

## API reference

### LiquidTabBar

`import { LiquidTabBar } from "@/components/goodui-native/liquid-tab-bar/liquid-tab-bar";`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` (required) | `LiquidTabBarItem<T>[]` | – | Two to five tabs. |
| `value` | `T` | – | The selected tab (controlled). |
| `defaultValue` | `T` | – | The tab selected first when uncontrolled. Defaults to the first item. |
| `onChange` | `(value: T) => void` | – | Called with the new tab on tap, or on release after scrubbing the blob. |
| `onReselect` | `(value: T) => void` | – | Called when the selected tab is tapped again, for example to scroll to the top. |
| `variant` | `"floating" \| "docked"` | `"floating"` | `floating` is an inset capsule above the home indicator; `docked` spans the bottom edge with a hairline. |
| `tone` | `"accent" \| "soft"` | `"accent"` | `accent` is a solid blob with inverted icons; `soft` is a tinted blob with accent icons. |
| `showLabels` | `boolean` | `false` | Show labels under the icons. Without them the bar is icon only and the blob is larger. |
| `draggable` | `boolean` | `true` | Allow dragging a finger along the bar to scrub the blob between tabs. Default `true`. |
| `haptic` | `HapticName \| false` | `"select"` | Haptic when the tab changes and at every tab crossed while scrubbing. `false` turns it off. |
| `accessibilityLabel` | `string` | – | Name of the tab list for screen readers, for example "Main". |
| `style` | `StyleProp<ViewStyle>` | – | Style for the outer container. |
| `testID` | `string` | – | Identifier for end-to-end tests. |

## Accessibility

- The bar is a tablist and every tab is a tab with its selected state. The name is the label, followed by the badge text when there is one; `accessibilityLabel` on an item replaces it.
- Labels are always read, also when `showLabels` is off and only icons are drawn.
- Scrubbing is an extra: every tab is reachable with a tap or a screen reader double tap.
- On the web the selected tab is in the tab order, Left and Right arrows move the selection and the focus, Enter and Space select.
- Icons use the theme's secondary text color on the bar and onAccent on the blob.

## Motion

- Tab change: the leading lobe travels on the morph spring; the trailing lobe is released 90 ms later on the bouncy spring, so the blob stretches, the surface between the lobes sinks into a neck that thins with distance, and the tail lands with one overshoot.
- The trailing lobe gives up volume as it stretches (smaller radius, shorter flat) and the leading lobe swells slightly.
- Touch down: the icon under the finger dips to 0.82 on the snappy spring. On selection the icon dips and comes back on the bouncy spring.
- Scrub: the blob is grabbed where it is, slides under the finger within a few frames and then follows 1:1; its tail chases on the smooth spring, so the neck grows with the finger's speed. Past the ends it resists.
- Release: the lead springs to the nearest tab (projected with the finger's velocity) carrying that velocity; the tail follows with one overshoot.
- Icons and labels cross-fade in proportion to how much of the blob's lead sits over each tab. A badge pops when its count goes up.
- Reduced motion: the blob jumps to the new tab without stretching, icons do not dip or bounce, badges do not pop. Scrubbing still follows the finger.

## Haptics

- select on a tab change by tap
- select at every tab the blob crosses while scrubbing; the release itself is silent
- Pass haptic={false} to turn them off, or another pattern name.

## Performance

- The blob is one SVG path whose outline is rebuilt in a worklet from two shared values, on the UI thread. React renders only when the selected tab changes.
- Each icon is rendered twice (on and off the blob) and cross-faded, so keep icon components cheap.

## Notes for AI

- Controlled: pass value and onChange. Uncontrolled: defaultValue. The callback is onChange, not onValueChange.
- icon is a render prop: ({ color, size, focused }) => node. Use the color and size it gives you, do not hardcode them.
- Two to five items. Every item needs a label even when showLabels is false: screen readers read it.
- variant='floating' adds its own side and bottom margins (bottom safe area included); place it at the bottom of the screen without extra padding. variant='docked' pads itself by the bottom inset.
- For expo-router pass it to <Tabs tabBar={...}> and map state.routes to items yourself; there is no navigation adapter in this file.
- Requires GestureHandlerRootView at the app root (see the foundation setup).

## Related

- [Tab bar](https://goodui.dev/native/components/tab-bar.md): A bottom tab bar whose pill stretches toward the next tab and can be dragged to scrub between tabs; the selected icon bounces, badges pop, and it can hide while scrolling.
- [Segmented control](https://goodui.dev/native/components/segmented-control.md): Two to five views of the same thing with an elastic highlight that stretches toward the new segment, can be dragged, and ticks at every boundary. Includes a billing toggle.
- [Top tabs](https://goodui.dev/native/components/top-tabs.md): A swipeable pager under a tab strip whose indicator tracks the swipe continuously: the leading edge runs ahead and the trailing edge follows, so it stretches between tabs and gathers as the page lands. Labels recolor with the swipe and a scrolling strip keeps the indicator centred.
- [Floating action button](https://goodui.dev/native/components/fab.md): A floating main action that opens a speed dial (the plus turns into a close mark, a scrim dims the screen, mini actions rise one by one with labels) and, extended, folds its label away while you scroll.

## Guidance for AI tools

Liquid tab bar: A tab bar whose indicator is a liquid blob: on a tab change the leading lobe shoots to the target, the surface behind it sinks into a neck and the rest snaps in with one overshoot, and a finger dragged along the bar scrubs the blob 1:1. Use only the documented props. Keep accessibility, reduced motion and both color schemes intact when adapting it.

Full library index: https://goodui.dev/native/llms.txt
