Set up from the UI with a 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 in building integrations.

The integration must be set up from the UI, with a config flow. The flow must be easy to understand: the right selectors 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.

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.

Set config_flow to true in manifest.json, and add a config_flow.py with a class that extends ConfigFlow. Config flow shows a complete example, and the tutorial 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:

{
  "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 and unique-config-entry.

• 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.

Integrations that ADR-0010 exempts from UI setup are exempt from this rule.

• test-before-configure: test the connection in the config flow.
• unique-config-entry: prevent duplicate config entries.
• config-flow-test-coverage: test the config flow fully.
• discovery: support discovery.
• reauthentication-flow: reauthenticate from the UI.
• reconfiguration-flow: reconfigure from the UI.