ActionSheetIOS: Native iOS Action Menus

WHY IT EXISTS: Apps often need to present a user with a few choices related to an action, without navigating to a new screen. A full-screen modal can be too heavy. The native iOS Action Sheet provides a lightweight, familiar, and context-specific way to handle this common UI pattern.

THE MENTAL MODEL: Think of ActionSheetIOS as a remote control for the built-in iOS menu that slides up from the bottom of the screen. You don't build the UI yourself; you just provide React Native with a list of button titles and tell it which ones are for canceling or destructive actions, and iOS handles the rest.

HOW IT WORKS: The API has three main static methods. The primary one is showActionSheetWithOptions. You pass it an options object and a callback function. The options object defines the button titles, message, and which buttons are "destructive" (often colored red) or "cancel". The callback function receives the index of the button the user tapped, allowing your app to respond. A second method, showShareActionSheetWithOptions, is a specialized version that opens the native iOS share dialog. The final method, dismissActionSheet, programmatically closes the sheet.

WHEN TO USE IT: Use ActionSheetIOS when you need to present a small number of simple, contextual actions on an iOS app. It's perfect for confirming a deletion, choosing a photo source (e.g., camera or library), or providing options on a list item. The share sheet variant is the standard way to implement sharing functionality on iOS.

WHEN NOT TO USE IT: Do not use this API if your app needs to run on Android, as it will cause a crash. For cross-platform apps, you must check Platform.OS === 'ios' before calling it. If you need a consistent UI on both platforms or more complex menu content than just text buttons, use a custom component or a third-party library instead.

ONE CANONICAL EXAMPLE: To ask a user to confirm removing an item, you would call ActionSheetIOS.showActionSheetWithOptions. You'd provide an options array like ['Cancel', 'Remove'], set destructiveButtonIndex to 1 (for 'Remove'), and cancelButtonIndex to 0. In the callback, you check if the tapped buttonIndex is 1. If it is, you proceed with the removal logic.