iOS Developer Library — Prerelease

Developer

UIKit User Interface Catalog

On This Page

Action Sheets

Action sheets display a set of buttons representing several alternative choices to complete a task initiated by the user. For example, when the user taps the Share button in an app’s toolbar, an action sheet appears offering a list of choices, such as Email, Print, and so on.

image: ../Art/uiactionsheet_intro_2x.png

Purpose. Action sheets allow users to:

  • Quickly select from a list of actions

  • Confirm or cancel an action

Implementation. Action sheets are implemented in the UIActionSheet class and discussed in the UIActionSheet Class Reference.

Configuration. Action sheets are created, initialized, and configured in code, typically residing in a view controller implementation file.

Content of Action Sheets (Programmatic)

You cannot create or manipulate action sheets in Interface Builder. Rather, an action sheet floats over an existing view to interrupt its presentation, and it requires the user to dismiss it.

When you create an action sheet object from the UIActionSheet class, you can initialize its most important properties with one method, initWithTitle:delegate:cancelButtonTitle:destructiveButtonTitle:otherButtonTitles:. Depending on your app’s needs, that single message may be enough to configure a fully functional action sheet object, as shown in the following code. Once you have created the action sheet object, send it a show... message, such as showInView: to display the action sheet.

  1. UIActionSheet *actionSheet = [[UIActionSheet alloc] initWithTitle:nil
  2. delegate:self
  3. cancelButtonTitle:@"Cancel"
  4. destructiveButtonTitle:@"Delete Note"
  5. otherButtonTitles:nil];

Although the first parameter of the initWithTitle:delegate:cancelButtonTitle:destructiveButtonTitle:otherButtonTitles: method enables you to provide a title for an action sheet, iOS human interface guidelines recommend that you do not use a title.

As described in iOS human interface guidelines, you should include a Cancel button with action sheets displayed on iPhone and with those displayed on iPad over an open popover. Otherwise on iPad, action sheets are displayed within a popover, and the user can cancel the action sheet by tapping outside the popover, in which case you do not need to include a Cancel button.

To create a Cancel button, pass a non-nil value for the cancelButtonTitle: parameter of the initWithTitle:delegate:cancelButtonTitle:destructiveButtonTitle:otherButtonTitles: method. A Cancel button created in this way is positioned at the bottom of the action sheet.

When your action sheet presents a potentially destructive choice, you should include a destructive button by passing a non-nil value for the destructiveButtonTitle: parameter of the initWithTitle:delegate:cancelButtonTitle:destructiveButtonTitle:otherButtonTitles: method. A destructive button created in this way is automatically colored red and positioned at the top of the action sheet.

Behavior of Action Sheets (Programmatic)

You can choose to present an action sheet so that it originates from a toolbar, tab bar, button bar item, from a view, or from a rectangle within a view. On iPhone, because the action sheet slides up from the bottom of a view and covers the width of the screen, most apps use showInView:. On iPad, however, action sheets appear within a popover whose arrow points to the control the user tapped to invoke the choices presented by the action sheet. So, showFromRect:inView:animated: and showFromBarButtonItem:animated: are most useful on iPad.

To handle the choices presented by your action sheet, you must designate a delegate to handle the button’s action, and the delegate must conform to the UIActionSheetDelegate protocol. You designate the delegate with the delegate parameter when you initialize the action sheet object. The delegate must implement the actionSheet:clickedButtonAtIndex: message to respond when the button is tapped. For example, the following code shows an implementation that simply logs the title of the button that was tapped.

  1. - (void)actionSheet:(UIActionSheet *)actionSheet clickedButtonAtIndex:(NSInteger)buttonIndex
  2. {
  3. NSLog(@"The %@ button was tapped.", [actionSheet buttonTitleAtIndex:buttonIndex]);
  4. }

Using Auto Layout with Action Sheets

The layout of action sheets is handled for you. You cannot create Auto Layout constraints between an action sheet and another user interface element.

For general information about using Auto Layout with iOS views, see Using Auto Layout with Views.

Making Action Sheets Accessible

Action sheets are accessible by default.

Accessibility for action sheets primarily concerns button titles. If VoiceOver is activated, it speaks the word “alert” when an action sheet is shown, then speaks its title if set (although iOS human interface guidelines recommend against titling action sheets). As the user taps a button in the action sheet, VoiceOver speaks its title and the word “button.”

For general information about making iOS views accessible, see Making Views Accessible.

Internationalizing Action Sheets

To internationalize an action sheet, you must provide localized translations of the button titles. Button size may change depending on the language and locale.

For more information, see Internationalization and Localization Guide.

Debugging Action Sheets

When debugging issues with action sheets, watch for this common pitfall:

Not testing localizations. Be sure to test the action sheets in your app with the localizations you intend to ship. In particular, button titles can truncate if they are longer in localizations other than the one in which you designed your user interface. Following the HI guideline to give buttons short, logical titles helps to ameliorate this potential problem, but localization testing is also required.

Elements Similar to an Action Sheet

The following elements provide similar functionality to an action sheet:

  • Alert View. Use an alert view to convey important information about an app or the device, interrupting the user and requiring them to stop what they’re doing to choose an action or dismiss the alert. For more information, see Alert Views.

  • Modal View. Use a modal view (that is, the view controller uses a modal presentation style) when users initiate a self-contained subtask in the context of their workflow or another task. For more information, see UIViewController Class Reference.