Forms

Forms that start and drive your workflows.

Design a form on a grid, with lookups into your data and APIs, file uploads, buttons, a header and your theme. Give it its own page and a QR code, start a workflow every time it is submitted, and use each value in the steps that follow — checked on the server, whoever sends it.

Build your first form 27 form-started packages
The UserTasks form designer: a palette of field types, a grid of rows with one to four columns, and the settings of an Attachments field
  • One designer for task forms, start forms and form pages
  • Every submission validated on the server
  • Values typed and ready in the next step

Grid designer

Drag fields onto a grid. It works on a phone too.

Rows of one to four columns, fields that span them, section headings and dividers. On a phone every row collapses to one column, so one layout serves the desk and the warehouse floor.

  • Drag from the palette, or select a type and press Enter
  • Move fields between cells, rows up and down; undo and redo
  • Keys follow the label (contact_email) and rename safely: references in later steps are listed and updated
  • Preview in light or dark, desktop or phone, and check the validation rules
  • Fully keyboard-operable: Alt+arrows move a field, Delete removes it

Grid layout The form designer

The Customer return form on a phone: every row collapsed to one column
The same form at phone width.

Field types

Every field a real process needs.

Seventeen types, each with its own validation, help text, default value (expressions welcome), read-only and visible when rules.

  • Textlength, pattern
  • Long textlength
  • Emailformat checked
  • Phoneformat checked
  • URLhttp(s) only
  • Numbermin / max
  • CurrencyISO code, min / max
  • Datedate range
  • Date & timeUTC, range
  • Checkboxyes / no
  • Single selectdropdown or radio
  • Multi-selectselection count
  • Persona workspace member
  • Autocomplete / lookupdata table or API
  • Attachmentsseveral files
  • Section headinglayout
  • Dividerlayout

Lookups into your data and your APIs.

An autocomplete field suggests as people type — from a data table, or from any API reference you have connected. Picking a customer can fill in their email and phone.

  • Search one or more columns; show a main line and a second line
  • Filters can use other fields ({{task_data.region}}) or workflow variables
  • Several selections as chips, or free text when you allow it
  • The chosen item travels downstream as {{form.customer_item}}
  • Re-checked on the server; credentials never reach the browser

Lookup fields Every field type

Preview of a form whose Customer lookup suggests two customers with their city and country
A standalone form page with a header, three-column rows, a customer lookup that filled the contact fields, and three uploaded files

Attachments

Photos, PDFs and spreadsheets, straight into the run.

Drag files in, paste them, browse, or use the camera on a phone. Each file shows its progress and can be retried, reordered or removed.

  • Set how many files, how large, and which kinds: documents, images, spreadsheets, PDF only or any safe file
  • Checked by content, not name; programs, scripts and macro-enabled Office files refused
  • Private storage, downloads only for people who may see the task or submission, optional ClamAV scan
  • Loop over {{form.photos}}, email them, upload them to S3 or SharePoint, or give them to an AI agent

Then read them: document actions turn an uploaded Word, Excel, PowerPoint or PDF file into text, rows and structure in the next step.

Attachments How files are kept safe

Buttons, behaviours and headers

Decide what happens when someone presses Submit.

Rename buttons, style them, add outcome buttons that complete a task, a Save draft button or more submit buttons. Each one runs its steps in order — and a header with your logo, a title and a subtitle sits above the fields.

  1. 1

    Show message

    A message under the form, with the submitted values filled in.

  2. 2

    Show success screen

    Replace the form with a title, text and a Submit another, Close or link button.

  3. 3

    Start workflow

    Start any workflow with the form's values mapped to its inputs — on the server, attributed to whoever submitted.

  4. 4

    Redirect

    Go to an app page or an address on your allow list.

  5. 5

    Close form

    Close the form.

The Buttons and header tab: a header with the workspace logo, title and subtitle, and a Submit return button that shows a success screen

Typical chains: Submit → Start workflow → Show success screen with the run reference. A double-click records one submission.

Buttons and behaviours Headers

Themes

Your brand on every surface of the form.

Forms follow your workspace theme in light and dark. Give one a mini theme — accent, page background or gradient, inputs, borders, buttons, radius, font, density, label position — and it applies to the page, the task, the preview and the success screen.

  • Start from a preset, save themes and reuse them across forms
  • Separate light and dark colours
  • Every text and background pair kept legible (AA contrast), with an Auto-fix for low-contrast pairs

