![](https://developer.android.com/static/images/design/ui/mobile/widgets/widget-configuration-4.png)

Configure your widget to display selected content or data from your app.

## When to use configuration

Let your user configure their widget either during widget selection or
through touch \& hold. Consider how crucial
customization is to your widget experience to decide when to make it available.

- If the widget appears empty without choosing settings or customization is central, directly open the configuration workflow during widget placement.
- If the widget has a preferred default or does not need the user to make a selection before viewing content, then your widget does not need an initial configuration screen. In these cases, let your user access configuration after placement.

## Direct users

We suggest that you provide a configuration step to provide a customizable and
glanceable experience for apps with multiple categories of content, such as an
email app.
![](https://developer.android.com/static/images/design/ui/mobile/widgets/widget-configuration-3.png) **Figure 1:** Let your users configure their widget and choose which folder to display.

## When to use configuration

Allow your user to configure their widget either between widget selection and
appearing on the home screen or through touch \& hold. Consider how crucial
customization is to your widget experience to decide when to make it available.

- If the widget appears empty without choosing settings or customization is central, directly open the configuration workflow during widget placement.
- If the widget has a preferred default or does not need the user to make a selection before viewing content, then your widget does not need an initial configuration screen. In these cases, let your user access configuration after placement.

## Direct users

Lead the user through configuration and provide clear feedback. If your app
already contains a configuration flow, you can mirror your in-app configuration
experience, ideally minimized for 1 to 2 screens.  
![](https://developer.android.com/static/images/design/ui/mobile/widgets/widget-configuration-2.png)  
check_circle

### Do

Provide a clear path though options that leads to adding a widget.

For example, the alarm configuration screen on the left only lets the user
select an alarm category, and then adds the widget. Tapping the category closes
the configuration step and adds the widget. If configuration is not completed,
don't cancel adding the widget. Provide a state to allow for restoring or
configuring within the widget.  
![](https://developer.android.com/static/images/design/ui/mobile/widgets/widget-configuration-1.png)  
cancel

### Don't

Lead users to a dead end or treat this step like in-app settings.

In this example, it isn't clear that closing the configuration view through the
**x** icon adds the widget, despite choosing content to display.

Include an empty state if there is no other preset available. The empty state
can show an onboarding or authentication reminder to make sure to direct users.

## Customize widget appearance

Provide a desirable default widget when possible to let users quickly get
started without customization or to help users understand how the widget
appears on their home screen.

Show a preview of the widget when customizing the widget appearance.
![](https://developer.android.com/static/images/design/ui/mobile/widgets/widget-configuration-5.png) **Figure 2:** A widget with a preview of the customization.

Use progressive disclosure for advanced controls to help users move quickly
through customization.
![](https://developer.android.com/static/images/design/ui/mobile/widgets/widget-configuration-6.png) **Figure 3:** Show a size slider after the user selects custom size.

## Variations

For widgets with limited customization, display popular or distinct
configurations directly in the widget picker. This avoids the need for a
separate configuration screen.

Apps can support an unlimited number of widgets. However, the widget picker must
focus on showcasing only critical tasks and helpful variations. Limit picker
previews to 6-8 variations. Allow access to additional variations through a
confirmation screen.  
![](https://developer.android.com/static/images/design/ui/mobile/widgets/Variation_do.png)  
check_circle

### Do

Provide distinct widget use cases with configurable options, such as a steps widget and a streak widget.  
![](https://developer.android.com/static/images/design/ui/mobile/widgets/Variation_dont.png)  
cancel

### Don't

Display all possible variations in the picker. Instead, display these as configuration options.

## Layout

Follow [Layout basics](https://developer.android.com/design/ui/mobile/guides/layout-and-content/layout-basics) best practices or take advantage of [Material Design
components](https://developer.android.com/design/ui/mobile/guides/components/material-overview), such as list layouts with switches, checkboxes, and toggle
buttons, when building your configuration screen. For more information on making
your widget layout high quality, see [Widget quality](https://developer.android.com/docs/quality-guidelines/widget-quality).