From 967c787b35c83c990f78bfab164585994fbab28e Mon Sep 17 00:00:00 2001
From: epenet <6771947+epenet@users.noreply.github.com>
Date: Wed, 30 Nov 2022 08:23:37 +0100
Subject: [PATCH] Document add_suggested_values_to_schema (#1541)

---
 docs/data_entry_flow_index.md | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/docs/data_entry_flow_index.md b/docs/data_entry_flow_index.md
index ea24687f..30a10742 100644
--- a/docs/data_entry_flow_index.md
+++ b/docs/data_entry_flow_index.md
@@ -230,6 +230,26 @@ The other alternative is to use a suggested value - this will also pre-fill the
 
 You can also mix and match - pre-fill through `suggested_value`, and use a different value for `default` in case the field is left empty, but that could be confusing to the user so use carefully.
 
+Using suggested values also make it possible to declare a static schema, and merge suggested values from existing input. A `add_suggested_values_to_schema` helper makes this possible:
+
+```python
+OPTIONS_SCHEMA = vol.Schema(
+    {
+        vol.Optional("field_name", default="default value"): str,
+    }
+)
+
+class ExampleOptionsFlow(config_entries.OptionsFlow):
+    async def async_step_init(
+        self, user_input: dict[str, Any] | None = None
+    ) -> FlowResult:
+        return self.async_show_form(
+            data_schema = self.add_suggested_values_to_schema(
+                OPTIONS_SCHEMA, self.entry.options
+            )
+        )
+```
+
 #### Validation
 
 After the user has filled in the form, the step method will be called again and the user input is passed in. Your step will only be called if the user input passes your data schema. When the user passes in data, you will have to do extra validation of the data. For example, you can verify that the passed in username and password are valid.