feat: allow custom fields to set UI state during onChange

measuredco · Nov 22, 2023 · 388793c · 388793c
1 parent ca9284f
commit 388793c
Show file tree

Hide file tree

Showing 2 changed files with 53 additions and 9 deletions.
diff --git a/apps/docs/pages/docs/api-reference/configuration/fields/custom.mdx b/apps/docs/pages/docs/api-reference/configuration/fields/custom.mdx
@@ -126,13 +126,22 @@ const config = {
 
 #### `params`
 
-| Param             | Example                    | Type     |
-| ----------------- | -------------------------- | -------- |
-| `field`           | `{ type: "custom" }`       | Object   |
-| `id`              | `id`                       | String   |
-| `name`            | `"title"`                  | String   |
-| `onChange(value)` | `onChange("Hello, world")` | Function |
-| `value`           | `"Hello, world"`           | Any      |
+| Param                 | Example                    | Type     |
+| --------------------- | -------------------------- | -------- |
+| `field`               | `{ type: "custom" }`       | Object   |
+| `id`                  | `id`                       | String   |
+| `name`                | `"title"`                  | String   |
+| `onChange(value, ui)` | `onChange("Hello, world")` | Function |
+| `value`               | `"Hello, world"`           | Any      |
+
+##### onChange(value, [ui])
+
+Set the value of the field and optionally update the [Puck UI state](/docs/api-reference/app-state#ui).
+
+| Param   | Example                       | Type                                        | Status   |
+| ------- | ----------------------------- | ------------------------------------------- | -------- |
+| `value` | `"Hello, world"`              | Any                                         | Required |
+| `ui`    | `{leftSideBarVisible: false}` | [UiState](/docs/api-reference/app-state#ui) |          |
 
 ## Further reading
 

diff --git a/apps/docs/pages/docs/extending-puck/custom-fields.mdx b/apps/docs/pages/docs/extending-puck/custom-fields.mdx
@@ -34,7 +34,7 @@ const config = {
 };
 ```
 
-The `onChange` function updates the Puck data payload for the field name, in this case "title".
+The [`onChange` function](/docs/api-reference/configuration/fields/custom#onchangevalue-ui) updates the Puck data payload for the field name, in this case "title".
 
 <ConfigPreview
   label="Example"
@@ -128,6 +128,41 @@ const config = {
   }}
 />
 
+## Updating the UI state
+
+The [`onChange` function](/docs/api-reference/configuration/fields/custom#onchangevalue-ui) can also be used to modify the [Puck UI state](/docs/api-reference/app-state#ui) at the same time as updating the field value:
+
+```tsx copy showLineNumbers {14,15}
+const config = {
+  components: {
+    Example: {
+      fields: {
+        title: {
+          type: "custom",
+          render: ({ name, onChange, value }) => (
+            <input
+              defaultValue={value}
+              name={name}
+              onChange={(e) =>
+                onChange(
+                  e.currentTarget.value,
+                  // Close the left side bar when this field is changed
+                  { leftSideBarVisible: false }
+                )
+              }
+              style={{ border: "1px solid black", padding: 4 }}
+            />
+          ),
+        },
+      },
+      render: ({ title }) => {
+        return <p>{title}</p>;
+      },
+    },
+  },
+};
+```
+
 ## Further reading
 
-- [The `custom` field API reference](/docs/api-reference/configuration/fields/custom):
+- [The `custom` field API reference](/docs/api-reference/configuration/fields/custom)