diff --git a/docs/config_entries_config_flow_handler.md b/docs/config_entries_config_flow_handler.md index 20d3b2ba..d63cb59e 100644 --- a/docs/config_entries_config_flow_handler.md +++ b/docs/config_entries_config_flow_handler.md @@ -31,6 +31,21 @@ class ExampleConfigFlow(config_entries.ConfigFlow, domain=DOMAIN): Once you have updated your manifest and created the `config_flow.py`, you will need to run `python3 -m script.hassfest` (one time only) for Home Assistant to activate the config entry for your integration. +## Config flow title + +The title of a config flow can be influenced by integrations, and is determined in this priority order: + +1. If `title_placeholders` is set to a non-empty dictionary in the config flow, it will be used to dynamically calculate the config flow's title. Reauth and reconfigure flows automatically set `title_placeholders` to `{"name": config_entry_title}`. + 1. If the integration provides a localized `flow_title`, that will be used, with any translation placeholders substituted from the `title_placeholders`. + 2. If the integration does not provide a `flow_title` but the `title_placeholders` includes a `name`, the `name` will be used as the flow's title. +2. Set the flow title to the integration's localized `title`, if it exists. +3. Set the flow title to the integration manifest's `name`, if it exists. +4. Set the flow title to the integration's domain. + +Note that this priority order means that: +- A localized `flow_title` is ignored if the `title_placeholders` dictionary is missing or empty, even if the localized `flow_title` does not have any placeholders +- If `title_placeholders` is not empty, but there's no localized `flow_title` and the `title_placeholders` does not include a `name`, it is ignored. + ## Defining steps Your config flow will need to define steps of your configuration flow. Each step is identified by a unique step name (`step_id`). The step callback methods follow the pattern `async_step_`. The docs for [Data Entry Flow](data_entry_flow_index.md) describe the different return values of a step. Here is an example of how to define the `user` step: