Guides and Sample Code


App Programming Guide for watchOS


Use a picker to display a list of items, letting the user select one item from the list. Watch apps supports single-column pickers using the WKInterfacePicker class. The picker displays images alone or a combination of images and text. Activating a picker lets the user scroll through the items using the Digital Crown.

WKInterfacePickerThe picker’s appearance is determined mostly by the items it displays. The style of the picker defines how the picker displays its contents and how it animates between items during scrolling. Figure 12-1 illustrates a picker that uses the list style, where items appear to be on the surface of a rotating wheel. Other styles display only images and offer different options for animating from one image to the next.

Figure 12-1A picker using the list style image: ../Art/picker_rainbow_list_2x.png

You can include multiple pickers on a single screen and configure the size and other attributes of the picker to suit the needs of your layout. When displaying images, you typically want to size the picker to match the size of the images.

To add a picker to your app’s interface, drag the picker object into your storyboard scene. Configure the picker style in your storyboard and create an outlet to the picker in your corresponding interface controller. You must have an outlet for your picker because you configure the picker’s contents programmatically. There are two attributes of a picker that you configure in your WatchKit extension:

  • Picker items. Use the setItems: method to specify the contents of the picker. Each item is an instance of the WKPickerItem class that contains the text or images you want to display in the picker interface.

  • Coordinated interface objects. For sophisticated picker interfaces, you can link the picker to one or more WKInterfaceImage or WKInterfaceGroup objects that contain animated image sequences. As the user turns the Digital Crown to select the next picker item, the picker updates the displayed image in each coordinated object.

Linking interface objects to the picker lets you created synchronized animations for your interface. As the user turns the Digital Crown, the picker updates its own content and the content of any coordinated objects at the same time. This behavior lets you create interfaces like the one shown in Figure 12-2. In the example, a picker is embedded inside a group object whose background contains an animated image showing an expanding circular ring. The picker contains images of completion percentage values and uses the group as a coordinated interface object. When the user turns the Digital Crown, the percentage value in the picker and circular ring image in the group update at the same time.

Figure 12-2Coordinating animations with the picker contents image: ../Art/picker_coordinated_animations_2x.png

Each time the picker value changes, the WKInterfacePicker object reports the change to its associated action method. The format of this action method is as follows:


  1. - (IBAction)pickerAction:(NSInteger)index


  1. @IBAction func pickerAction(index: Int)

You can use the action method’s index value to obtain the selected item from the array of items you used to configure the picker. The picker reports every change to its action method, regardless of how fast the user turns the Digital Crown. If your app should respond only to the item that the user selected, use the pickerDidSettle: method of WKInterfaceController to get the selected item instead.

For more information about how to configure and use a WKInterfacePicker object, see WKInterfacePicker Class Reference.