@xpario/reactnative-floating-buttons

A customizable floating action button (FAB) component for React Native and Expo. Displays an expandable button that reveals a configurable set of action buttons, each with its own icon, color, and callback.

Installation

npm install @xpario/reactnative-floating-buttons

Required Dependencies

Your project must have the following packages installed (they are not bundled with this package):

npm install react react-native @expo/vector-icons @react-navigation/native react-native-safe-area-context @xpario/reactnative-accessibility

Compatible with Expo SDK 49+ (tested through SDK 55).

Components

FloatingImageButtons

The main component. Renders a floating action button that expands to reveal a vertical stack of action buttons.

import { FloatingImageButtons } from '@xpario/reactnative-floating-buttons';

Props

| Prop | Type | Default | Description | |---|---|---|---| | buttons | FloatingButton[] | Required | Array of action buttons to display when expanded | | collapsedButtons | FloatingButton[] | [] | Array of buttons to display when the FAB is collapsed (hidden when expanded) | | buttonColor | string | 'red' | Background color of the main toggle button | | borderColor | string | 'black' | Border color for all buttons | | iconColor | string | 'white' | Icon color for the main toggle button | | buttonSize | number | 25 | Size of the main toggle button in pixels | | bottomPosition | number | 20 | Distance from the bottom of the screen (safe area insets are added automatically) | | rightPosition | number | 20 | Distance from the right of the screen | | visible | boolean | true | Whether the FAB is visible | | shaded | boolean | false | Whether to apply a drop shadow to the buttons |

FloatingButton

The shape of each action button in the buttons array.

| Property | Type | Required | Default | Description | |---|---|---|---|---| | id | string | Yes | - | Unique identifier for the button | | icon | string | Yes | - | Icon name from the button's icon family (default Entypo) | | iconFamily | string | No | 'Entypo' | (1.0.11) Any family exported by @expo/vector-icons — e.g. 'FontAwesome', 'MaterialCommunityIcons', 'Ionicons', 'Feather'. Unknown names fall back to Entypo. Browse names at icons.expo.fyi | | name | string | Yes | - | Accessibility label for the button | | onPress | () => void | Yes | - | Callback when the button is pressed | | buttonColor | string | No | Inherits from parent | Background color override for this button | | borderColor | string | No | Inherits from parent | Border color override for this button | | iconColor | string | No | Inherits from parent | Icon color override for this button | | buttonSize | number | No | 80% of parent size | Size override for this button |

DetailButton

A single circular icon button. Used internally by FloatingImageButtons but exported for standalone use.

import { DetailButton } from '@xpario/reactnative-floating-buttons';

Props

| Prop | Type | Default | Description | |---|---|---|---| | icon | string | Required | Icon name from the button's icon family (default Entypo) | | iconFamily | string | 'Entypo' | (1.0.11) Any @expo/vector-icons family name; unknown names fall back to Entypo | | name | string | Required | Accessibility label | | onPress | () => void | Required | Callback when pressed | | buttonSize | number | Required | Button size in pixels | | buttonBorderWidth | number | Required | Border width in pixels | | shaded | boolean | false | Whether to apply a drop shadow | | iconColor | string | 'white' | Icon color | | buttonColor | string | 'red' | Background color | | borderColor | string | 'black' | Border color |

Usage Examples

Basic Usage

A simple FAB with camera and gallery buttons:

import React from 'react';
import { View, Alert } from 'react-native';
import { FloatingImageButtons } from '@xpario/reactnative-floating-buttons';

export default function MyScreen() {
  return (
    <View style={{ flex: 1 }}>
      {/* Your screen content */}

      <FloatingImageButtons
        buttons={[
          {
            id: 'camera',
            icon: 'camera',
            name: 'Take Photo',
            onPress: () => Alert.alert('Camera', 'Opening camera...'),
          },
          {
            id: 'gallery',
            icon: 'image',
            name: 'Choose from Gallery',
            onPress: () => Alert.alert('Gallery', 'Opening gallery...'),
          },
        ]}
      />
    </View>
  );
}

