Documentation Index
Fetch the complete documentation index at: https://mintlify.com/felipe-software/react-native-jelly-tabs/llms.txt
Use this file to discover all available pages before exploring further.
This page documents every TypeScript interface and type alias exported from react-native-jelly-tabs. All types are available as named imports directly from the package.
import type {
TabsIconProps,
TabsIcon,
TabsItem,
TabsChangeEvent,
JellyTabBarHeadlessProps,
JellyTabBarProps,
JellyNavigationRoute,
JellyNavigationState,
JellyNavigationOptions,
JellyNavigationDescriptor,
JellyNavigationEvent,
JellyNavigationHelpers,
PillMaskedViewProps,
TouchFeedbackProps,
DeepPartial,
TabsProps,
} from 'react-native-jelly-tabs';
Icon types
TabsIconProps
The props object that react-native-jelly-tabs passes into each icon component when rendering a tab.
interface TabsIconProps {
color: string;
colors: Readonly<TabBarColors>;
opacity: number;
size: number;
}
| Field | Type | Description |
|---|
color | string | The resolved active or inactive content color for this icon’s current state. |
colors | Readonly<TabBarColors> | The full color palette in use, giving the icon access to every layer’s color. |
opacity | number | The resolved layer opacity for this icon’s current state. |
size | number | The resolved icon size in logical pixels, sourced from config.layout.iconSize. |
TabsIcon
A type alias for any React component that accepts TabsIconProps. Use this type when declaring your icon components to get full type inference.
type TabsIcon = ComponentType<TabsIconProps>;
Each TabsItem requires two TabsIcon components: one for the active (masked) state and one for the inactive (track) state.
Tab item and event types
TabsItem
Describes a single tab in the bar. Pass an array of these to the items prop.
interface TabsItem {
accessibilityLabel?: string;
key: string;
label: string;
labelStyle?: StyleProp<TextStyle>;
activeIcon: TabsIcon;
inactiveIcon: TabsIcon;
badge?: number | string;
badgeStyle?: StyleProp<TextStyle>;
testID?: string;
}
| Field | Type | Required | Description |
|---|
key | string | ✅ | Stable identifier used by React’s reconciler. Must be unique within the items array. |
label | string | ✅ | Display label shown below the icon. Truncated to one line with an ellipsis. |
activeIcon | TabsIcon | ✅ | Icon component rendered inside the animated pill mask (selected state). |
inactiveIcon | TabsIcon | ✅ | Icon component rendered in the track background (unselected state). |
accessibilityLabel | string | — | Custom accessibility label. Defaults to label when omitted. |
labelStyle | StyleProp<TextStyle> | — | Additional style applied to the tab label text. |
badge | number | string | — | Badge value displayed in the top-right corner of the tab. |
badgeStyle | StyleProp<TextStyle> | — | Style applied to the badge text. |
testID | string | — | Test identifier for end-to-end testing frameworks. |
TabsChangeEvent
Emitted by onTabPress, onTabLongPress, and onTabChange.
interface TabsChangeEvent {
index: number;
item: TabsItem;
}
| Field | Type | Description |
|---|
index | number | Zero-based index of the tab that was interacted with. |
item | TabsItem | The full TabsItem object for the interacted tab. |
Component prop interfaces
JellyTabBarHeadlessProps
All props accepted by <JellyTabBarHeadless />. Only items is required; every other prop falls back to a built-in default.
interface JellyTabBarHeadlessProps {
backdrop?: ReactNode;
colors?: Partial<TabBarColors>;
config?: DeepPartial<TabBarConfig>;
displayScale?: number;
maxWidth?: DimensionValue;
recording?: boolean;
items: readonly TabsItem[];
onTabChange?: (event: TabsChangeEvent) => void;
onTabLongPress?: (event: TabsChangeEvent) => void;
onTabPress?: (event: TabsChangeEvent) => boolean | void;
opacity?: Partial<TabBarOpacity>;
selectedIndex?: number | null;
selectedBackdrop?: ReactNode;
touchFeedbackEnabled?: boolean;
touchFeedbackColor?: string;
touchFeedbackOpacity?: number;
touchFeedbackScale?: number;
}
| Prop | Type | Default | Description |
|---|
items | readonly TabsItem[] | — | Required. Array of tab descriptors to render. |
selectedIndex | number | null | uncontrolled | Controlled selected tab index. Pass null or a negative number to show no selection. |
onTabPress | (event: TabsChangeEvent) => boolean | void | — | Fired after every completed tap or drag, including re-pressing the active tab. Return false to reject the change and restore the current selection. |
onTabLongPress | (event: TabsChangeEvent) => void | — | Fired when a tab is held down, and on the longpress accessibility action. |
onTabChange | (event: TabsChangeEvent) => void | — | Fired only when an accepted gesture results in a new selected tab. Rejected presses and re-taps on the active tab do not trigger this. |
colors | Partial<TabBarColors> | built-in palette | Partial color overrides. Merged over DEFAULT_TAB_BAR_COLORS. |
opacity | Partial<TabBarOpacity> | all 1 | Per-layer opacity values, clamped 0–1. |
config | DeepPartial<TabBarConfig> | see Config | Deep-partial override of layout, jelly, and distortion settings. |
backdrop | ReactNode | — | Node rendered below the track color layer (e.g. a blur view). |
selectedBackdrop | ReactNode | — | Node rendered below the selected-pill color layer. |
maxWidth | DimensionValue | 400 | Maximum track width. The bar stays centered inside wider parents. |
displayScale | number | 1 | Scales every layout dimension. Useful for recordings and thumbnails. |
touchFeedbackEnabled | boolean | true | Toggles the radial touch-feedback effect on or off. |
touchFeedbackColor | string | colors.selectedSurface | Overrides the radial touch-feedback color independently of the palette. |
touchFeedbackOpacity | number | distortion.touchFeedback.opacity | Overrides the touch-feedback base opacity. |
touchFeedbackScale | number | distortion.touchFeedback.scale | Overrides the touch-feedback radius scale multiplier. |
recording | boolean | false | Enables deterministic rendering mode for capturing clean recordings. |
JellyTabBarProps
Props for <JellyTabBar />, the React Navigation / Expo Router adapter. Extends JellyTabBarHeadlessProps (minus the props sourced automatically from the navigator), and adds navigation-specific fields.
interface JellyTabBarProps extends Omit<
JellyTabBarHeadlessProps,
'items' | 'onTabChange' | 'onTabLongPress' | 'onTabPress' | 'selectedIndex'
> {
containerStyle?: StyleProp<ViewStyle>;
descriptors: Readonly<Record<string, JellyNavigationDescriptor>>;
floating?: boolean;
insets: {
bottom: number;
left: number;
right: number;
top: number;
};
navigation: JellyNavigationHelpers;
state: JellyNavigationState;
}
| Field | Type | Description |
|---|
containerStyle | StyleProp<ViewStyle> | Additional style applied to the outermost wrapper view. |
descriptors | Readonly<Record<string, JellyNavigationDescriptor>> | Route descriptor map supplied by the navigator. Contains per-route options. |
floating | boolean | When true, the bar is absolutely positioned over the screen content. |
insets | { bottom, left, right, top: number } | Safe-area insets supplied by the navigator. |
navigation | JellyNavigationHelpers | Navigation action dispatcher supplied by the navigator. |
state | JellyNavigationState | Current navigation state, including the active route index. |
items, onTabChange, onTabLongPress, onTabPress, and selectedIndex are omitted from JellyTabBarProps because JellyTabBar derives them automatically from state, descriptors, and navigation. Pass JellyTabBar directly to your navigator’s tabBar prop.
Navigation integration types
These types mirror the shapes that React Navigation and Expo Router supply to custom tab bar components. You generally do not construct these yourself.
JellyNavigationRoute
A single route entry in the navigation state.
interface JellyNavigationRoute {
key: string;
name: string;
params?: object;
path?: string;
}
| Field | Type | Description |
|---|
key | string | Unique, stable route key assigned by the navigator. |
name | string | Screen name as registered in the navigator. |
params | object | Optional route parameters. |
path | string | Optional URL path for linking. |
JellyNavigationState
The full navigation state passed to <JellyTabBar /> via the state prop.
interface JellyNavigationState {
index: number;
key: string;
routes: readonly JellyNavigationRoute[];
}
| Field | Type | Description |
|---|
index | number | Index of the currently active route. |
key | string | Unique key for this navigation state instance. |
routes | readonly JellyNavigationRoute[] | Ordered list of all registered routes. |
JellyNavigationOptions
Per-screen options read from descriptors to configure each tab. Maps closely to the React Navigation bottom tabs API.
interface JellyNavigationOptions {
href?: unknown;
tabBarAccessibilityLabel?: string;
tabBarActiveBackgroundColor?: unknown;
tabBarActiveTintColor?: unknown;
tabBarBackground?: () => ReactNode;
tabBarBadge?: number | string;
tabBarBadgeStyle?: StyleProp<TextStyle>;
tabBarButtonTestID?: string;
tabBarIcon?: (props: {
color: string;
focused: boolean;
size: number;
}) => ReactNode;
tabBarInactiveBackgroundColor?: unknown;
tabBarInactiveTintColor?: unknown;
tabBarLabel?: unknown;
tabBarLabelStyle?: StyleProp<TextStyle>;
tabBarShowLabel?: boolean;
tabBarStyle?: unknown;
title?: string;
}
| Field | Description |
|---|
href | Expo Router href: null convention — used to hide a tab from the bar. |
tabBarAccessibilityLabel | Custom accessibility label for the tab button. |
tabBarActiveTintColor | Icon/label color for the active state. |
tabBarInactiveTintColor | Icon/label color for the inactive state. |
tabBarBackground | Function returning a React node rendered behind the tab bar. |
tabBarBadge | Badge value shown on the tab. |
tabBarBadgeStyle | Style for the badge text. |
tabBarButtonTestID | Test ID for the tab button. |
tabBarIcon | Function returning a React node for the tab icon. |
tabBarLabel | Custom tab label string. |
tabBarLabelStyle | Style for the tab label text. |
tabBarShowLabel | Whether to show the text label. |
title | Screen title used as fallback label. |
JellyNavigationDescriptor
Wraps the resolved options for a single route.
interface JellyNavigationDescriptor {
options: JellyNavigationOptions;
}
| Field | Type | Description |
|---|
options | JellyNavigationOptions | The resolved screen options for this route. |
JellyNavigationEvent
The event object emitted by navigation.emit() when a tab is pressed or long-pressed.
interface JellyNavigationEvent {
canPreventDefault?: boolean;
target: string;
type: 'tabPress' | 'tabLongPress';
}
| Field | Type | Description |
|---|
canPreventDefault | boolean | When true, listeners may call preventDefault() to cancel the navigation. |
target | string | The route key of the tab that was interacted with. |
type | 'tabPress' | 'tabLongPress' | The kind of interaction that occurred. |
JellyNavigationHelpers
The navigation object supplied to <JellyTabBar /> via the navigation prop.
interface JellyNavigationHelpers {
dispatch(action: {
payload: {
name: string;
params?: object;
path?: string;
};
target: string;
type: 'NAVIGATE';
}): void;
emit(event: JellyNavigationEvent): unknown;
}
| Method | Description |
|---|
dispatch(action) | Dispatches a NAVIGATE action to the navigator to change the active route. |
emit(event) | Emits a navigation event (e.g. tabPress) that screen listeners can subscribe to. |
Primitive component prop interfaces
PillMaskedViewProps
Props for the <PillMaskedView /> low-level component, which renders the animated pill-shaped mask over the active icon layer.
interface PillMaskedViewProps extends PropsWithChildren {
animatedStyle: StyleProp<AnimatedStyle<ViewStyle>>;
clipStyle: StyleProp<AnimatedStyle<ViewStyle>>;
contentHeight: number;
contentStyle: StyleProp<AnimatedStyle<ViewStyle>>;
contentWidth: number;
height: number;
left: number;
tabWidth: number;
top: number;
}
| Field | Type | Description |
|---|
animatedStyle | StyleProp<AnimatedStyle<ViewStyle>> | Animated style applied to the pill mask shape (position, scale, etc.). |
clipStyle | StyleProp<AnimatedStyle<ViewStyle>> | Animated style applied to the web clip box (web only). |
contentHeight | number | Height of the content container inside the mask. |
contentStyle | StyleProp<AnimatedStyle<ViewStyle>> | Animated inverse-transform style to keep children fixed to the track (web only). |
contentWidth | number | Width of the content container inside the mask. |
height | number | Height of the pill mask in logical pixels. |
left | number | Left offset of the pill mask relative to the track. |
tabWidth | number | Width of a single tab slot, used as the pill’s initial width on web. |
top | number | Top offset of the pill mask relative to the track. |
children | ReactNode | Content rendered inside (and clipped by) the pill mask. |
TouchFeedbackProps
Props for the <TouchFeedback /> low-level component, which renders the radial gradient glow on tap.
interface TouchFeedbackProps {
animatedStyle: StyleProp<AnimatedStyle<ViewStyle>>;
centerOpacity: number;
color?: string;
diameter: number;
gradientId: string;
middleOpacity: number;
offsetX?: number;
offsetY?: number;
radius: number;
}
| Field | Type | Default | Description |
|---|
animatedStyle | StyleProp<AnimatedStyle<ViewStyle>> | — | Animated style controlling opacity and position of the glow. |
centerOpacity | number | — | Opacity of the radial gradient at its center stop (0%). |
color | string | '#ffffff' | Color of the radial gradient. |
diameter | number | — | Total diameter of the SVG viewport (radius * 2). |
gradientId | string | — | Unique ID for the SVG <RadialGradient> element. Must be unique per instance. |
middleOpacity | number | — | Opacity at the gradient’s middle stop (45%). |
offsetX | number | 0 | Horizontal offset of the glow center from the left edge of its container. |
offsetY | number | 0 | Vertical offset of the glow center from the top edge of its container. |
radius | number | — | Radius of the radial gradient in logical pixels. |
Utility types
DeepPartial<T>
A recursive utility type that makes all properties (and nested properties) of T optional. Used as the type of the config prop so you only need to pass the keys you want to override.
type DeepPartial<T> = {
[Key in keyof T]?: T[Key] extends object ? DeepPartial<T[Key]> : T[Key];
};
Example:
import type { DeepPartial, TabBarConfig } from 'react-native-jelly-tabs';
// Only the fields you care about — everything else uses defaults
const myConfig: DeepPartial<TabBarConfig> = {
layout: {
iconSize: 24,
},
distortion: {
spring: {
stiffness: 300,
},
},
};
TabsProps (deprecated)
/** @deprecated Use JellyTabBarHeadlessProps instead. */
type TabsProps = JellyTabBarHeadlessProps;
TabsProps is a legacy alias for JellyTabBarHeadlessProps, kept for backwards compatibility. Update your code to reference JellyTabBarHeadlessProps directly.