The Form component for Retool Apps

A form to group and submit input fields.

Version: Cloud and 3.234 Edge

Form can automatically generate input fields from a database or Table component, and populate nested input field values using default data.

Demo

For more information about using the Form component, refer to the forms guide.

Properties

All properties for this object with supported data types or values. You can write JavaScript almost anywhere in Retool to manipulate or read property values.

data

The data.

Type	string | number | boolean | object | array
Format	Custom data
Configurability	Inspector

---

disabled

Whether input, interaction, selection, or triggering is disabled.

Type	boolean
Format	True/False
Configurability	Inspector > Interaction > Disabled
Default	false

Examples

true

---

disableSubmit

Whether to disable form submission.

Type	boolean
Configurability	Inspector

---

enableFullBleed

Whether to expand the contents to fill available space.

Type	boolean
Format	True/False
Configurability	Inspector > Appearance > Expand contents to fit
Default	false

Examples

true

---

events

A list of configured event handlers that trigger actions or queries.

Type	array
Array values	object
Configurability	Inspector > Interaction > Event handlers

Array Object Properties

event

The event that triggers the action. Refer to the events section for details of available events for this object.

Type	string
Configurability	Inspector > Interaction > Event handlers > Event

---

method

The JavaScript method to perform when type is datasource, widget, state, or localStorage.

Type	string
Configurability	Inspector > Interaction > Event handlers > Edit event handler > Run script actions

---

type

The type of action to perform.

Type	string
Configurability	Inspector > Interaction > Event handlers > Edit event handler > Action
Allowed Values	Value Description datasource Control query. widget Control component. script Run script. state Set variable. localStorage Set localStorage. util Perform utility action (e.g., Open URL or Confetti).

---

---

footerPadding

The amount of padding used within the footer.

Type	string
Format	Plain Text
Configurability	Inspector > Content > Add-ons > Footer > Padding
Allowed Values	Value UI Option Description 8px 12px Normal 8px top and bottom, 12px left and right. 0 None No padding.
Default	8px 12px

Examples

"8px 12px"

---

headerPadding

The amount of padding used within the header.

Type	string
Format	Plain Text
Configurability	Inspector > Content > Add-ons > Header > Padding
Allowed Values	Value UI Option Description 8px 12px Normal 8px top and bottom, 12px left and right. 0 None No padding.
Default	8px 12px

Examples

"8px 12px"

---

hoistFetching

Whether to display a loading indicator whenever nested objects are fetching data.

Type	boolean
Format	True/False
Configurability	Inspector > Interaction > Hoist loading state
Default	false

Examples

true

---

id

The unique identifier (name).

Type	string
Format	Plain Text
Configurability	Inspector
Default	form1

Examples

query1

button1

---

initialData

The data used to populate default values for input fields.

Type	array
Array values	object
Configurability	Read-only

---

invalid

Whether the value has failed any validation rules.

Type	boolean
Configurability	Read-only

---

isHiddenOnDesktop

Whether to show or hide this object in the desktop layout.

Type	boolean
Format	True/False
Configurability	Inspector > Appearance > Advanced > Show on desktop
Default	false

Examples

true

---

isHiddenOnMobile

Whether to show or hide this object in the mobile layout.

Type	boolean
Format	True/False
Configurability	Inspector > Appearance > Advanced > Show on mobile
Default	true

Examples

true

---

loading

Whether to display a loading indicator.

Type	boolean
Format	True/False
Configurability	Inspector > Interaction > Loading
Default	false

Examples

true

---

maintainSpaceWhenHidden

Whether to take up space on the canvas if hidden is true.

Type	boolean
Format	True/False
Configurability	Inspector > Appearance > Advanced > Maintain space when hidden
Default	false

Examples

true

---

margin

The amount of margin to render outside.

Type	string
Format	Plain Text
Configurability	Inspector > Spacing > Margin
Allowed Values	Value UI Option Description 4px 8px Normal Normal margin. 0 None No margin.
Default	4px 8px

Examples

4px 8px

---

padding

The amount of padding to render inside.

Type	string
Format	Plain Text
Configurability	Inspector > Spacing > Padding
Allowed Values	Value Description 4px 8px Normal padding. 0 No padding.
Default	4px 8px

Examples

4px 8px

---

requireValidation

Whether all input fields must be valid to submit. If valid is false for any input field, the Invalid event handler is triggered.

Type	boolean
Configurability	Read-only

