Skip to content

About

A jelly-like animated tab bar for React Native, built with Reanimated, Gesture Handler and Masked View

Topics

Resources

Stars

93 stars

Watchers

1 watching

Forks

Repository files navigation

react-native-jelly-tabs

npm version license React Native >=0.76 Reanimated 3–4 Gesture Handler 2–3 Runs with Expo Expo Router
Platforms: Android, iOS and Web

A jelly-like animated tab bar for React Native. On Android it renders natively (Kotlin, through an Expo module); on iOS and the web it is built with Reanimated, Gesture Handler and Masked View.

tabdemofinal.mp4

Demo at: https://jelly.felipe.software/

Docs at: https://jelly-docs.felipe.software

Still under development. Supports Android, iOS and React Native Web.

Features

  • ⭐️ Runs on Android, iOS and React Native Web.
  • ⭐️ Drop-in integration with Expo Router and React Navigation bottom tabs.
  • ⭐️ Compatible with Expo and bare React Native projects (bare projects need Expo Modules).
  • ⭐️ Native Android renderer: the jelly springs, touch handling and drawing run in Kotlin, off the JavaScript and Reanimated pipelines.
  • Smooth jelly snapping, dragging and press interactions powered by Reanimated and Gesture Handler.
  • Navigation-aware selection that follows deep links, hardware back and programmatic navigation.
  • Expo Router hidden tabs through href: null, including hidden focused routes with no false selection.
  • Per-tab accessibility semantics for VoiceOver and TalkBack, including selected state and activation actions.
  • Navigation badges, test IDs, accessibility labels, label styles and tabLongPress events.
  • Badges that can restyle themselves as the pill wipes over them (activeBadgeStyle).
  • Headless component for custom routers and fully controlled tab state.
  • Icons as React components, SVG paths (pathIcon) or icon-font glyphs (glyphIcon); paths and glyphs are drawn natively on Android.
  • Custom colors, opacity, sizing, springs, distortion, backdrops and touch feedback.
  • Compatible with Reanimated 3–4 and Gesture Handler 2–3 within the supported React Native ranges below.
  • Written in TypeScript with bundled type declarations.

Installation

npm install react-native-jelly-tabs
Dependencies

Using Expo install

npx expo install @react-native-masked-view/masked-view react-native-gesture-handler react-native-reanimated react-native-svg

Without expo install

npm install @react-native-masked-view/masked-view react-native-gesture-handler react-native-reanimated react-native-svg

Jelly Tabs ships native Android code as an Expo module, so the app needs the expo package. Expo apps already have it. Bare React Native apps add it once:

npx install-expo-modules@latest

Then rebuild the native app — npx expo prebuild on Expo, or pod install + a fresh build on bare React Native. Aside from that command, Expo and bare React Native are identical here.

Reanimated & Gesture Handler setup

React Native Gesture Handler v2 needs extra steps to finalize its installation instructions. Please make sure to wrap your App with GestureHandlerRootView when you've upgraded to React Native Gesture Handler ^2.

React Native Reanimated v3 needs extra steps to finalize its installation: installation instructions.

Compatible versions

Jelly Tabs works across a couple of major versions of each native dependency, so you can match whatever your app already uses:

Package Supported range
React Native >=0.76
Expo >=52 (tested with SDK 57)
Gesture Handler >=2.25 <4 (Gesture Handler 3 needs React Native >=0.82)
Reanimated >=3.16 <5

Usage with Expo Router or React Navigation

import { MaterialIcons } from "@react-native-vector-icons/material-icons";
import { Tabs } from "expo-router";
import { JellyTabBar } from "react-native-jelly-tabs";

export default function TabLayout() {
    return (
        <Tabs tabBar={(props) => <JellyTabBar {...props} floating />}>
            <Tabs.Screen
                name="index"
                options={{
                    title: "Home",
                    tabBarIcon: ({ color, size }) => (
                        <MaterialIcons color={color} name="home" size={size} />
                    ),
                }}
            />
            <Tabs.Screen
                name="settings"
                options={{
                    title: "Settings",
                    tabBarIcon: ({ color, size }) => (
                        <MaterialIcons color={color} name="settings" size={size} />
                    ),
                }}
            />
        </Tabs>
    );
}