Form themes Workspace theme

The designer previewing a form at phone width with a custom mini theme: bronze accent, cream page and a header with the workspace logo

Form pages and the Form submitted trigger

A link, a QR code — and a workflow on every submission.

Every reusable form has its own page. Share the link, print the QR code on a poster or a tablet stand, and let the Form submitted trigger start a workflow with the values.

Form pages

/f/<id> for signed-in members, with the header, grid, theme, lookups and buttons. Submissions are listed, exported to CSV and kept as long as you choose.

QR codes

Download PNG or SVG, with or without the name and link under the code. Dark on a white card with a quiet zone, so it scans on screen and in print.

Publish as form page

Turn a workflow's start form into a page in one click. It stays in sync with the published version and starts the workflow as the person who submits.

A workflow whose Form submitted trigger is linked to the Customer return form, with the form page link, Copy link, Open form, QR code and every form variable listed

The Form submitted trigger Form pages and QR codes Publish as form page

The Data panel docked beside a Log step, listing the Customer return form's fields with their keys and types

Values downstream

Every field, typed, in the next step.

The Data panel lists the form's fields first — label, key and type — at every step. Drag one onto a setting, or click to insert it.

text
{{form.order_number}}          "10248"
{{form.refund_amount}}         412.5
{{form.customer_item.city}}    "Marseille"
{{form.photos_count}}          3
{{task_data.approved_amount}}  after a User Task

Data panel and drag and drop Keys and downstream data

Reuse, version and test

Build a form once. Change it safely.

Forms library

Search and tag forms, see which steps use each one, duplicate, export and import. Link a form from any User Task, or detach a local copy.

Versions

Every change to fields, layout or theme is a new version. Drafts follow the latest; publishing a workflow pins the version it uses.

Test with the real form

Save & Test draws the form exactly as people see it, checks it on the server and starts a test run. Test cases remember what you entered.

Validated on the server

The page, the task screen, the API, MCP, the CLI and test runs all go through the same checks. Read-only fields keep their value.

Forms as code, too.

Forms, form themes and submissions have REST endpoints, MCP tools and CLI commands, and travel with config as code, GitHub sync and packages. Upload files and submit with the same checks as the browser.

Reusable forms Testing with forms

shell
usertasks forms create -f customer-return.json
usertasks forms submit <form id> \
  --set values:='{"order_number":"10248","refund_amount":412.5}' \
  --attach photos=./carton.jpg --attach photos=./delivery-note.pdf
usertasks forms submissions <form id> -o json

Package gallery

Start from a form that already works.

27 gallery packages start from a form — form pages with their own header and theme, grid task forms, and the workflow behind them. Install one and change it in the designer.

Every form-started package

Questions

Where can a form be used?

On a User Task (what the assignee fills in), as a workflow's start form (the Run dialog, Save & Test, API and CLI starts), as a reusable form on its own page at /f/<id> with a QR code, and as the form a task trigger declares. One designer builds all of them.

How does a form start a workflow?

Two ways. Add a Form submitted trigger to a workflow and choose the form: every submission — from its page, the API, MCP or a linked User Task — starts a run with the values as {{form.<key>}}. Or give a button a Start workflow behaviour that maps the form's values to another workflow's inputs.

Is validation only in the browser?

No. Every way of submitting — the form page, the task screen, the REST API, MCP, the CLI and test runs — is checked on the server against the form: types, required fields, ranges, patterns, options, people, lookup values and attachments. Invalid values are refused with one message per field.

Which files can people upload?

An Attachments field sets how many files, how large and which kinds (documents, images, spreadsheets, PDF only or any safe file). Files are checked by their content, stored in private storage, never served publicly and can be scanned with ClamAV. Workflows then loop over them, email them, upload them or read them with document actions.

Can I build forms from code?

Yes. Forms, form themes and submissions have REST endpoints, MCP tools and usertasks CLI commands, and travel with config as code, GitHub sync and packages. The designer writes the same JSON you can send.

Build your first form in five minutes.

Fields on a grid, a button that starts a workflow, a page with a QR code. The guide walks through it step by step.

Forms guide Document actions