---
title: Form widget
description: "Use the **Form widget** to let users create and edit an object by filling in fields. ## What a Form widget actually is The Form widget is the [Text Grid widget](/documentation/text-grid-widget/) in form mode. Selecting the **Form** tile in the…"
url: "https://auclio.com/documentation/form-widget/"
updated: "2026-10-15"
category: Widgets
---

# Form widget

Use the **Form widget** to let users create and edit an object by filling in fields.

## What a Form widget actually is

The Form widget is the [Text Grid widget](/documentation/text-grid-widget/) in form mode. Selecting the **Form** tile in the widget palette opens the same configuration dialog with editing turned on and one extra step, and the result is stored as a Text Grid.

That matters in two practical ways:

- everything in [Text Grid widget](/documentation/text-grid-widget/) about items, binding, and layout applies here unchanged;
- a widget created as a Form appears as a Text Grid in the widget list.

This page covers what is different in form mode.

## When to use it

Use a Form widget when users need to supply values rather than read them:

- a `Create new account` page, where users add an object from scratch;
- an edit page for one object, where a table row would be too cramped;
- a request or submission page for users who never see the underlying dataset.

Where users need to add many objects quickly, a Table widget with **Add Row** enabled is faster, because it keeps them on the list.

## Add a Form widget

To add a Form widget:

1. Open the page and enable **Layout edit mode**.
2. Select **Add a widget**.
3. Select the **Form** tile, or drag it onto the page.
4. Work through the five configuration steps.
5. Select **Create**.
6. Save the page layout.

The steps are **Widget**, **Fields**, **Properties**, **File Settings**, and **Submit Button**. The first four behave as they do for a Text Grid, except that items are called fields: the buttons read **Add Field** and **Save Field**, and the label field reads **Field Label**.

Two differences beyond the naming. A field offers no **Link Configuration** section, because a form is for entering values rather than following them. And the Properties step shows no editing pencil, because every field on a form is editable.

## Step 2: Fields

Fields are configured exactly like Text Grid items - each names an **Object**, which is a page parameter, and a **Property** of that parameter's dataset. **Boolean Field Input Type**, **Enable create new object**, **Control**, and **Add multiple fields at once** all work as they do for a Text Grid.

One switch is specific to form mode: **Auto-populate fields from page parameters**.

- Switch it on when the form edits an existing object. The fields open filled with that object's current values.
- Leave it off when the form creates a new object. The fields open empty. This is the default.

A create form that auto-populates shows the values of whatever object the parameter happens to hold; an edit form that does not populate looks blank and quietly overwrites values with nothing.

### Required properties that are not on the form

Auclio validates the whole object on the server, not just the fields you have shown. If the dataset marks a property as required and the submitted object does not carry it, the save is refused and the response names the missing properties.

Put every required property on the form.

## Step 5: Submit Button

This step exists only in form mode.

- **Button Text** - the label, for example `Submit request`. It is required.
- the icon preview, which opens **Select an Icon**, and **Icon Position** - an optional icon, placed **Left** or **Right** of the text.
- **Button Style** - the colour, from **Default**, **Primary**, **Secondary**, **Success**, **Warning**, and **Error**. This is the Button widget's set without **Info**.
- **On Submit Behavior** - what happens after the form is submitted:
  - **Do Nothing** - the form stays as it is;
  - **Refresh Form** - the form reloads, clearing it ready for the next entry;
  - **Execute Actions** - the configured actions run, which is the only setting under which the button can navigate.

Choose **Execute Actions** and three more controls appear. **Link to** decides where the user goes: choose **Url** and enter an address in **Url**, or **Page** and pick the destination in **Select Page**. An icon toggle beside them controls whether the destination opens in a new tab, and its tooltip reads **Open link in new tab** or **Do not open link in new tab**.

Pair these deliberately. A create form used repeatedly wants **Refresh Form**, which needs no destination. A create form used once wants **Execute Actions** with a **Link to** destination, so the user lands on the new object or back on the list.

## Recommendations

When configuring a Form widget:

- decide first whether the form creates or edits, and set **Auto-populate fields from page parameters** to match;
- include every required property the dataset defines, since the server checks all of them;
- order the fields the way a person would fill them in, not the order the dataset lists them;
- label fields in the users' language;
- use **Refresh Form** for repeated entry, and **Execute Actions** with a destination for one-off entry;
- tell users where they will end up - a button reading `Submit` that navigates away is a surprise;
- test as a non-administrator, since creating an object needs Create cascading from the dataset’s **Children** slot.

See [Configure permissions](/documentation/configure-permissions/) for detailed instructions on granting the access a form needs.