> For the complete documentation index, see [llms.txt](https://docs.notionapps.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.notionapps.com/screens-and-components/types-of-screens/form-update-one-item.md).

# Form (Update One Item)

The **Form (Update One Item)** screen edits an existing Notion record. It is usually opened from Details (**Allow Editing**) or from **List (Update Items)**.

{% hint style="info" %}
**Who this guide is for**\
Makers configuring edit forms. This guide covers Content/Behaviour options for Update Form, including how it differs from Create Form (no Public access, no section stepper).
{% endhint %}

## What the screen is for

### Use Form (Update One Item) when

* Users change fields on an existing record
* Details should stay read-focused while edit lives on a separate form
* You need after-save Actions or delete from the edit surface

### Do not use it when

* Users only create records: use **Form (Add Item)**
* Users only view: use **Details**
* Guests should submit new intake: use Create Form + Public access (Update Form has no public panel)

## What users see in the live app

* Editable fields for the open record
* Submit button (when editable comps exist) with placement settings
* Optional Delete (non-primary screens)
* Optional after-save Actions

## Add Form (Update One Item) in the builder

1. **Screens → + New Screen** → database → **Form (Update One Item)**.
2. Add editable fields under **Content → Logic**.
3. On Details, enable **Allow Editing → Go to Update Screen** pointing here.
4. Configure Save Button Text, Success Message, and Actions.
5. Publish and test edit→save→Notion sync.

![Builder configuration for this screen](https://4233028229-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ZqDXcVVffWUqEIZVhmn%2Fuploads%2FO1iu4lLVVukXcY7MiHMR%2Fdata-1786203151-35-00-builder-hero.jpg?alt=media)

![End-user preview of this screen](https://4233028229-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ZqDXcVVffWUqEIZVhmn%2Fuploads%2FdtFEtkzmOBQHVVNiegTW%2Fdata-1786203151-36-09-preview-closeup.jpg?alt=media)

## Complete Builder Options Reference

### Content tab

![Annotated builder screenshot: Content](https://4233028229-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ZqDXcVVffWUqEIZVhmn%2Fuploads%2FTiMPo9SCrO7FyYdlO0tj%2Fdata-1786203151-37-01-section-content.jpg?alt=media)

#### Logic

![Annotated builder screenshot: Logic](https://4233028229-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ZqDXcVVffWUqEIZVhmn%2Fuploads%2FUndcLsDrCMRoKYfzsCfl%2Fdata-1786203151-38-02-section-logic.jpg?alt=media)

**Field / component list**

**What it does:**\
Defines which properties users can edit (and read-only comps if included).

**How to use it:**\
Include fields users actually change. Hide system fields. Use visibility logic for role-specific edits.

**Why / recommended default:**\
Keep edit forms tighter than Details. A common mistake is allowing edits to fields that workflows own.

#### Filtering (primary only)

![Annotated builder screenshot: Filtering](https://4233028229-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ZqDXcVVffWUqEIZVhmn%2Fuploads%2FrugAB9UEjfNYhgIlkKt8%2Fdata-1786203151-39-03-section-filtering.jpg?alt=media)

**Filter rows**

**What it does:**\
Scopes records when this Update Form is used as a primary screen.

**How to use it:**\
Usually empty when opened from Details/List with context. Use when Update Form is a primary gated editor.

**Why / recommended default:**\
Empty for secondary edit forms.

### Behaviour tab

![Annotated builder screenshot: Behaviour](https://4233028229-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ZqDXcVVffWUqEIZVhmn%2Fuploads%2FakIkHSzrTMCBH2ump1gG%2Fdata-1786203151-40-04-section-behaviour.jpg?alt=media)

#### Save Button Text / positions / Success Message

![Annotated builder screenshot: Save Button Text](https://4233028229-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ZqDXcVVffWUqEIZVhmn%2Fuploads%2FCASP3MbnuuhJfqwFGwGP%2Fdata-1786203151-41-05-section-save-button-text.jpg?alt=media)

**What it does:**\
Submit chrome for saving changes. Hidden if the layout has no explicit editable comps.

**How to use it:**\
Label as “Save changes”. Match mobile/desktop placement to Create Form patterns your users already know.

**Why / recommended default:**\
Always provide a clear save label and success message.

#### Actions

![Annotated builder screenshot: Actions](https://4233028229-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ZqDXcVVffWUqEIZVhmn%2Fuploads%2F4SzoMuPxJ7FDdmmu2pGv%2Fdata-1786203151-42-06-section-actions.jpg?alt=media)

**Action Type / + Add Action**

**What it does:**\
After-save Change Data / Go to Screen / Open Link.

**How to use it:**\
Often Go to Screen back to Details or List after save.

**Why / recommended default:**\
Return users to the record they edited.

#### Allow Delete (non-primary)

![Annotated builder screenshot: Allow Delete](https://4233028229-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ZqDXcVVffWUqEIZVhmn%2Fuploads%2F4SzoMuPxJ7FDdmmu2pGv%2Fdata-1786203151-42-06-section-actions.jpg?alt=media)

**What it does:**\
Delete the current record from the edit form (with confirmation options).

**How to use it:**\
Enable only for trusted editors. Prefer confirmation on.

**Why / recommended default:**\
Off unless delete is a real product requirement.

#### Screen Visibility Logic (primary)

![Annotated builder screenshot: Screen Visibility Logic](https://4233028229-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5ZqDXcVVffWUqEIZVhmn%2Fuploads%2FncacbmvhwtrvjQiuoYLm%2Fdata-1786203151-43-08-section-screen-visibility-logic.jpg?alt=media)

**What it does:**\
Who can open the Update Form when it is primary.

**How to use it:**\
Restrict to roles that may edit. Secondary edit forms usually inherit access via Details navigation.

**Why / recommended default:**\
Unrestricted secondary; restrict if primary.

### Appearance tab

Empty — use field inspector + app theme.

### Differences from Create Form

| Option                         | Create Form | Update Form                            |
| ------------------------------ | ----------- | -------------------------------------- |
| Public access / Copy form link | Yes         | No                                     |
| Use sections as steps          | Yes         | No                                     |
| Filtering                      | Never       | Primary only                           |
| Delete                         | No          | Non-primary yes                        |
| URL default prefills           | Common      | Less common; still available per field |

### Field inspector highlights

* Is Required, Validate input
* Disable Changes (lock fields)
* Visibility When: current row vs user inputs
* Default Value (use carefully on updates)

## Recommended default setup

| Setting         | Recommended value     |
| --------------- | --------------------- |
| Opened from     | Details Allow Editing |
| Fields          | Editable subset only  |
| Success Message | “Changes saved”       |
| Actions         | Return to Details     |
| Delete          | Off                   |

## Testing checklist

* [ ] Details Edit opens this form with the same record
* [ ] Save writes to Notion
* [ ] Required/validation rules work
* [ ] Actions return to the expected screen
* [ ] Delete (if on) confirms correctly
* [ ] Role visibility works with `View as user`

## Troubleshooting

| Symptom              | Likely cause           | What to check                    |
| -------------------- | ---------------------- | -------------------------------- |
| No submit button     | No editable comps      | Logic fields                     |
| Opens blank          | Missing record context | Navigation from Details/List     |
| Public link expected | Wrong screen type      | Use Create Form for guest intake |

## Best practices

* Keep Update Form focused on mutable fields.
* Let workflows own status fields when automation sets them.
* Always provide a return path after save.