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.
- ⭐️ 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
tabLongPressevents. - 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.
npm install react-native-jelly-tabsUsing Expo install
npx expo install @react-native-masked-view/masked-view react-native-gesture-handler react-native-reanimated react-native-svgWithout expo install
npm install @react-native-masked-view/masked-view react-native-gesture-handler react-native-reanimated react-native-svgJelly 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@latestThen 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.
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 |
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.
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.
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.
- 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
configto change them;layout.iconLabelGapandlayout.pillOverhangare new. expois a new peer dependency.- Icon components receive a
focusedprop (truefor the copy revealed through the selected pill). - On Android,
labelStyle/tabBarLabelStyleapplycolor,fontFamily,fontSize,fontStyle,fontWeight,letterSpacingandtextTransform; other text style keys are ignored there.
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/builddocs/build is a plain static bundle, ready to deploy to Cloudflare Workers
(see docs/wrangler.jsonc).
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:webOther useful commands:
bun run dev
bun run typecheck
bun run example:android
bun run example:iosDon't be afraid to open issues or Pull Requests, especially for documentation! :)