Adding Interactive Controls to a Long-Look Interface

Define a dynamic notification controller that responds to user interactions on watchOS.


In watchOS 5 and later, you can define a dynamic interactive notification controller for a notification category. The dynamic interactive notification controllers support interactive UI elements, such as buttons or switches, which you can connect to action methods in your notification controller class.

The dynamic interactive interfaces and actionable notifications both let users interact directly with notifications; however, they play somewhat different roles. Action methods perform tasks within the notification controller, while notification actions pass control back to your app.

Dynamic interactive interfaces use the target-action design pattern to connect UI elements in the storyboard to your notification controller’s action methods. You typically use action methods to update your notification’s appearance. For example, when the user taps a button, the system calls the button’s action method. You can use this method to show or hide additional information within the notification.

An actionable notification, on the other hand, has one or more actions associated with it. The system displays a button for each action beneath the notification. When tapped, these buttons dismiss the notification, and the system passes control back to either your iOS or watchOS app. By default, your app handles these actions in the background; however, you can configure notifications to launch your app to the foreground. For more information, see Adding Actions to Notifications on watchOS.

Add the Interface to Your WatchKit Storyboard

To add a dynamic interactive interface, select your WatchKit app’s storyboard in the Project navigator. If your storyboard does not already have a notification interface controller, click the Add button (+) in the toolbar, and drag a Notification Interface Controller onto the canvas.

A screenshot showing the Notification Interface Controller in the Object Library.

Dragging out the notification controller adds a static interface to the storyboard.

A screenshot showing the static notification interface controller in the storyboard.

Next, in the document outline, select the static interface’s Notification Category.

A screenshot showing the Notification Category in the document outline.

In the Attributes inspector, make sure to select both the Has Dynamic Interface and the Has Interactive Interface attributes. You can also customize the notification category name by editing the value in the Name field.

A screenshot showing the required attributes for enabling an interactive controller.

Checking the Has Dynamic Interface and Has Interactive Interface attributes adds the corresponding scenes to the storyboard.

A screenshot showing the dynamic interactive interface on the storyboard canvas.

In watchOS 5 and later, if the app has a dynamic interactive interface, the system loads the interactive interface instead of the dynamic interface; however, you need both interfaces if you plan to support watchOS 4 and earlier.

For more information on handling notifications in watchOS, see Adding Notifications to Your watchOS App.

Configure the Interface

After adding the dynamic interactive interface to your storyboard, you must configure it before you can attach its controls to actions. Start by selecting the Dynamic Interactive Notification Controller. In the Identity inspector, set the notification controller’s class.

A screenshot showing the Identity inspector, with the NotificationController class set.

You can now add interactive elements like buttons or switches to the dynamic interactive interface, and draw connections between the interactive controls and action methods in your notification controller.

A screenshot showing the connection between a button in the storyboard and an action method in the navigation controller class.

Action methods can perform the following tasks:

In general, keep your action methods simple. Complex, multi-step tasks are not a good fit for interactive notifications.

See Also

Custom Interfaces and Actions

Customizing Your Long-Look Interface

Create custom interfaces for your watchOS app’s notifications.

Adding Actions to Notifications on watchOS

Use actionable notifications to provide a set of responses for the notification.