Widgets

A widget is an extension that displays a small amount of timely, useful information or app-specific functionality. For example, the News widget shows top headlines. Calendar provides two widgets, one that shows today’s events and one that shows what’s up next. Notes lets you preview recent notes and quickly create new notes, reminders, photos, and drawings. Widgets are highly customizable and can contain buttons, text, layout customizations, images, and more.

Widgets appear above the quick action list when you apply pressure to an app icon on the Home screen using 3D Touch. People also add the widgets they care about to the Search screen, which is accessed by swiping to the right on the Home screen and the Lock screen. Your goal should be to design a widget that people want to add to the Search screen.

Design a great glanceable experience. People use widgets to get brief updates and perform very simple tasks, so it’s essential to deliver the right amount of information and interactivity. Wherever possible, provide tasks that can be completed in a single tap. Panning and scrolling within widgets isn’t supported.

Show content quickly. People spend very little time looking at widgets and shouldn’t need to wait for content to load. Cache information locally so you can always show recent information while getting updates.

Provide ample margins and padding. Avoid extending content to the edges of a widget. In general, provide a margin of at least a few pixels between each edge and the content. Use the app icon at the top of your widget for alignment guidance. Content tends to work well when lined up with the center of this icon. If your app offers a grid-style layout, make sure you provide sufficient and equal padding between grid items. If possible, limit grids of icons and buttons to four per row.

Be adaptable. The width of a widget varies, depending on the device and orientation. The height and information displayed by a widget depends on whether it’s collapsed or expanded (not all widgets support expansion). A collapsed widget is the height of roughly two and a half table rows. An expanded widget is ideally no taller than the height of the screen. The quick action list only shows widgets in a collapsed state. When collapsed, a widget shows essential information that can stand alone. When expanded, a widget shows additional information that enhances the primary information. The Weather widget, for example, shows the current weather conditions when collapsed, but adds the hourly forecast when expanded.

Avoid customizing the background of a widget. The light, blurred widget background provided by the system is designed for consistency and legibility. Use it whenever possible. Never use a photo as a background, as it may clash with the Lock and Home screen wallpaper.

In general, use the system font in black or dark gray for text. The system font is designed for legibility, and dark colors work well with the standard widget background.

When appropriate, let people jump to your app to do more. Your widget should operate independently from your app. However, if people might occasionally need to do more than what your widget offers, make it easy to do so. Don’t include an “Open App” button that takes space away from your content. Instead, let people tap the content itself to see or edit it in your app. In the Calendar widget, for example, you can tap an event to open it in the Calendar app. Never use your widget to open other apps.

Pick a good widget name. An app icon and a title appear above each widget’s content. In general, your widget’s name should match your app’s name. If your app offers multiple widgets, consider using your app name for the primary one and clear, concise names for the others. If you use custom titles, consider prefixing them with your app name. For example, the Maps widget for showing nearby locations is titled Maps Nearby. The inclusion of your app name instills confidence that the widget is in fact provided by your app.

Let people know when authentication adds value. If your widget provides additional functionality when someone is logged into your app, make sure people know about this. For example, an app that shows upcoming reservations might include a message that says “Sign into the app to view your reservations.” when people aren’t logged in.

Choose a widget for the quick action list. If your app has multiple widgets, pick one to appear in the quick action menu that appears when someone applies pressure to your app icon on the Home screen using 3D Touch.

For implementation details, see App Extension Programming Guide.