Skip to main content

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;
}
FieldTypeDescription
colorstringThe resolved active or inactive content color for this icon’s current state.
colorsReadonly<TabBarColors>The full color palette in use, giving the icon access to every layer’s color.
opacitynumberThe resolved layer opacity for this icon’s current state.
sizenumberThe 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;
}
FieldTypeRequiredDescription
keystringStable identifier used by React’s reconciler. Must be unique within the items array.
labelstringDisplay label shown below the icon. Truncated to one line with an ellipsis.
activeIconTabsIconIcon component rendered inside the animated pill mask (selected state).
inactiveIconTabsIconIcon component rendered in the track background (unselected state).
accessibilityLabelstringCustom accessibility label. Defaults to label when omitted.
labelStyleStyleProp<TextStyle>Additional style applied to the tab label text.
badgenumber | stringBadge value displayed in the top-right corner of the tab.
badgeStyleStyleProp<TextStyle>Style applied to the badge text.
testIDstringTest identifier for end-to-end testing frameworks.

TabsChangeEvent

Emitted by onTabPress, onTabLongPress, and onTabChange.
interface TabsChangeEvent {
  index: number;
  item: TabsItem;
}
FieldTypeDescription
indexnumberZero-based index of the tab that was interacted with.
itemTabsItemThe 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;
}
PropTypeDefaultDescription
itemsreadonly TabsItem[]Required. Array of tab descriptors to render.
selectedIndexnumber | nulluncontrolledControlled selected tab index. Pass null or a negative number to show no selection.
onTabPress(event: TabsChangeEvent) => boolean | voidFired 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) => voidFired when a tab is held down, and on the longpress accessibility action.
onTabChange(event: TabsChangeEvent) => voidFired only when an accepted gesture results in a new selected tab. Rejected presses and re-taps on the active tab do not trigger this.
colorsPartial<TabBarColors>built-in palettePartial color overrides. Merged over DEFAULT_TAB_BAR_COLORS.
opacityPartial<TabBarOpacity>all 1Per-layer opacity values, clamped 01.
configDeepPartial<TabBarConfig>see ConfigDeep-partial override of layout, jelly, and distortion settings.
backdropReactNodeNode rendered below the track color layer (e.g. a blur view).
selectedBackdropReactNodeNode rendered below the selected-pill color layer.
maxWidthDimensionValue400Maximum track width. The bar stays centered inside wider parents.
displayScalenumber1Scales every layout dimension. Useful for recordings and thumbnails.
touchFeedbackEnabledbooleantrueToggles the radial touch-feedback effect on or off.
touchFeedbackColorstringcolors.selectedSurfaceOverrides the radial touch-feedback color independently of the palette.
touchFeedbackOpacitynumberdistortion.touchFeedback.opacityOverrides the touch-feedback base opacity.
touchFeedbackScalenumberdistortion.touchFeedback.scaleOverrides the touch-feedback radius scale multiplier.
recordingbooleanfalseEnables 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;
}
FieldTypeDescription
containerStyleStyleProp<ViewStyle>Additional style applied to the outermost wrapper view.
descriptorsReadonly<Record<string, JellyNavigationDescriptor>>Route descriptor map supplied by the navigator. Contains per-route options.
floatingbooleanWhen true, the bar is absolutely positioned over the screen content.
insets{ bottom, left, right, top: number }Safe-area insets supplied by the navigator.
navigationJellyNavigationHelpersNavigation action dispatcher supplied by the navigator.
stateJellyNavigationStateCurrent 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.

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;
}
FieldTypeDescription
keystringUnique, stable route key assigned by the navigator.
namestringScreen name as registered in the navigator.
paramsobjectOptional route parameters.
pathstringOptional 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[];
}
FieldTypeDescription
indexnumberIndex of the currently active route.
keystringUnique key for this navigation state instance.
routesreadonly 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;
}
FieldDescription
hrefExpo Router href: null convention — used to hide a tab from the bar.
tabBarAccessibilityLabelCustom accessibility label for the tab button.
tabBarActiveTintColorIcon/label color for the active state.
tabBarInactiveTintColorIcon/label color for the inactive state.
tabBarBackgroundFunction returning a React node rendered behind the tab bar.
tabBarBadgeBadge value shown on the tab.
tabBarBadgeStyleStyle for the badge text.
tabBarButtonTestIDTest ID for the tab button.
tabBarIconFunction returning a React node for the tab icon.
tabBarLabelCustom tab label string.
tabBarLabelStyleStyle for the tab label text.
tabBarShowLabelWhether to show the text label.
titleScreen title used as fallback label.

JellyNavigationDescriptor

Wraps the resolved options for a single route.
interface JellyNavigationDescriptor {
  options: JellyNavigationOptions;
}
FieldTypeDescription
optionsJellyNavigationOptionsThe 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';
}
FieldTypeDescription
canPreventDefaultbooleanWhen true, listeners may call preventDefault() to cancel the navigation.
targetstringThe 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;
}
MethodDescription
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;
}
FieldTypeDescription
animatedStyleStyleProp<AnimatedStyle<ViewStyle>>Animated style applied to the pill mask shape (position, scale, etc.).
clipStyleStyleProp<AnimatedStyle<ViewStyle>>Animated style applied to the web clip box (web only).
contentHeightnumberHeight of the content container inside the mask.
contentStyleStyleProp<AnimatedStyle<ViewStyle>>Animated inverse-transform style to keep children fixed to the track (web only).
contentWidthnumberWidth of the content container inside the mask.
heightnumberHeight of the pill mask in logical pixels.
leftnumberLeft offset of the pill mask relative to the track.
tabWidthnumberWidth of a single tab slot, used as the pill’s initial width on web.
topnumberTop offset of the pill mask relative to the track.
childrenReactNodeContent 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;
}
FieldTypeDefaultDescription
animatedStyleStyleProp<AnimatedStyle<ViewStyle>>Animated style controlling opacity and position of the glow.
centerOpacitynumberOpacity of the radial gradient at its center stop (0%).
colorstring'#ffffff'Color of the radial gradient.
diameternumberTotal diameter of the SVG viewport (radius * 2).
gradientIdstringUnique ID for the SVG <RadialGradient> element. Must be unique per instance.
middleOpacitynumberOpacity at the gradient’s middle stop (45%).
offsetXnumber0Horizontal offset of the glow center from the left edge of its container.
offsetYnumber0Vertical offset of the glow center from the top edge of its container.
radiusnumberRadius 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.

Build docs developers (and LLMs) love