# Set up from the UI with a config flow

> Bronze rule config-flow: the integration is set up from the UI, with a clear config flow that stores its data in the right place.

Source: https://contributors.home-assistant.io/core/quality-scale/config-flow/

This is a Bronze rule. In `quality_scale.yaml`, it is called `config-flow`.

This page is about what the rule requires, and how it is checked. How to build a config flow, step by step, is on [config flow](https://contributors.home-assistant.io/core/integrations/config-flow/) in building integrations.

The integration must be set up from the UI, with a [config flow](https://contributors.home-assistant.io/glossary/config-flow/). The flow must be easy to understand: the right [selectors](https://contributors.home-assistant.io/glossary/selector/) for each field, validation where it is needed, and a `data_description` in `strings.json` that explains every field. Store what is needed to connect in `ConfigEntry.data`, and settings that are not needed to connect in `ConfigEntry.options`.

## Why it matters

Since 2018, the config flow has been the standard way to set up an integration. It gives every integration the same setup experience, guides users through the steps, and means nobody has to edit YAML to get started. The config flow is the first thing a user sees of your integration, so it should be clear and friendly.

Keeping connection data and options apart lets users change options later in an options flow, without touching the connection.

## Example

Set `config_flow` to `true` in `manifest.json`, and add a `config_flow.py` with a class that extends `ConfigFlow`. [Config flow](https://contributors.home-assistant.io/core/integrations/config-flow/#add-a-config-flow) shows a complete example, and the [tutorial](https://contributors.home-assistant.io/core/integrations/tutorial/#4-build-the-config-flow) builds one from the scaffold.

The text of the form lives in `strings.json`. Give every field a label in `data` and an explanation in `data_description`:

```json
{
  "config": {
    "step": {
      "user": {
        "data": {
          "host": "[%key:common::config_flow::data::host%]"
        },
        "data_description": {
          "host": "The hostname or IP address of your device."
        }
      }
    }
  }
}
```

A real config flow also tests the connection and prevents duplicates. Those are rules of their own: [test-before-configure](https://contributors.home-assistant.io/core/quality-scale/test-before-configure/) and [unique-config-entry](https://contributors.home-assistant.io/core/quality-scale/unique-config-entry/).

## How it is checked

- Hassfest, when the rule is `done`: `config_flow` must be `true` in `manifest.json`, and `config_flow.py` must exist.
- Pylint warns when a config flow asks for a name (`home-assistant-config-flow-name-field`) or a polling interval (`home-assistant-config-flow-polling-field`). Names come from the device, and the polling interval is up to the integration.
- Pylint warns when a field of a config, options, or subentry flow has no translation in `strings.json` (`home-assistant-config-flow-field-not-translated` and its siblings).
- The use of selectors, `data_description`, and `data` versus `options` is checked in review.

## Exceptions

Integrations that [ADR-0010](https://github.com/home-assistant/architecture/blob/master/adr/0010-integration-configuration.md) exempts from UI setup are exempt from this rule.

## Related rules

- [test-before-configure](https://contributors.home-assistant.io/core/quality-scale/test-before-configure/): test the connection in the config flow.
- [unique-config-entry](https://contributors.home-assistant.io/core/quality-scale/unique-config-entry/): prevent duplicate config entries.
- [config-flow-test-coverage](https://contributors.home-assistant.io/core/quality-scale/config-flow-test-coverage/): test the config flow fully.
- [discovery](https://contributors.home-assistant.io/core/quality-scale/discovery/): support discovery.
- [reauthentication-flow](https://contributors.home-assistant.io/core/quality-scale/reauthentication-flow/): reauthenticate from the UI.
- [reconfiguration-flow](https://contributors.home-assistant.io/core/quality-scale/reconfiguration-flow/): reconfigure from the UI.