react-native-expandable-tabs

A lightweight, animated expandable tab component for React Native with zero runtime dependencies. Perfect for floating action buttons, bottom navigation, and contextual menus.

---

🎥 Demo

---

Table of Contents

• Features
• Installation
• Basic Usage
• Examples
  • Horizontal Mode (Default)
  • Vertical Mode
  • Radial Mode
  • With Overlay
  • Custom Theme
  • Controlled Mode
  • With Ref API
• API Reference
  • Props
  • Tab Object
  • Events
  • Ref API
  • Custom Rendering
• Accessibility
• Contributing
• License
• Support

---

Features

• 🎯 Press to expand — Center button triggers smooth tab expansion
• 🎨 Multiple directions — Horizontal, vertical, radial, semi-circle, and arc
• ⚡ Smooth animations — Built with React Native's Animated API
• 📱 Cross-platform — Works on iOS, Android, and Expo
• 🎛️ Highly configurable — Colors, sizes, animations, and more
• ♿ Accessible — Built-in accessibility support
• 🪶 Lightweight — Zero runtime dependencies
• 🔄 Controlled/Uncontrolled — Flexible state management
• 📦 Ref API — Programmatic control

---

Installation

npm install react-native-expandable-tabs

or

yarn add react-native-expandable-tabs

---

Basic Usage

import React, { useState } from "react";
import ExpandableTabs from "react-native-expandable-tabs";

const tabs = [
  { key: "home", label: "Home", icon: "🏠" },
  { key: "search", label: "Search", icon: "🔍" },
  { key: "profile", label: "Profile", icon: "👤" },
  { key: "settings", label: "Settings", icon: "⚙️", badge: 5 },
];

const App = () => {
  const [activeTab, setActiveTab] = useState("home");

  return (
    <ExpandableTabs
      tabs={tabs}
      activeTab={activeTab}
      onTabPress={(tab) => setActiveTab(tab.key)}
    />
  );
};

export default App;

---

Examples

Horizontal Mode (Default)

<ExpandableTabs tabs={tabs} direction="horizontal" radius={120} />

Vertical Mode

<ExpandableTabs tabs={tabs} direction="vertical" radius={120} />

Radial Mode

<ExpandableTabs
  tabs={tabs}
  direction="radial"
  radius={140}
  startAngle={0}
  endAngle={360}
/>

With Overlay

<ExpandableTabs
  tabs={tabs}
  showOverlay={true}
  overlayOpacity={0.3}
  closeOnOverlayPress={true}
/>

Custom Theme

<ExpandableTabs
  tabs={tabs}
  primaryColor="#6C63FF"
  activeColor="#6C63FF"
  backgroundColor="#FFFFFF"
  textColor="#333333"
  tabSize={50}
  centerButtonSize={60}
/>

Controlled Mode

const [expanded, setExpanded] = useState(false);

<ExpandableTabs
  tabs={tabs}
  expanded={expanded}
  onExpandedChange={setExpanded}
/>;

With Ref API

const tabsRef = useRef(null);

<ExpandableTabs ref={tabsRef} tabs={tabs} />;

// Programmatic control
tabsRef.current.open();
tabsRef.current.close();
tabsRef.current.toggle();
const activeTab = tabsRef.current.getActiveTab();

---

API Reference

Props

Prop	Type	Default	Description
tabs	array	Required	Array of tab objects
direction	string	'horizontal'	Expansion direction: 'horizontal', 'vertical', 'radial', 'semi-circle', 'arc'
position	string	'bottom-center'	Position on screen: 'bottom-center', 'bottom-left', 'bottom-right', 'top-center', 'top-left', 'top-right'
radius	number	120	Distance tabs expand from center
startAngle	number	0	Starting angle for radial/arc modes
endAngle	number	360	Ending angle for radial/arc modes
expanded	bool	-	Controlled expanded state
defaultExpanded	bool	false	Default expanded state
activeTab	string	-	Controlled active tab key
defaultActiveTab	string	-	Default active tab key
animationType	string	'timing'	'timing' or 'spring'
animationDuration	number	300	Animation duration in ms
stagger	number	40	Stagger delay between tabs in ms
showLabels	bool	true	Show tab labels
showOverlay	bool	false	Show overlay when expanded
overlayOpacity	number	0.2	Overlay opacity
closeOnTabPress	bool	true	Close menu when tab is pressed
closeOnOverlayPress	bool	true	Close menu when overlay is pressed
primaryColor	string	'#6200EE'	Primary color for center button
activeColor	string	'#6200EE'	Active tab color
inactiveColor	string	'#777777'	Inactive tab color
backgroundColor	string	'#FFFFFF'	Tab background color
textColor	string	'#111111'	Tab text color
tabSize	number	50	Tab size (width/height)
centerButtonSize	number	60	Center button size
iconSize	number	24	Icon size
labelFontSize	number	12	Label font size
badgeSize	number	20	Badge size
edgePadding	number	20	Minimum distance from screen edges
centerButtonRotation	number	45	Rotation angle for center button
centerButtonScale	number	1.05	Scale factor for center button
centerButtonAnimationDuration	number	250	Center button animation duration

Tab Object

Property	Type	Description
key	string	Required — Unique identifier
label	string	Tab label
icon	string | ReactElement	Tab icon (text or component)
badge	string | number	Badge value
disabled	bool	Disable tab

Events

Prop	Type	Description
onTabPress	(tab, index) => void	Called when tab is pressed
onTabChange	(tab, index) => void	Called when active tab changes
onExpandedChange	(expanded) => void	Called when expansion state changes
onOpen	() => void	Called when menu opens
onClose	() => void	Called when menu closes
onToggle	(expanded) => void	Called when menu toggles
onAnimationStart	(expanded) => void	Called when animation starts
onAnimationEnd	(expanded) => void	Called when animation ends

Ref API

Method	Description
open()	Expand the menu
close()	Collapse the menu
toggle()	Toggle menu state
getActiveTab()	Get the currently active tab
isExpanded()	Check if menu is expanded

Custom Rendering

Prop	Type	Description
renderCenterIcon	() => ReactNode	Custom center button icon (collapsed)
renderExpandedCenterIcon	() => ReactNode	Custom center button icon (expanded)
renderTab	(tab, index, isActive) => ReactNode	Custom tab renderer
renderTabIcon	({ icon, size, color }) => ReactNode	Custom tab icon renderer
renderTabLabel	({ label, isActive, textColor, fontSize }) => ReactNode	Custom tab label renderer
renderBadge	({ badge, size }) => ReactNode	Custom badge renderer

---

Accessibility

The component includes built-in accessibility support:

• accessibilityRole="button" for the center button
• accessibilityRole="tab" for tabs
• accessibilityState for expanded/selected/disabled states
• Configurable labels and hints

---

License

This project is under the MIT license.

---

Author

Built with ❤️ by Nascenture.

• 🌐 Website: https://www.nascenture.com
• 📱 React Native Development Services: https://www.nascenture.com/react-native-app-development/