---

resetAfterSubmit

Whether to reset input field values using initialData after form submission.

Type	boolean
Configurability	Read-only

---

showBody

Whether to show the body.

Type	boolean
Configurability	Read-only

---

showBorder

Whether to show a border.

Type	boolean
Format	True/False
Configurability	Inspector > Appearance > Show border
Default	false

Examples

true

---

showFooter

Whether to show the footer area.

Type	boolean
Configurability	Inspector

---

showFooterBorder

Whether to show a border above the footer.

Type	boolean
Format	True/False
Configurability	Inspector > Content > Add-ons > Footer > Appearance > Show separator

Examples

true

---

showHeader

Whether to show the header area.

Type	boolean
Format	True/False
Configurability	Inspector > Content > Add-ons > Header > Appearance > Show header
Default	false

Examples

true

---

showHeaderBorder

Whether to show a border under the header.

Type	boolean
Format	True/False
Configurability	Inspector > Content > Add-ons > Header > Appearance > Show separator
Default	true

Examples

true

---

showInEditor

Whether the component remains visible in the editor if hidden is true.

Type	boolean
Format	True/False
Configurability	Inspector > Appearance > Advanced > Always show in edit mode
Default	false

Examples

true

---

style

Custom style options.

Type	object
Configurability	Inspector > Appearance > style

---

submitting

Whether the Submit event handler is running.

Type	boolean
Configurability	Read-only

---

tooltipText

The tooltip text to display next to the label on hover.

Type	string
Format	Markdown
Configurability	Inspector > Content > Add-ons > Helper text
Default	null

Examples

Submit

---

Methods

JavaScript API methods for this object. You can write JavaScript almost anywhere in Retool and use methods to manipulate data and property values.

form.clear()

A value is cleared.

Definition

form.clear()

Examples

Clear the value of form.

form.clear();

---

form.clearValidation()

Clear the validation message from the input field.

Definition

form.clearValidation()

Examples

Clear the validation message from form.

form.clearValidation();

---

form.reset()

Reset all child inputs to default values or clears them if no default values are set.

Definition

form.reset()

Examples

Reset form.

form.reset();

---

form.setData()

Set child input values.

Definition

form.setData(data)

Parameters

data

The data.

Type	string | number | boolean | object | array
Format	Custom data

---

---

form.setDisabled()

Set the disabled value to toggle whether the input field is disabled. Defaults to true without a parameter.

Definition

form.setDisabled(disabled)

Parameters

disabled

Whether input, interaction, selection, or triggering is disabled.

Type	boolean
Format	True/False
Default	false

Examples

true

---

Examples

Disable form.

form.setDisabled(true);

Enable form.

form.setDisabled(false);

---

form.setHidden()

Set the hidden value to toggle whether the component is visible. Defaults to true without a parameter.

Definition

form.setHidden(hidden)

Parameters

hidden

Whether this object is hidden from view.

Type	boolean
Format	True/False
Default	false

Examples

true

---

Examples

Hide form.

form.setHidden(true);

Unhide form.

form.setHidden(false);

---

form.setShowBody()

Set the showBody value to toggle whether the component body is visible.

Definition

form.setShowBody(showBody)

Parameters

showBody

Whether to show the body.

Type

boolean

---

Examples

Show the body of form.

form.setShowBody(true);

Hide the body of form.

form.setShowBody(false);

---

form.setShowFooter()

Set the showFooter value to toggle whether the component footer is visible.

Definition

form.setShowFooter(showFooter)

Parameters

showFooter

Whether to show the footer area.

Type

boolean

---

Examples

Show the footer of form.

form.setShowFooter(true);

Hide the footer of form.

form.setShowFooter(false);

---

form.setShowHeader()

Set the showHeader value to toggle whether the component header is visible.

Definition

form.setShowHeader(showHeader)

Parameters

showHeader

Whether to show the header area.

Type	boolean
Format	True/False
Default	false

Examples

true

---

Examples

Show the header of form.

form.setShowHeader(true);

Hide the header of form.

form.setShowHeader(false);

---

form.submit()

The value is submitted.

Definition

form.submit()

---

form.validate()

Validates the value of the input field.

Definition

form.validate()

Examples

Validate the value of form.

form.validate();

---

Events

Events triggered by user interactions. You can configure event handlers in the IDE to trigger queries or other actions in response to events.

Event	Description
Invalid	A value is invalid.
Submit	The value is submitted.