Action Sheets in React Native: Expo Managed vs. Bare CLI

When adding action sheets to a React Native app, the choice between @expo/react-native-action-sheet and react-native-action-sheet usually comes down to one architectural decision: Are you using the Expo Managed Workflow? While they share similar APIs for showing options, their installation and native integration paths are completely different. Let's break down how they fit into your project structure.

🏗️ Installation and Native Linking

The most critical difference is how these libraries connect to native code. This decision often dictates your entire build pipeline.

@expo/react-native-action-sheet is designed for the Expo Managed Workflow.

• It uses Expo Config Plugins to automatically inject native code during the pre-build phase.
• You do not touch Xcode or Android Studio files directly.
• Ideal for teams wanting to stay within the Expo ecosystem.

# Install the Expo-specific wrapper
npx expo install @expo/react-native-action-sheet

// No manual linking required. Expo handles it via app.json/config plugins.

react-native-action-sheet is for Bare React Native or Ejected Expo apps.

• It requires manual linking or react-native link (though manual is preferred for stability).
• You must modify Podfile on iOS and settings.gradle/build.gradle on Android.
• If you try to use this in a pure Managed Workflow without custom config plugins, the build will fail because the native modules won't be found.

# Install the core community library
npm install react-native-action-sheet

# iOS: You must manually run pod install
cd ios && pod install

// Android: Ensure the package is included in settings.gradle
// rootProject.include(':react-native-action-sheet')

🎣 Provider Setup and Context

Both libraries rely on a React Context provider to inject the action sheet logic into your component tree. The implementation looks nearly identical in JavaScript, which is intentional since the Expo package wraps the core logic.

@expo/react-native-action-sheet uses the ActionSheetProvider from the Expo namespace.

• It ensures the context is compatible with Expo's navigation and lifecycle methods.
• Best for apps that might run in Expo Go during development.

// App.js (Expo Managed)
import { ActionSheetProvider } from '@expo/react-native-action-sheet';

export default function App() {
  return (
    <ActionSheetProvider>
      <NavigationContainer>
        <RootStack />
      </NavigationContainer>
    </ActionSheetProvider>
  );
}

react-native-action-sheet uses the ActionSheetProvider from the core package.

• Functionally the same, but relies on the native modules being correctly linked in your bare project.
• If linking is missed, the showActionSheetWithOptions call will throw a native module error.

// App.js (Bare CLI)
import { ActionSheetProvider } from 'react-native-action-sheet';

export default function App() {
  return (
    <ActionSheetProvider>
      <NavigationContainer>
        <RootStack />
      </NavigationContainer>
    </ActionSheetProvider>
  );
}

🖱️ Triggering the Action Sheet

Once the provider is set up, consuming the action sheet is identical in both packages. You access the showActionSheetWithOptions method via the useActionSheet hook. This consistency makes migrating between bare and managed workflows easier if you abstract the hook usage.

Both packages use the same options structure.

• You define options, cancelButtonIndex, and destructiveButtonIndex.
• The UI adapts automatically to iOS (bottom sheet) and Android (dialog).

// Shared usage pattern for BOTH packages
import { useActionSheet } from '@expo/react-native-action-sheet'; // OR 'react-native-action-sheet'

function MyComponent() {
  const { showActionSheetWithOptions } = useActionSheet();

  const handlePress = () => {
    const options = ['Delete', 'Save', 'Cancel'];
    const cancelButtonIndex = 2;
    const destructiveButtonIndex = 0;

    showActionSheetWithOptions(
      {
        options,
        cancelButtonIndex,
        destructiveButtonIndex,
        title: 'Choose an action',
      },
      (buttonIndex) => {
        if (buttonIndex === 0) console.log('Delete selected');
        if (buttonIndex === 1) console.log('Save selected');
      }
    );
  };

  return <Button title="Open Sheet" onPress={handlePress} />;
}

📱 Platform Behavior and Customization

Both libraries aim to mimic native behavior strictly. They do not try to create a custom JavaScript-based UI unless the native module fails. This ensures high performance and correct accessibility traits on both platforms.

iOS Behavior

• Renders a UIAlertController with style actionSheet.
• Automatically dims the background.
• Supports title and message headers natively.

Android Behavior

• Renders a BottomSheetDialog or standard AlertDialog depending on OS version.
• Matches the device's system theme (Light/Dark mode) automatically.

// Both packages support custom styling via options (limited to native capabilities)
showActionSheetWithOptions(
  {
    options: ['Option 1', 'Option 2', 'Cancel'],
    cancelButtonIndex: 2,
    // 'tintColor' works on iOS to change button text color
    tintColor: '#007AFF', 
    // 'anchoredView' can be passed on iPad to anchor the sheet
  },
  callback
);

⚠️ Common Pitfalls and Migration

A frequent mistake is installing react-native-action-sheet in an Expo Managed project and wondering why the build crashes. The Expo runtime cannot find the native module because it wasn't injected via the Expo config system.

If you are in Expo Managed:

• ❌ Do NOT install react-native-action-sheet directly unless you write a custom config plugin.
• ✅ Use @expo/react-native-action-sheet.

If you are in Bare/CLI:

• ❌ Do NOT use @expo/react-native-action-sheet as it adds unnecessary Expo dependencies.
• ✅ Use react-native-action-sheet and verify your Podfile.

// Incorrect setup in Expo Managed (Will fail on build)
import { ActionSheetProvider } from 'react-native-action-sheet'; 
// Error: Native module ActionSheetManager not found

// Correct setup in Expo Managed
import { ActionSheetProvider } from '@expo/react-native-action-sheet';
// Works seamlessly with EAS Build and Expo Prebuild

📊 Summary: Key Differences

💡 The Big Picture

These two packages are essentially the same engine in different chassis. react-native-action-sheet is the raw engine meant for developers who build their own car (Bare CLI). @expo/react-native-action-sheet is the same engine pre-installed in a Tesla (Expo Managed), ready to drive out of the box.

Final Recommendation:

• If your app.json exists and you run npx expo start, stick with @expo/react-native-action-sheet. It saves hours of debugging native build errors.
• If you run npx react-native run-ios and manage your own Podfile, use react-native-action-sheet for a lighter dependency tree and direct control.