JellyTabBar is compatible with the tabBar prop from Expo Router's JavaScript tabs and React Navigation's bottom tabs.

Pass floating to position the bar over the screen instead of reserving layout space. The screen will then fill behind the bar. Scrollable screens should add enough bottom content padding for their last item to remain reachable above the floating bar.

Router-independent component

Use JellyTabBarHeadless when you want the animated component without any navigation integration:

<JellyTabBarHeadless
    items={items}
    selectedIndex={selectedIndex}
    onTabPress={({ index }) => setSelectedIndex(index)}
/>

Each item takes an activeIcon and an inactiveIcon (see Icons).

JellyTabBarHeadless adds no safe-area inset of its own. Give it a wrapper whose height matches config.layout.trackHeight (default 64) times displayScale.

Colors, opacity, layout, jelly springs, distortion, backdrops, badges and the touch-feedback gradient are all configurable.

Icons

An icon can be any React component that receives { color, size, focused }, so tabBarIcon render functions and icon-library components keep working. On Android they are hosted inside the native bar as React views.

For the lightest Android rendering, build icons with the two helpers. They return regular icon components (so they also work on iOS, on the web, and as tabBarIcon), and on Android they are drawn natively:

import { glyphIcon, pathIcon } from "react-native-jelly-tabs";
import { mdiHome, mdiHomeOutline } from "@mdi/js";
import glyphMap from "@react-native-vector-icons/material-icons/glyphmaps/MaterialIcons.json";

// SVG path data, 24×24 viewBox by default
const HomeIcon = pathIcon(mdiHome, { inactivePath: mdiHomeOutline });

// A glyph from an icon font that is already loaded in the app
const SettingsIcon = glyphIcon("MaterialIcons", glyphMap.settings);

<Tabs.Screen name="index" options={{ title: "Home", tabBarIcon: HomeIcon }} />;

glyphIcon takes the font family name the font is registered under on Android (the file name for fonts bundled in assets/fonts, or the name given to expo-font) and a glyph string or code point.

Upgrading from 0.x

  • Android now renders natively. Rebuild the app after upgrading, and add Expo Modules to bare React Native apps (see Installation).
  • Labels are now 11 pt (weights 600/500) on Android and the web; iOS keeps 13 pt (700/400). Override with labelStyle.
  • Android has its own layout defaults: a pill 8 pt wider than its tab so tabs sit closer, a 1 pt icon-label gap, and stronger presses (pill 1.2×, track 1.1×). Pass config to change them; layout.iconLabelGap and layout.pillOverhang are new.
  • expo is a new peer dependency.
  • Icon components receive a focused prop (true for the copy revealed through the selected pill).
  • On Android, labelStyle / tabBarLabelStyle apply color, fontFamily, fontSize, fontStyle, fontWeight, letterSpacing and textTransform; other text style keys are ignored there.

Documentation

https://jelly-docs.felipe.software — guides and live, interactive previews. Every example is a real Storybook story rendered through React Native Web, so what you read is what runs, and each preview has a Copy props button that hands you the current setup as JSX or as a plain config object.

PROPS.md is the flat reference: every prop, type and default in one file.

The site lives in docs/ (Docusaurus) and the stories in storybook/.

bun run docs:previews   # build Storybook into docs/static/storybook
bun run docs            # start the docs site (previews must be built first)
bun run storybook       # open Storybook on its own (port 7007)
bun run docs:build      # full static build (previews + docs) → docs/build

docs/build is a plain static bundle, ready to deploy to Cloudflare Workers (see docs/wrangler.jsonc).

Development

The reusable package lives in src/, and the native Android renderer in android/. The Expo playground, generated background, and color laboratory live in example/. bench/ holds the Android benchmark (see bench/README.md).

bun install
bun run build
bun run example:web

Other useful commands:

bun run dev
bun run typecheck
bun run example:android
bun run example:ios

Don't be afraid to open issues or Pull Requests, especially for documentation! :)

About

A jelly-like animated tab bar for React Native, built with Reanimated, Gesture Handler and Masked View

Topics

Resources

Stars

93 stars

Watchers

1 watching

Forks

Releases

Contributors

Languages