Every prop and config value of react-native-jelly-tabs, taken from the exported
TypeScript types. This file is the flat reference; the guides, defaults in context
and live interactive examples live at https://jelly.felipe.software/docs —
every preview there has a Copy props button that emits this same shape as JSX
or JSON.
All props are optional except items. JellyTabBar accepts the same visual props
while sourcing its items and selection from the navigator.
| Prop | Type | Default | Description |
|---|---|---|---|
items |
TabsItem[] |
— | The tabs to render (required). |
maxWidth |
DimensionValue |
400 |
Maximum track width; stays centered in wider parents. |
selectedIndex |
number | null |
uncontrolled | Controlled index. null/negative renders no pill. |
onTabPress |
(e: TabsChangeEvent) => boolean | void |
— | After every completed tap or drag, including the already selected tab. Return false to reject. |
onTabLongPress |
(e: TabsChangeEvent) => void |
— | When a tab is held, including the longpress accessibility action. |
onTabChange |
(e: TabsChangeEvent) => void |
— | After an accepted change only. |
colors |
Partial<TabBarColors> |
see below | Solid color per layer. |
opacity |
Partial<TabBarOpacity> |
all 1 |
Per-layer opacity, clamped 0–1. |
config |
DeepPartial<TabBarConfig> |
see below | Layout, jelly and distortion overrides. |
backdrop |
ReactNode |
— | Node below the track color layer. |
selectedBackdrop |
ReactNode |
— | Node below the selected-pill color layer. |
displayScale |
number |
1 |
Scales every layout dimension. |
touchFeedbackEnabled |
boolean |
true |
Toggles the radial touch feedback. |
touchFeedbackColor |
string |
colors.selectedSurface |
Feedback gradient color. |
touchFeedbackOpacity |
number |
0.15 |
Opacity of the gradient's center stop. |
touchFeedbackScale |
number |
2 |
Multiplier applied to the radius. |
recording |
boolean |
false |
Deterministic mode for clean captures. |
JellyTabs remains available as a deprecated alias for JellyTabBarHeadless.
Pass it to the navigator's tabBar callback; the navigator supplies state,
descriptors, navigation and insets.
| Prop | Type | Description |
|---|---|---|
floating |
boolean |
Absolutely position the bar over the screen. |
containerStyle |
StyleProp<ViewStyle> |
Wrapper overrides. |
Recognised screen options: title, string tabBarLabel, tabBarLabelStyle,
tabBarIcon, tabBarShowLabel, tabBarBadge, tabBarBadgeStyle,
tabBarActiveBadgeStyle, tabBarAccessibilityLabel, tabBarButtonTestID,
tabBarActiveTintColor, tabBarInactiveTintColor,
tabBarActiveBackgroundColor, tabBarInactiveBackgroundColor,
tabBarBackground, tabBarStyle, and Expo Router's href: null. It emits
tabPress and tabLongPress. Function-valued tabBarLabel and custom tab
buttons are not rendered by the Jelly layout.
interface TabsItem {
key: string;
label: string;
activeIcon: TabsIcon; // revealed through the pill mask; see pathIcon / glyphIcon
inactiveIcon: TabsIcon; // drawn in the track
accessibilityLabel?: string;
labelStyle?: StyleProp<TextStyle>;
badge?: number | string;
badgeStyle?: StyleProp<TextStyle>; // both copies of the tab
activeBadgeStyle?: StyleProp<TextStyle>; // layered over it inside the mask
testID?: string;
}The tab row is rendered twice — in the track, and inside the pill mask.
activeBadgeStyle applies only to the masked copy, so a badge can carry one color
outside the pill and another inside it. Labels are limited to one line and
truncate with a trailing ellipsis.
interface TabsChangeEvent {
index: number;
item: TabsItem;
}
interface TabsIconProps {
color: string; // resolved active/inactive content color
colors: Readonly<TabBarColors>; // full palette
focused: boolean; // true for the copy revealed through the pill
size: number; // resolved icon size
opacity: number; // resolved layer opacity
}pathIcon(path: string, options?: { inactivePath?: string; viewBox?: number }): JellyIcon
glyphIcon(fontFamily: string, glyph: string | number, options?: { inactiveGlyph?: string | number }): JellyIconBoth return an icon component usable as activeIcon, inactiveIcon or a navigator's
tabBarIcon. viewBox is the side of the square path viewBox (default 24). The
inactive variant is used for the copy outside the pill, or when React Navigation
passes focused: false. On Android these icons are drawn natively; on iOS and the
web they render with react-native-svg and Text.
Android uses a native renderer with the same props and its own defaults: the icon sits
1 above its label, the pill overhangs its tab by 8, and presses scale the pill 1.2×
and the track 1.1×. resolveTabBarConfig() returns these values on Android. Labels
are 11 with weights 600 (selected copy) and 500 on Android and the web; iOS keeps
13 with 700 and 400. Notes:
- React icons, badges,
backdropandselectedBackdropare React views hosted inside the native layers;pathIconandglyphIconicons and the labels are drawn natively. labelStyleappliescolor,fontFamily,fontSize,fontStyle,fontWeight,letterSpacingandtextTransform; other text style keys are ignored.layout.maskOverscanX/maskOverscanYsize theselectedBackdropoverscan; there is no mask view.
interface TabBarColors {
surface: string;
selectedSurface: string;
activeContent: string;
inactiveContent: string;
}| Key | Color default | Opacity default | Role |
|---|---|---|---|
surface |
#22211f |
1 |
Track background |
selectedSurface |
#f2eee7 |
1 |
Selected pill |
activeContent |
#11100f |
1 |
Selected icon / label |
inactiveContent |
#b8b4ad |
1 |
Unselected icon / label |
Opacity applies to the rendered content rather than the mask, so the animated pill keeps a fully opaque clipping shape.
config is a deep-partial of TabBarConfig — pass only the nested keys you want.
resolveTabBarConfig(partial?) returns a complete, mutable object.
| Key | Default | Android default | Description |
|---|---|---|---|
iconSize |
28 |
28 |
Base icon size passed to each icon. |
itemHeight |
56 |
56 |
Height of a single tab / the selected pill. |
trackHeight |
64 |
64 |
Height of the track. |
trackInset |
4 |
4 |
Padding between the track edge and items. |
maskOverscanX |
48 |
48 |
Horizontal overscan for the pill mask. |
maskOverscanY |
16 |
16 |
Vertical overscan for the pill mask. |
iconLabelGap |
0 |
1 |
Space between icon and label. Android only. |
pillOverhang |
0 |
8 |
How much wider the pill (and each tab's content box) is than the tab pitch, so tabs sit closer. Android only. |
| Key | Default | Description |
|---|---|---|
pressedScale |
1.3 (Android 1.2) |
How much the pill inflates while pressed. |
snapOnPointerDown |
true |
Snap the indicator toward the touch on press. |
frameConfig.releaseDistanceFraction |
0.025 |
Keeps the indicator inflated until it is within this fraction of its snap point. |
Springs are { stiffness, dampingRatio } per channel:
| Spring | stiffness |
dampingRatio |
Drives |
|---|---|---|---|
value |
1000 |
1 |
Pill position along the track. |
velocity |
300 |
0.5 |
Velocity tracking that feeds the stretch. |
scaleX |
250 |
0.6 |
Horizontal stretch. |
scaleY |
250 |
0.7 |
Vertical squash. |
press |
1000 |
1 |
Press inflation. |
panel |
300 |
1 |
Whole-panel follow. |
| Key | Default | Description |
|---|---|---|
pressedScale |
1.025 (Android 1.1) |
Whole-track scale while pressed. |
touchFeedback.opacity |
0.15 |
Base opacity of the radial gradient. |
touchFeedback.middleOpacityRatio |
0.43 |
Opacity of the gradient's 45% stop, relative to the base. |
touchFeedback.radius |
150 |
Base gradient radius (px). |
touchFeedback.scale |
2 |
Multiplier applied to the radius. |
spring.damping |
18 |
Distortion spring damping. |
spring.mass |
0.9 |
Distortion spring mass. |
spring.stiffness |
240 |
Distortion spring stiffness. |
verticalDrag.distortion |
0.08 |
How much vertical drag squishes the track width. |
verticalDrag.distanceForMaxDistortion |
700 |
Drag distance (px) that reaches max distortion. |
verticalDrag.follow |
0.25 |
How much the track follows the finger vertically. |
verticalDrag.rubberBand |
0.14 |
Rubber-band resistance on the vertical follow. |
The touch-feedback gradient is drawn twice — once under the whole track and once inside the pill mask — so it stays visible as it crosses the selected tab.