Custom Colors and Size

<FloatingImageButtons
  buttons={[
    {
      id: 'camera',
      icon: 'camera',
      name: 'Take Photo',
      onPress: handleCameraPress,
    },
    {
      id: 'gallery',
      icon: 'image',
      name: 'Choose from Gallery',
      onPress: handleGalleryPress,
    },
  ]}
  buttonColor="#FF6B6B"
  borderColor="#333333"
  iconColor="#FFFFFF"
  buttonSize={30}
  bottomPosition={40}
  rightPosition={20}
  shaded={true}
/>

Per-Button Color Overrides

Each button can override the default colors:

<FloatingImageButtons
  buttons={[
    {
      id: 'camera',
      icon: 'camera',
      name: 'Take Photo',
      buttonColor: '#4ECDC4',
      iconColor: '#FFFFFF',
      onPress: handleCameraPress,
    },
    {
      id: 'delete',
      icon: 'trash',
      name: 'Delete',
      buttonColor: '#FF4444',
      iconColor: '#FFFFFF',
      onPress: handleDelete,
    },
  ]}
  buttonColor="#2196F3"
  borderColor="#1565C0"
/>

Collapsed Buttons (Always-Visible Actions)

Show buttons above the FAB even when it's not expanded. When the user taps the FAB to expand, the collapsed buttons are replaced by the expanded buttons. A common use case is a refresh button that's always accessible:

<FloatingImageButtons
  buttons={[
    {
      id: 'camera',
      icon: 'camera',
      name: 'Take Photo',
      onPress: handleCameraPress,
    },
    {
      id: 'gallery',
      icon: 'image',
      name: 'Choose from Gallery',
      onPress: handleGalleryPress,
    },
  ]}
  collapsedButtons={[
    {
      id: 'refresh',
      icon: 'cycle',
      name: 'Refresh List',
      buttonColor: '#3498DB',
      borderColor: '#2980B9',
      iconColor: '#FFFFFF',
      buttonSize: 45,
      onPress: handleRefresh,
    },
  ]}
  buttonColor="#FF6B6B"
  borderColor="#333333"
  iconColor="#FFFFFF"
  buttonSize={60}
/>

Conditional Visibility

The FAB automatically closes when the screen loses focus (via useIsFocused from React Navigation). You can also control visibility manually:

const [showFab, setShowFab] = React.useState(true);

<FloatingImageButtons
  buttons={myButtons}
  visible={showFab}
/>

Using with Any Entypo Icon

The icon prop accepts any icon name from the Entypo icon set. Some common examples:

• camera - Camera
• image - Image/gallery
• plus - Add
• trash - Delete
• share - Share
• edit - Edit/pencil
• upload - Upload
• download - Download
• location-pin - Location
• attachment - Attachment

TypeScript

All types are exported for use in your TypeScript projects:

import type {
  FloatingImageButtonsProps,
  FloatingButton,
} from '@xpario/reactnative-floating-buttons';

Features

• Expandable floating action button with open/close toggle
• Collapsed buttons: show actions above the FAB even when not expanded
• Configurable number of action buttons with individual styling
• Safe area aware positioning (accounts for notches, home indicators, etc.)
• Built-in accessibility support via @xpario/reactnative-accessibility
• Automatic close on screen blur (React Navigation integration)
• Full TypeScript support with exported types
• Compatible with Expo SDK 49-55 and bare React Native

Development

This project uses npm workspaces. The example app references the library directly, so changes to src/ are reflected after rebuilding.

# Install all dependencies (root + example)
npm install

# Build the library
npx tsc -p tsconfig.json --skipLibCheck

# Run the example app
cd example
npx expo start

After making changes to the library source, rebuild with npx tsc -p tsconfig.json --skipLibCheck from the project root, then refresh Expo Go.

License

MIT