Skip to content

Open source website builder and Webflow alternative. Webstudio is an advanced visual builder that connects to any headless CMS, supports all CSS properties, and can be hosted anywhere, including with us.

docs: Explain Form capabilities with focused screenshots (#6591)

Oleg Isonen0a4e3a48dd91
diff --git a/.github/actions/builder-e2e-shard/action.yml b/.github/actions/builder-e2e-shard/action.yml
index d0726f2305..742e748445 100644
--- a/.github/actions/builder-e2e-shard/action.yml
+++ b/.github/actions/builder-e2e-shard/action.yml
@@ -45,7 +45,7 @@ runs:
E2E_TEST_SHARD: ${{ inputs.shard }}
E2E_TEST_PARTITION: ${{ inputs.partition }}
run: |
- args=(--workers=4)
+ args=(--workers=2)
if [ -n "$E2E_TEST_PARTITION" ]; then
args+=(--shard="$E2E_TEST_PARTITION")
fi
diff --git a/apps/builder/e2e/flows/mcp-preview-submit.ts b/apps/builder/e2e/flows/mcp-preview-submit.ts
index ec2ab8df0d..821a61b591 100644
--- a/apps/builder/e2e/flows/mcp-preview-submit.ts
+++ b/apps/builder/e2e/flows/mcp-preview-submit.ts
@@ -1,5 +1,6 @@
import { spawn } from "node:child_process";
import { fileURLToPath } from "node:url";
+import { chromium } from "@playwright/test";
import type {
ProjectSessionPreviewSubmitFormInput,
ProjectSessionPreviewSubmitFormResult,
@@ -36,7 +37,11 @@ export const submitPreviewFormViaMcp = async ({
],
{
stdio: ["pipe", "pipe", "pipe"],
- env: { ...process.env, TSX_TSCONFIG_PATH: cliTsconfigPath },
+ env: {
+ ...process.env,
+ TSX_TSCONFIG_PATH: cliTsconfigPath,
+ WEBSTUDIO_BROWSER_PATH: chromium.executablePath(),
+ },
}
);
let stdout = "";
diff --git a/apps/builder/e2e/run.sh b/apps/builder/e2e/run.sh
index cfd02d7112..8fe417182e 100644
--- a/apps/builder/e2e/run.sh
+++ b/apps/builder/e2e/run.sh
@@ -39,6 +39,8 @@ case "$mode" in
export E2E_BUILD_DATABASE_IMAGE=false
export E2E_SKIP_BUILDER_BUILD=true
export E2E_SKIP_CLEANUP=true
+ export E2E_PGPORT="${E2E_PGPORT:-0}"
+ export E2E_POSTGREST_PORT="${E2E_POSTGREST_PORT:-0}"
;;
*)
echo "Unknown Builder E2E mode: $mode" >&2
@@ -59,9 +61,6 @@ export POSTGRES_DB="${E2E_POSTGRES_DB:-webstudio}"
# E2E_DIRECT_URL.
export POSTGRES_USER="supabase_admin"
export POSTGRES_PASSWORD="${E2E_POSTGRES_PASSWORD:-pass}"
-export DATABASE_URL="${E2E_DATABASE_URL:-postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@localhost:${PGPORT}/${POSTGRES_DB}?pgbouncer=true}"
-export DIRECT_URL="${E2E_DIRECT_URL:-postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@localhost:${PGPORT}/${POSTGRES_DB}}"
-export POSTGREST_URL="${E2E_POSTGREST_URL:-http://localhost:${POSTGREST_PORT}}"
export E2E_BACKEND_MODE="${E2E_BACKEND_MODE:-test}"
source "$ROOT_DIR/apps/builder/backend/lib.sh"
@@ -193,6 +192,14 @@ run_step "prepare e2e database image" "$E2E_DOCKER_PULL_TIMEOUT_SECONDS" \
run_step "start e2e database" "$E2E_DOCKER_TIMEOUT_SECONDS" \
builder_backend_start_db
+db_port="$PGPORT"
+if [ "$db_port" = 0 ]; then
+ db_port="$(builder_compose port db 5432)"
+ db_port="${db_port##*:}"
+fi
+export DATABASE_URL="${E2E_DATABASE_URL:-postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@localhost:${db_port}/${POSTGRES_DB}?pgbouncer=true}"
+export DIRECT_URL="${E2E_DIRECT_URL:-postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@localhost:${db_port}/${POSTGRES_DB}}"
+
run_step "generate prisma client" "$E2E_MIGRATIONS_TIMEOUT_SECONDS" \
builder_generate_prisma_client "$E2E_GENERATE_PRISMA"
@@ -206,6 +213,12 @@ if [ "$E2E_START_POSTGREST" = "true" ]; then
run_step "start e2e postgrest" "$E2E_DOCKER_TIMEOUT_SECONDS" \
builder_backend_start_postgrest
fi
+postgrest_port="$POSTGREST_PORT"
+if [ "$E2E_START_POSTGREST" = "true" ] && [ "$postgrest_port" = 0 ]; then
+ postgrest_port="$(builder_compose port postgrest 3000)"
+ postgrest_port="${postgrest_port##*:}"
+fi
+export POSTGREST_URL="${E2E_POSTGREST_URL:-http://localhost:${postgrest_port}}"
if [ "$E2E_RUN_TESTS" = "true" ]; then
run_step "install playwright chromium" "$E2E_PLAYWRIGHT_INSTALL_TIMEOUT_SECONDS" \
diff --git a/docs/.gitbook/assets/form-actions-dark.jpg b/docs/.gitbook/assets/form-actions-dark.jpg
new file mode 100644
index 0000000000..db6a024f26
Binary files /dev/null and b/docs/.gitbook/assets/form-actions-dark.jpg differ
diff --git a/docs/.gitbook/assets/form-actions-light.jpg b/docs/.gitbook/assets/form-actions-light.jpg
new file mode 100644
index 0000000000..925d615e71
Binary files /dev/null and b/docs/.gitbook/assets/form-actions-light.jpg differ
diff --git a/docs/.gitbook/assets/form-components-dark.jpg b/docs/.gitbook/assets/form-components-dark.jpg
new file mode 100644
index 0000000000..9b6d58e75a
Binary files /dev/null and b/docs/.gitbook/assets/form-components-dark.jpg differ
diff --git a/docs/.gitbook/assets/form-components-light.jpg b/docs/.gitbook/assets/form-components-light.jpg
new file mode 100644
index 0000000000..cdc44764d4
Binary files /dev/null and b/docs/.gitbook/assets/form-components-light.jpg differ
diff --git a/docs/.gitbook/assets/form-email-dark.jpg b/docs/.gitbook/assets/form-email-dark.jpg
new file mode 100644
index 0000000000..5c737bae04
Binary files /dev/null and b/docs/.gitbook/assets/form-email-dark.jpg differ
diff --git a/docs/.gitbook/assets/form-email-light.jpg b/docs/.gitbook/assets/form-email-light.jpg
new file mode 100644
index 0000000000..b98e492251
Binary files /dev/null and b/docs/.gitbook/assets/form-email-light.jpg differ
diff --git a/docs/.gitbook/assets/form-variables-dark.jpg b/docs/.gitbook/assets/form-variables-dark.jpg
new file mode 100644
index 0000000000..eab62dc8b0
Binary files /dev/null and b/docs/.gitbook/assets/form-variables-dark.jpg differ
diff --git a/docs/.gitbook/assets/form-variables-light.jpg b/docs/.gitbook/assets/form-variables-light.jpg
new file mode 100644
index 0000000000..6d9c5663ea
Binary files /dev/null and b/docs/.gitbook/assets/form-variables-light.jpg differ
diff --git a/docs/.gitbook/assets/form-visitor-dark.jpg b/docs/.gitbook/assets/form-visitor-dark.jpg
new file mode 100644
index 0000000000..9330a5298c
Binary files /dev/null and b/docs/.gitbook/assets/form-visitor-dark.jpg differ
diff --git a/docs/.gitbook/assets/form-visitor-light.jpg b/docs/.gitbook/assets/form-visitor-light.jpg
new file mode 100644
index 0000000000..8f18bcbe9e
Binary files /dev/null and b/docs/.gitbook/assets/form-visitor-light.jpg differ
diff --git a/docs/university/core-components/form.md b/docs/university/core-components/form.md
index 32404bec0e..196d76e8ca 100644
--- a/docs/university/core-components/form.md
+++ b/docs/university/core-components/form.md
@@ -1,67 +1,338 @@
---
-description: Collect form fields and submit them to HTTP or email resources.
+description: Send data, files, and emails, or build search and filters without reloading the page.
---
# Form
-Use **Form** to send visitor input to HTTP or email [resources](../foundations/cms.md#resources). Add it from **Components > Forms**. Each newly inserted Form includes named name, email, subject, and message fields, a submit button, editable success and error messages, and two selected email resources. One sends to project settings recipients (or the site owner); the other sends to the submitted email address. You can edit or remove either action.
+Form is a custom Webstudio component for collecting information without reloading the page. Use it to:
-## Configure actions
+- Send data and files to an API.
+- Send email notifications and visitor confirmations.
+- Build search and filter forms that update URL query parameters.
-1. Use the two email resources included in a new Form, or create HTTP, email, or GraphQL resources in **Variables**, on the Form or an ancestor.
-2. Select the Form. In **Properties & Attributes > Action**, use the plus menu to choose up to ten visible resources. Each resource can be selected once; use the row control to remove an action. Edit a resource in **Variables**.
-3. Give each input a **Name**. Its name identifies the submitted value in `formData`.
-4. Submit the Form in Builder Preview to test the current draft, or publish and test the deployed site.
+A single submission can do several things at once. For example, it can email your team, confirm receipt to the visitor, and send the submitted data to another service.
-With selected actions, the Form starts independent destinations in parallel. Every HTTP destination receives a POST request. With no actions selected, the Form uses **Navigation** mode: a GET submission updates the current page's query string using its named fields. A resource created inside the Form can bind `formData` and the safe `browserInfo` values (visitor IP, user agent, language, and referrer). A resource on an ancestor can be selected, but cannot bind that Form's data.
+**You can test all of this in Preview without publishing.**
-By default, a Form-scoped HTTP resource forwards all submitted fields. It sends JSON for text values and multipart data when files are included. Edit the resource body to choose or transform fields, or set its body format if the receiving service requires one. An HTTP resource outside the Form uses its own configured body.
+For a basic HTML form with native browser behavior, insert an [Element](element.md) and set its tag to `form`.
-For a selected email resource that sends to project or custom recipients, an unset body uses automatic text containing the submitted Form fields and browser information. This default works whether the resource is defined on the Form, an ancestor, or global root. Set the resource body to customize the message, including an explicitly empty body. To use `formData` or `browserInfo` in a resource expression, define the resource on the Form; resources on an ancestor or global root cannot bind that Form’s data.
+## Start with a working contact form
-### Send browser information to a destination
+Insert **Form (Beta)** from **Components > Forms**. On Webstudio Cloud, the default form is ready to use. It includes:
-In a resource created inside the Form, add these headers in the resource editor when your destination needs them:
+- Name, email, subject, and message fields.
+- An optional file attachment.
+- **Email to owner**, which sends the submitted information and page URL to your project recipients.
+- **Email to visitor**, which sends a confirmation to the submitted email address.
+- Editable success and error messages.
-| Header | Value expression |
-| ----------------- | ----------------------- |
-| `X-Forwarded-For` | `browserInfo.ip` |
-| `User-Agent` | `browserInfo.userAgent` |
-| `Accept-Language` | `browserInfo.language` |
+If you haven’t configured project recipients, the owner notification goes to the account holder.
-These values are sent only when you configure the headers. `browserInfo` also provides `referrer`. It does not expose cookies, authorization, or raw request headers. On Cloudflare Workers, `browserInfo.ip` comes from Cloudflare's `CF-Connecting-IP` request header. The generated React Router Cloudflare Worker supplies the Cloudflare hosting context; the Remix Cloudflare adapter also supplies it. On Node-based hosts, including the generated Docker, Netlify, and Vercel adapters, no trusted visitor-IP source is configured, so `browserInfo.ip` is absent. The Form does not derive it from visitor-supplied `X-Forwarded-For` or `X-Real-IP` headers. If an IP header is required on another host, configure a trusted source at the hosting boundary before relying on it.
+Open Preview and submit with an email address you control to try it. These defaults are a starting point: you can change the fields, customize the emails, or replace the actions entirely.
-On a published Webstudio Cloud site, an email resource sends through Webstudio's private Cloudflare email service when the `EMAIL_SERVICE` binding is configured. Set project recipients and Reply to in [project settings](../foundations/project-settings.md#emails); set subject and body on the email resource. The resource Reply to override is empty by default. The server rejects a submission if an email resource cannot send because the binding is missing. Other hosts need their own server-side email integration; a static export cannot send managed Form email. [Existing Webhook Forms](webhook-form.md) keep their separate behavior.
+## Collect the information you need
-Each email from a Form submission includes an `X-Message-ID` header. Email actions from the same submission share the header value. The configured subject stays unchanged. Email actions are sent once and are not retried after dispatch.
+Add fields inside the Form from **Components > Forms**. Each field needs a **Name**, which identifies its value when the form is submitted.
-The **Visitor** email resource in a newly inserted Form uses its named `email` input. To configure another Form manually, add an email resource in **Variables**, select **Visitor** as its recipient, choose one named email input, and add that resource to the Form's Action. The server requires exactly one valid address in the chosen field. A fixed preamble says the request came from the website and includes its URL. The resource body starts empty; you can add plain text and bindings after the preamble. When a Form includes file inputs, submitted files are attached to the outgoing email resource message by default. Turn off ‘Attach submitted files’ to omit them. It runs alongside other actions; a delivery error appears in `errors` without making the overall Form submission fail. It requires Webstudio Cloud email service configuration.
+<picture>
+ <source media="(prefers-color-scheme: dark)" srcset="../../.gitbook/assets/form-components-dark.jpg">
+ <img src="../../.gitbook/assets/form-components-light.jpg" alt="Forms section in the Components panel, with Form (Beta), Button, Input Label, Text Input, File Input, Text Area, Select, Radio, and Checkbox." width="232">
+</picture>
-A Form can send up to **five team-recipient deliveries** across all of its email resources. Duplicate addresses count as separate deliveries; one visitor-addressed email resource is allowed in addition. The server checks this total before running any destination. Webstudio Cloud also applies an approximate limit of **50 recipient deliveries per project, per Cloudflare location, per minute**; Preview and published sites use separate project keys. Cloudflare's account-level daily sending quota can be lower and varies by account. A rate-limited primary email resource fails before delivery and makes the Form show its error state; a visitor-addressed email resource failure remains nonfatal. Other parallel destinations may still finish.
+For example, a field named `subject` becomes available in bindings as `formData.subject`. Its visible label can be different.
-## Inputs and responses
+Fields can share a Name to collect multiple values, such as a group of checkboxes.
-Add inputs from **Components > Forms**. Each value you want to send needs a **Name**. Inputs with the same name keep all their selected values in form order. An unchecked checkbox group remains an empty list.
+See the individual component guides for field settings:
-For uploads, add **File Input** and set **Name**, **Required**, **Accept**, and **Multiple** in Settings. **Accept** guides the browser's file picker; it does not validate file types on the server. A required empty file input blocks submission. An optional empty file input submits without a file.
+- [Text Input and File Input](input.md)
+- [Text Area](textarea.md)
+- [Select](select.md)
+- [Radio](radio-button.md)
+- [Checkbox](checkbox.md)
+- [Input Label](label.md)
+- [Button](button.md)
-The entire managed Form request is limited to **25 MiB**, including all selected files, other fields, and multipart encoding. This is a combined limit, not an allowance for each file. If the request is too large, the server rejects it before sending to any resource and reports `Form submission exceeds the 25 MiB limit. Reduce file sizes and try again.` Outbound HTTP resource request bodies have a separate 25 MiB limit, and the receiving service may impose a lower limit.
+## Send to several destinations
-When files are attached to an email, the server checks for at most **32 attachments** and no more than **7 MiB of aggregate Base64 attachment data** before starting the selected destinations. The private email Worker separately caps its complete serialized JSON request at **7 MiB**, including email text and Base64 files. Cloudflare measures the final email, including MIME encoding, against its **5 MiB general limit**; **25 MiB** applies only to verified destination addresses. The Worker does not calculate final MIME size before sending, so Cloudflare can reject a message after other selected destinations have started. See [Cloudflare Email Service limits](https://developers.cloudflare.com/email-service/platform/limits/) and [Workers binding error codes](https://developers.cloudflare.com/email-service/api/send-emails/workers-api/#error-codes).
+**Actions** define what happens when someone submits the Form. Each action uses a Resource, which contains the destination and its settings.
-Cloud email can also fail because the provider rejects a recipient or Reply to address, suppresses a recipient, reaches an account sending limit, or is temporarily unavailable. The Form reports the resulting resource error and does not claim successful owner delivery. A timeout can leave delivery uncertain; the Form does not retry an email because another send could create a duplicate.
+You can select up to **10 REST, GraphQL, or Email Resources**.
-The inserted Form has **Form content**, **Success message**, and **Error message** sections. When every primary destination succeeds, the success state appears; otherwise the error state appears. A failed visitor-addressed email resource is reported in `errors` but does not change the overall success state. The Form exposes `formState` (the current Form state: initial, success, or error), `results` (responses from selected actions, in order, including each resource's HTTP status code and response body), and `errors` (failed actions in order, including each resource's HTTP status code, response body, message, and an error code for managed email when available). A configured **Success redirect** runs only after overall success. Without a redirect, successful submissions reset the Form to its authored field defaults and refresh the current page's resources without a full-page reload or a second submission. The newly inserted Form has empty defaults. Failed submissions leave the entered values in place.
+Select the Form and open **Settings > Properties & attributes > Action**:
-## Hosting and plain HTML forms
+- Click **+** to choose a Resource.
+- Click an existing action to edit its Resource.
+- Drag actions to change their order.
+- Remove an action to stop using it on this Form. The Resource itself remains available.
-Managed Form submission requires a running server endpoint on the published site. Webstudio generates a same-origin POST endpoint for each Form page in a dynamic JavaScript application. The host must run that application and route POST requests to it; a [static export](../self-hosting/README.md#static-site-limitations) has no submission endpoint and cannot deliver Form resources. Resource credentials and outbound requests stay on the server.
+<picture>
+ <source media="(prefers-color-scheme: dark)" srcset="../../.gitbook/assets/form-actions-dark.jpg">
+ <img src="../../.gitbook/assets/form-actions-light.jpg" alt="Form Action settings with the plus button, Email to owner and Email to visitor actions, and the Success redirect control below them." width="238">
+</picture>
-For ordinary browser form behavior, add **Element**, set its tag to `form`, and configure native HTML attributes such as `action`, `method`, and `enctype`. That form follows the browser's validation and navigation behavior and can be used on a static site when its action points to a working destination.
+If the list is empty, create a Resource in **Variables** first. You can select each Resource once.
+
+Actions run in parallel. Reordering them changes the order of their results, not the order in which they run. One selected action cannot use another action’s response.
+
+### Use submitted values
+
+Create a Resource **on the Form** when it needs submitted values. You can then bind fields into its settings:
+
+```text
+"Contact form: " + (formData.subject ?? "New message")
+```
+
+Resources on ancestors or the global root can also be selected as actions, but they cannot bind this Form’s local variables.
+
+### Send to an API
+
+Choose a Resource type that matches your service:
+
+- **REST:** configure the URL, headers, search parameters, body, and format.
+- **GraphQL:** configure the URL, headers, query or mutation, and variables.
+
+When used as Form actions, HTTP Resources send **POST** requests, regardless of their saved Method.
+
+If an HTTP Resource has no configured body, the Form sends its submitted fields. This also works for Resources on ancestors or the global root. Set a custom body when you want to choose or transform the fields yourself. GraphQL uses its configured query and variables.
+
+For REST Resources, **Format** controls how the body is sent:
+
+| Format | What it sends |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `auto` | Plain text for text values, JSON for objects and arrays, or multipart form data when the body contains file fields. |
+| `application/json` | An object or array as JSON. |
+| `multipart/form-data` | Fields and files as form data. |
+
+Choose the format your API expects. Uploaded files need multipart form data; they cannot be sent as JSON.
+
+See [Variables](../foundations/variables.md) for more about Resource settings and bindings.
+
+## Customize email notifications
+
+Email Resources can notify your team, confirm receipt to a visitor, or send different messages to different recipients. The default Form includes two emails, but you can edit or remove either one.
+
+<picture>
+ <source media="(prefers-color-scheme: dark)" srcset="../../.gitbook/assets/form-email-dark.jpg">
+ <img src="../../.gitbook/assets/form-email-light.jpg" alt="Email to owner Resource configuration with project recipients, an empty Reply to field, bound Subject and Body fields, and Attach submitted files selected." width="320">
+</picture>
+
+### Choose recipients
+
+| Recipients option | Who receives the email |
+| --------------------------------- | ----------------------------------------------------------------------------- |
+| **Project recipients (or owner)** | Addresses from project settings, or the account holder if that list is empty. |
+| **Custom recipients** | Addresses entered or bound on this Resource. |
+| **Visitor email field** | The address submitted through the Form’s selected email input. |
+
+Use `Name <address>` to include a recipient’s name, such as `John <[email protected]>`. Separate multiple custom recipients with commas.
+
+For a visitor confirmation, create the Email Resource on the Form. Its email input must have a fixed **Name** and a **Type** of `email` to appear in the field selector. The submitted value must contain one valid email address.
+
+<picture>
+ <source media="(prefers-color-scheme: dark)" srcset="../../.gitbook/assets/form-visitor-dark.jpg">
+ <img src="../../.gitbook/assets/form-visitor-light.jpg" alt="Email to visitor Resource with Visitor email field selected, the email input chosen, a confirmation message, and Do not attach files selected." width="320">
+</picture>
+
+### Set Reply to
+
+**Reply to** determines where replies go. It accepts one address, optionally with a name, and supports bindings.
+
+For an owner notification, you could use the visitor’s details so your team can reply directly:
+
+```text
+`${formData.name} <${formData.email}>`
+```
+
+Leave Reply to empty on the Resource to use the value from project settings.
+
+The name in Reply to also identifies your organization in the default visitor confirmation. It appears in the subject and at the end of the message. Without a name, the default uses “Site Owner.”
+
+Reply to does not change the sending email address used by Webstudio’s email service.
+
+### Write the subject and message
+
+Both **Subject** and **Body** support bindings. Use submitted fields to personalize the message, or `browserInfo.pageUrl` to include the page it came from.
+
+To include all submitted fields, insert `formData` into the body:
+
+```text
+`Message from ${formData.name}
+
+${formData}`
+```
+
+Webstudio turns the object into readable field names and values. Adding another named field then includes it automatically. Files appear as filenames; attaching the files is a separate setting.
+
+Automatic formatting excludes password inputs and Webstudio’s internal fields. If an input’s Name or Type uses a binding, the automatic field list is omitted. Use explicit field bindings in that case.
+
+The default visitor message thanks the visitor, confirms receipt, and ends with the name from Reply to. You can replace its subject and body with your own text.
+
+Email bindings can use submitted fields and other available Variables, but cannot use another Resource’s response.
+
+### Share defaults across forms
+
+Set recipients and Reply to under **Project settings > Emails**.
+
+- Choose **Project recipients** on a Resource to use the shared recipient list.
+- Leave its **Reply to** empty to inherit the project value.
+- Set either field on the Resource to override that default.
+
+Subject and body belong to each Email Resource.
+
+See [project email settings](../foundations/project-settings.md#emails).
+
+## Send files
+
+Add a **File Input** inside the Form and give it a **Name**. Use **Required**, **Accept**, and **Multiple** to configure the picker.
+
+**Accept** helps visitors choose the right files. The receiving server must still validate their types.
+
+Each action controls what happens to uploaded files:
+
+- **Email:** choose **Attach submitted files** or **Do not attach files**.
+- **HTTP API:** use multipart form data. The automatic format selects it when the body contains files.
+
+The default owner email attaches files. The default visitor confirmation does not. An optional file input left empty sends no file.
+
+See [Input](input.md) for field settings and [Limits and hosting](#limits-and-hosting) below for upload limits.
+
+## Build search and filter forms
+
+Remove all actions to switch the Form to **Navigation mode**.
+
+Submitting now puts the named field values into the current page’s URL without a full reload. For example, submitting `chairs` through a field named `query` on `/products` produces:
+
+```text
+/products?query=chairs
+```
+
+A page Resource can use that value through a binding:
+
+```text
+system.search.query
+```
+
+Bind it to the Resource’s search parameter to load matching results. Add more fields for filters such as category or price.
+
+Submission replaces the current query string. Include any parameters you want to keep as fields; hidden inputs work for this. Fields sharing a Name produce repeated query parameters.
+
+Navigation mode does not use **Success redirect**. Use Resource actions when you need to upload files.
+
+## Choose what happens after submission
+
+The default Form contains three containers:
+
+- **Form content** holds the fields.
+- **Success message** appears after success.
+- **Error message** appears after failure.
+
+Their **Show** bindings use `formState` to control visibility. By default, success hides the fields and shows the success message. Failure keeps the fields and entered values visible.
+
+Select the message containers in Navigator to edit their text and design.
+
+### Keep the fields visible
+
+To keep the Form visible after success, select **Form content** and change its **Show** binding to an always-visible value.
+
+A successful submission without a redirect resets fields to their default values. The default template has empty values, so visitors see an empty form again. You can show the success message alongside it.
+
+On published dynamic sites, a successful submission also refreshes the current page’s Resources without reloading the page.
+
+### Redirect to another page
+
+Set **Success redirect** below the actions to send visitors to a thank-you page or another URL after success.
+
+This setting is available when the Form has actions.
+
+### Handle failures
+
+All actions except visitor confirmation must succeed for the Form to show success. A failed visitor confirmation is recorded in `errors`, but does not make an otherwise successful submission fail.
+
+Actions can succeed or fail independently. Your team might receive an email even when an API request fails. Check the individual results before submitting again.
+
+Emails are not automatically resent when delivery is uncertain, to avoid duplicates.
+
+## Use Form variables
+
+The default Form provides these Variables on the Form and its children:
+
+<picture>
+ <source media="(prefers-color-scheme: dark)" srcset="../../.gitbook/assets/form-variables-dark.jpg">
+ <img src="../../.gitbook/assets/form-variables-light.jpg" alt="Form Variables list showing formData, browserInfo, Email to owner, Email to visitor, formState, results, errors, and system, with dynamic and static badges." width="238">
+</picture>
+
+| Variable | What it contains |
+| ------------- | ------------------------------------------------------------------------------------------------ |
+| `formData` | Submitted values, keyed by field Name. |
+| `browserInfo` | The page URL and available visitor details, such as browser, language, referrer, and IP address. |
+| `formState` | `initial`, `success`, or `error`. |
+| `results` | Action responses in order, including Resource name, HTTP status, and response body. |
+| `errors` | Failed action details, including available status, response body, and error message. |
+
+Use `formData` and `browserInfo` to customize messages and requests. Use `results`, `errors`, and `formState` to display feedback after submission.
+
+Create action Resources on the Form itself when they need these local bindings.
+
+Available visitor details depend on the host and request. Referrer query parameters are removed, and an IP address is only included when the host provides a trusted source. `browserInfo` does not expose cookies, authorization, or raw request headers.
+
+## Test without publishing
+
+Preview lets you test the current draft, including emails, API requests, attachments, and redirects.
+
+1. Open **Preview** and submit the Form.
+2. Check the visible feedback and expected emails or API results.
+3. Return to design mode and open an action’s Resource.
+
+**Preview sends real emails and makes real requests.** Use addresses you control and test destinations.
+
+The Resource inspector shows:
+
+- **Request:** what was sent.
+- **Response:** the returned status, headers, and body, where available.
+- **Diagnostics:** additional execution details, when available.
+
+Sensitive values are hidden, large output is limited, and files appear as metadata rather than their full contents.
+
+Loading an Email Resource’s request preview does not send an email. Submit the Form in Preview to test delivery and capture its response.
+
+Once the Form works as expected, publish it to update the site. Later Builder changes need to be published again.
+
+## Limits and hosting
+
+### Files and message sizes
+
+These limits apply to the whole request or message, not to each file separately.
+
+| Limit | What it includes |
+| ------------------------------------------------ | --------------------------------------------------------------------------------------------- |
+| **25 MiB per Form submission** | All fields, files, and request encoding. |
+| **25 MiB per outbound HTTP Resource body** | The body sent to the API. The receiving API may have a lower limit. |
+| **32 attachments per email** | All files attached to that email. |
+| **7 MiB per email-service request** | Email text, encoded attachments, and request data. |
+| **5 MiB per complete email for most recipients** | The final email and attachments. Cloudflare allows 25 MiB for verified destination addresses. |
+
+Encoding increases file size. A file below the limit on disk can still exceed it once encoded and combined with the rest of the message.
+
+See [Cloudflare’s email limits](https://developers.cloudflare.com/email-service/platform/limits/).
+
+### Sending limits
+
+Webstudio Cloud allows up to **five team-recipient deliveries per submission**, plus one visitor confirmation Resource. Duplicate addresses count as separate deliveries.
+
+An approximate limit of **50 recipient deliveries per project, per Cloudflare location, per minute** also applies. Preview and published sites have separate limits. Provider account limits may apply too.
+
+If an email fails, check its response for the reported reason. See [Cloudflare’s email error reference](https://developers.cloudflare.com/email-service/api/send-emails/workers-api/#error-codes).
+
+### Hosting
+
+Resource actions need a server. Webstudio Cloud provides this; a static export cannot run them.
+
+Self-hosted sites need a supported server setup and an email integration to send Email Resources. See [self-hosting](../self-hosting/README.md).
## Related
-- [Input](input.md) – Name fields and choose input types
-- [Element](element.md) – Use native HTML form behavior
-- [Webhook Form](webhook-form.md) – Configure an existing deprecated form
-- [Self-Hosting](../self-hosting/README.md) – Choose a dynamic or static export
+- [Variables](../foundations/variables.md) — Resources, scope, and bindings.
+- [Project settings](../foundations/project-settings.md#emails) — Shared recipients and Reply to.
+- [Input](input.md) — Field types and settings.
+- [Element](element.md) — Basic HTML forms.
diff --git a/docs/university/core-components/webhook-form.md b/docs/university/core-components/webhook-form.md
index a1d48db531..85f1945551 100644
--- a/docs/university/core-components/webhook-form.md
+++ b/docs/university/core-components/webhook-form.md
@@ -50,7 +50,7 @@ A Webhook Form consists of three nested instances:
2. **Success message** – Displayed upon successful submission.
3. **Error message** – Shown when an error occurs.
-You can [add new inputs](form.md#inputs-and-responses) to further expand and modify your form.
+You can [add new inputs](form.md#collect-the-information-you-need) to further expand and modify your form.
### Form states
@@ -81,7 +81,7 @@ Ensure every form input has a value for the `name` field to be included in submi
<figure><img src="../../.gitbook/assets/form-name.png" alt="Form input name"><figcaption></figcaption></figure>
-For a full list of input types, including checkboxes and radio buttons, refer to [Form inputs](form.md#inputs-and-responses).
+For a full list of input types, including checkboxes and radio buttons, refer to [Form inputs](form.md#collect-the-information-you-need).
### Input properties
diff --git a/docs/university/foundations/variables.md b/docs/university/foundations/variables.md
index 8cb8185f2c..e6c45ef0f5 100644
--- a/docs/university/foundations/variables.md
+++ b/docs/university/foundations/variables.md
@@ -106,9 +106,9 @@ The preview can load the request and show its response, request details, and err
A new [Form](../core-components/form.md) includes two email resources. To add another destination, create a REST, GraphQL, or email resource in **Variables** on the Form or an ancestor. Then select the Form and use **Properties & Attributes > Action** to add the resource. Resources defined on the Form can bind to its `formData` and safe `browserInfo` values; ancestor resources cannot bind to those values. HTTP destinations always send POST requests when the Form is submitted, regardless of their configured method for ordinary data loading.
-The Form also exposes `formState`, `results`, and `errors` in **Variables**. Use these to show the submission state and inspect the selected actions' responses. See the [Form guide](../core-components/form.md#inputs-and-responses) for their contents and submission behavior.
+The Form also exposes `formState`, `results`, and `errors` in **Variables**. Use these to show the submission state and inspect the selected actions' responses. See the [Form guide](../core-components/form.md#use-form-variables) for their contents and submission behavior.
-For a Form-scoped HTTP resource, leave the body unset to forward every named Form field. **Format** defaults to **auto**: text-only Form data is JSON; a body containing uploaded files becomes multipart. Choose **application/json** or **multipart/form-data** when the receiving API requires that format. JSON rejects uploaded files instead of dropping them. Multipart sends repeated values under the same field name and includes uploaded files with their filenames and bytes. Use the [Form upload guide](../core-components/form.md#inputs-and-responses) for file inputs and the combined request limit.
+For a Form-scoped HTTP resource, leave the body unset to forward every named Form field. **Format** defaults to **auto**: text-only Form data is JSON; a body containing uploaded files becomes multipart. Choose **application/json** or **multipart/form-data** when the receiving API requires that format. JSON rejects uploaded files instead of dropping them. Multipart sends repeated values under the same field name and includes uploaded files with their filenames and bytes. Use the [Form upload guide](../core-components/form.md#send-files) for file inputs and the combined request limit.
#### Response