Dashboard Widgets

Dashboard gives people a way to get information and perform simple tasks quickly and easily, without leaving the context of the current app. Appearing and disappearing with a single keystroke or gesture, Dashboard presents a default or user-defined set of mini apps, known as widgets. The system includes a variety of predefined widgets including a calculator, calendar, clock, and weather forecaster. Your app can implement custom widgets that expose app-specific content or functionality.

Screenshot of Dashboard with several widgets, such as the clock, calculator, and weather forecaster.

Consider developing a Notification Center widget instead of a Dashboard widget. In general, users expect to find widgets in the Today pane of Notification Center. See Notification Center Widgets.

Design a small, visually appealing, narrowly-focused widget. People use widgets to get brief updates and perform very simple tasks, so it’s essential to deliver the right amount of information and functionality.

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.

Design widgets for small screens. Device screen sizes vary and people keep multiple widgets open in Dashboard, so don’t monopolize screen space. People may leave your widget out of their Dashboard if there’s not enough room for other widgets.

Minimize the use of scroll bars. Generally, a widget should display minimal information that doesn’t require scrolling. If a widget, such as a dictionary, must provide lots of information, a scroll bar may be justified to keep the widget small.

Use color to distinguish your widget. A unique color scheme ensures that your widget is recognized quickly when Dashboard comes into view.

Avoid garish color schemes. The colors in your app should work well together, not conflict or distract. Varying shades of the same color tend to work well in widgets, rather than using multiple distinct colors.

Use clear, readable fonts. People expect to obtain information quickly from widgets. Avoid sacrificing readability to achieve a particular appearance. Remember that the standard system font, San Francisco, is optimized for legibility. See Typography.

Design custom controls. Standard system-provided controls should only be used for the back side of your widget, where preferences are displayed (see Widget Preferences).

Make sure custom controls look and behave like the elements they represent. A checkbox should still look like a checkbox and buttons should still look clickable, for example.

Avoid advertising. Branding a widget is acceptable and important, but advertising takes away valuable space from content. Presence on a user’s Dashboard is a privilege. Use the back of the widget for information that isn’t vital to the widget’s purpose, such as branding, licensing information, and copyright notices.

Position your widget’s Close button over the top left of your widget. The default location of the Close button may appear to be floating off to the side of a widget with transparency around its edges. If this is the case with your widget, reposition the button so that it’s located over the widget itself and isn't disconnected.

Support clipboard interaction whenever possible. People often expect to be able to copy and paste content between apps and widgets.

For developer guidance, see Dashboard Programming Topics.

Widget Preferences

If your widget requires configuration, you can display preferences on the back of your widget.

Screenshot of the front of the Weather widget, showing the current temperature and a six-day forecast.

Widget front

Screenshot of the back of the Weather widget, showing the location text field and a control for choosing Fahrenheit or Celsius.

Widget back

Provide an info button on the front of your widget that alludes to configurable preferences. An info button typically appears in the lower-right corner of the widget. Some widgets hide this button by default, and only display it when the pointer is positioned over the widget. This button should use the standard info button style, which appears as an “i” character enclosed within a circle. Imagery for this button is found in /System/Library/WidgetResources/.

Use the back of your widget strictly for exposing preferences or useful information. All core functionality should be on the front of your widget.

Use a flip animation only for revealing the back of your widget. People expect to see this animation when accessing a widget’s preferences. They don’t expect to see it used for other purposes.

Use standard system controls on the back of your widget. Standard controls are expected and relevant when configuring preferences. To keep widget sizes to a minimum, small-sized controls are preferred.

Provide a Done button. Clicking the Done button should commit the user’s changes and flip the widget back over to reveal its front side. Imagery for this button is found in /System/Library/WidgetResources/. Be sure to update the front of the widget promptly to reflect any preference changes.

Use a dark or subdued background color for your widget’s back. Reusing the background color from the front of your widget is not advised because it leads to confusion about which side is the front.

If necessary, show licensing information, logos, and minimal help information on the back of your widget. Avoid excessive branding and advertising.

Use standard artwork for the buttons and controls on the back of your widget. See the resources available in /System/Library/WidgetResources/.