Tasks

Custom form controls

Add your own web components (Lit or plain JavaScript) to forms: the starter kit, the sandbox and security model, the manifest and element contract, packaging, versions and accessibility.

A custom form control is a web component your workspace adds to the form designer: a star rating, a signature pad, a colour picker, a seat map — anything a built-in field type doesn't cover. Upload it once in Extensibility → Form controls, and it appears in the designer's palette under Custom, with a properties panel generated from its manifest. It then works wherever forms render: the designer preview, task forms, form pages (/f/<id>), start forms, Save & Test and Run, with grids, Visible when, required, themes and steps.

Each control is a standard custom element (built with Lit, plain JavaScript or any framework that compiles to one) plus a manifest.json. It runs sandboxed: in its own frame, with no access to the page, the user's session or the network unless an admin allows it, and every value it produces is checked on the server.

How it works

1. The designer stores a field that points at the control and a version, plus its property values and context mapping.
2. When the form renders, each control instance gets its own sandboxed <iframe> served from /form-controls/frame/<tag>/<version>. The frame loads the control's module (snapshotted in UserTasks, never fetched from its source), creates one element and sets its properties.
3. The control talks to the form through a typed postMessage bridge: the host sends the field's state (value, disabled, theme…), the control sends changes, blur, validity, height and requests for host services. Messages carry a per-frame channel nonce and are checked for source, origin and shape.
4. The form treats the value like any other field: it is saved with the task or submission, validated on the server and available downstream as {{task_data.<key>}} (task forms) or {{form.<key>}} (form pages and the Form submitted trigger).

Keyboard focus moves into and out of the frame with Tab like any field, clicking the field's label focuses the control, and the frame grows and shrinks with the control's height (within the manifest's size.min_height / size.max_height). Read-only views (completed tasks, the mobile app) don't run the control: they show its display.template (for example "4 of 5 stars") or the value as formatted text.

Security model

Controls are third-party code, so the defaults assume they are untrusted.

Tutorial: a star rating with Lit

You need Node.js 20 or later.

1. Download the kit. Get form-control-starter.zip, unzip it and open form-control-starter/lit-ts.
2. Install and start the harness.

cd form-control-starter/lit-ts
npm install
npm run dev

Open http://localhost:5180/harness/. The harness is a mock host: it sets the control's properties, toggles disabled / readonly / required / invalid, switches light and dark themes, edits props and context as JSON, logs every ut-* event and answers host requests.

3. Edit. Change src/ut-star-rating.ts (the page reloads on save). Rename the control by changing tag (lowercase with a hyphen, unique in your workspace), name and entry in manifest.json and the tag in the source.
4. Declare what designers can set. Each entry in props becomes a field in the designer's properties panel and an element property:

{
  "tag": "ut-star-rating",
  "name": "Star rating",
  "icon": "star",
  "version": "1.0.0",
  "entry": "ut-star-rating.js",
  "value": { "type": "number", "schema": { "type": "number", "minimum": 0, "maximum": 10 } },
  "props": [
    { "name": "max", "label": "Number of stars", "type": "number", "default": 5, "min": 1, "max": 10 },
    { "name": "allow_clear", "label": "Allow clearing the rating", "type": "boolean", "default": false },
    { "name": "size", "label": "Star size", "type": "select", "default": "medium", "options": ["small", "medium", "large"] }
  ],
  "validation": { "reports_validity": true },
  "display": { "template": "{{value}} of {{props.max}} stars" },
  "accessibility": { "role": "radiogroup", "keyboard": "Arrow keys change the rating; Home/End jump; Delete clears" }
}

5. Build. npm run build typechecks and bundles one self-contained ES module (Lit included, minified) into dist/ut-star-rating.js.
6. Package. npm run package writes release/ut-star-rating-1.0.0.zip with manifest.json and the module.
7. Upload. In UserTasks, open Extensibility → Form controls → Upload and choose the zip. Check the summary (tag, version, value type, capabilities, checksum) and Enable the control.
8. Add it to a form. Open a form in the designer: the control is in the palette under Custom with its icon. Drag it onto the grid, give the field a label and key, then set Number of stars, Allow clearing and Star size in the properties panel. The panel also has the version picker and, for controls that declare context, a mapping from each context name to another field.
9. Preview and publish. Preview runs the real control in light and dark mode and at phone width; Check validation tries required. Save the form (or the workflow) and publish as usual. After a submission, {{form.rating}} or {{task_data.rating}} holds the number.

The control's code is short. The element receives properties and dispatches events:

export class UtStarRating extends LitElement {
  static override properties = {
    value: { attribute: false }, disabled: { type: Boolean, reflect: true },
    readonly: { type: Boolean, reflect: true }, required: { type: Boolean },
    invalid: { type: Boolean, reflect: true }, error: { attribute: false },
    props: { attribute: false }, theme: { attribute: false }, label: { attribute: false },
    description: { attribute: false }, max: { type: Number }, // a declared prop
  }

  #select(n: number) {
    if (this.disabled || this.readonly) return
    this.value = n
    this.dispatchEvent(new CustomEvent('ut-change', { detail: { value: n }, bubbles: true, composed: true }))
  }

  override updated() {
    const valid = !(this.required && !this.value)
    this.dispatchEvent(new CustomEvent('ut-validity', {
      detail: valid ? { valid } : { valid, message: 'Choose a rating.' }, bubbles: true, composed: true,
    }))
  }
}
customElements.define('ut-star-rating', UtStarRating)

The vanilla JavaScript version

form-control-starter/vanilla-js is the same control as a plain custom element with no dependencies and no build step: ut-star-rating.js is the module you upload. Run npm run dev (a static server for the harness, nothing to install), then npm run package for the zip — or upload ut-star-rating.js with manifest.json directly.

class AcmeToggle extends HTMLElement {
  #value = false
  constructor() {
    super()
    this.attachShadow({ mode: 'open', delegatesFocus: true }).innerHTML =
      '<button role="switch" aria-checked="false"></button>'
    this.shadowRoot.querySelector('button').addEventListener('click', () => {
      if (this.disabled || this.readonly) return
      this.value = !this.#value
      this.dispatchEvent(new CustomEvent('ut-change', { detail: { value: this.#value }, bubbles: true, composed: true }))
    })
  }
  set value(v) { this.#value = v === true; this.#render() }
  get value() { return this.#value }
  set label(v) { this.shadowRoot.querySelector('button').setAttribute('aria-label', v ?? '') }
  // …disabled, readonly, required, invalid, error, props, theme, description
  #render() { this.shadowRoot.querySelector('button').setAttribute('aria-checked', String(this.#value)) }
}
customElements.define('acme-toggle', AcmeToggle)

Test with the harness

The harness (harness/index.html in each kit) behaves like the runtime inside the frame. Before you upload:

• Keyboard only: Tab in and out, operate every part, check the focus ring is visible. Click the field label: focus should move into the control.
• States: toggle disabled (not focusable, no changes), readonly (focusable, no changes), required (a ut-validity with valid: false while empty), invalid with an error message (announced through the control's description).
• Theme: switch to dark; check text and non-text contrast with the tokens.
• Props and context: apply props JSON (for example {"max": 10, "size": "small"}) and context JSON.
• Events: the log shows every ut-* event; values that don't match value.type or the schema bounds are flagged in red, and so are events that aren't composed.
• Requests: grant lookup / files (only those the manifest declares can be granted), edit the lookup items, add a delay or make requests fail.
• Screen reader: the control should announce the field's label, its role and state.

The harness isn't the sandbox: it doesn't apply the frame's CSP. A build that passes the kit's checks (one module, no imports, no import.meta.url) runs under it.

Contract reference

The source of truth is lib/forms/custom-controls/contract.ts (also exported by the @usertasks/form-control package once it is published).

manifest.json

Each entry in props is { name, label, type, description, default, options, min, max, required }. type is one of:

A prop's name can't be one of the host's property names (value, disabled, props, label…) or a built-in element property (id, style, hidden, title, innerHTML…).

Element properties (host → control)

The runtime creates exactly one <tag> element and sets these properties (not attributes), first all at once and then whenever they change:

Each declared prop is also set by its own name (el.max = 5), so Lit's reactive properties and plain setters both work. The host draws the visible label, help text and error message around the frame; the control uses label, description and error for its accessible name and description.

Events (control → host)

Dispatch them on the element as CustomEvents with bubbles: true, composed: true:

Theme tokens

The runtime sets these CSS custom properties on the frame's :root (so they inherit into shadow roots) and passes them in theme.tokens (without the leading --). They come from the form's theme or mini theme in the current mode, so style with them rather than fixed colours:

theme.mode is light or dark; switch any colours you can't express with tokens on it.

Capabilities and host requests

A control asks the form for a service by dispatching ut-request with a kind, a payload and the resolve / reject functions of a promise. The request only works if the manifest declares the matching capability (and the field allows it); otherwise it is rejected.

const result = await new Promise((resolve, reject) =>
  this.dispatchEvent(new CustomEvent('ut-request', {
    detail: { kind: 'lookup', payload: { query: 'acme' }, resolve, reject },
    bubbles: true, composed: true,
  })))

network is different: it doesn't add a request kind, it lets the control's own fetch reach the hosts in network.allowed_hosts that an admin approved (HTTPS only). Prefer lookup (it uses the workspace's integrations and keeps credentials on the server).

Value types and downstream data

null means "no value": the form's Required fails on null (and on an empty string or array). The data picker lists a custom field with its value type.

Server validation

Every way of saving or completing a task and every form submission (the app, /api/v1, MCP, the CLI, Save & Test) checks a custom field's value on the server, never trusting the control:

• the value matches value.type, and Required and Visible when apply as for any field;
• value.schema holds, using this JSON Schema subset: type, enum, const, minimum / maximum / exclusiveMinimum / exclusiveMaximum, multipleOf, minLength / maxLength, pattern, format (date, date-time, email, uri), items, minItems / maxItems, uniqueItems, properties, required and additionalProperties;
• the value is at most 256 KB of JSON, and files values only reference files uploaded for that form or task.

Invalid values are refused with a message for the field and nothing is recorded.

Packaging

Upload either:

• a zip with manifest.json and the module at its root (plus an optional README.md and LICENSE), or
• the module (.js or .mjs) and its manifest JSON as two files.

ut-star-rating-1.0.0.zip
├── manifest.json
└── ut-star-rating.js

The module must be one self-contained ES module: the frame's CSP blocks every other request, so bundle every dependency (esbuild, Rollup or Vite in library mode with a single output), and don't use dynamic import() of other files, import.meta.url to load assets, external stylesheets or web fonts. Inline images and fonts as data: URIs.

Versions and upgrades

• version is semver, and each upload is a new immutable version: the same tag and version can't be uploaded twice with different contents. The library shows each version's checksum, size, uploader and date.
• A field stores the version it uses. New fields get the latest enabled version; existing fields keep theirs until a designer picks another in the field's version picker, so uploading 1.1.0 never changes a published form by itself.
• Bump the patch for fixes, the minor for new optional props, and the major when the value's shape changes. Values already saved aren't migrated: if the type or schema changes incompatibly, keep reading the old shape or publish under a new tag.
• Disable a control to hide it from the palette and stop it loading — a kill switch for a control you no longer trust: forms that use it show "disabled in this workspace" in its place until you enable it again (or move them to another control). Check Usage first. Delete is blocked while any form, workflow (draft or published) or open task uses it; the error and Usage list them.

Import from a URL

Import from URL (Extensibility → Form controls) takes an https:// link to a zip, or to the module with its manifest beside it. UserTasks fetches it once through the same egress guard as integrations (no private or internal addresses, size and time limits), records the checksum and stores the snapshot. Later changes at the URL have no effect until someone imports again, which creates a new version.

Export, import and packages

Controls are the asset type form_control in exports, packages and config as code. Exporting a form or workflow with its dependencies brings the control versions its fields use (module, manifest and checksum). On import, a control whose tag and version already exist with the same checksum is reused; a different checksum under the same version is refused. Approved network hosts and the trusted flag are not imported: an admin reviews them in the target workspace.

API, MCP and CLI

The API reference, MCP tools and CLI commands pages list the exact parameters.

Permissions

Marking a control trusted is an instance-admin setting.

Accessibility for control authors

The form is only as accessible as its least accessible field. The accessibility checker checks a control's manifest and scans it in the preview; to pass WCAG 2.2 AA:

• Name and description. Use label as the accessible name (aria-label on the interactive element, or on its group) and link description and, while invalid, error with aria-describedby — both inside the shadow root. Keep accessibility.labelled_by_host true.
• Role and state. Use native elements where you can (<button>, <input>); otherwise give the right ARIA role (radiogroup / radio, slider, combobox, switch) with its states (aria-checked, aria-valuenow, aria-expanded), plus aria-required, aria-invalid, aria-readonly, aria-disabled.
• Keyboard. Everything works without a mouse, following the ARIA Authoring Practices pattern for the role (a radio group moves with the arrow keys and has one Tab stop). Document it in accessibility.keyboard. Use delegatesFocus: true or implement focus() so the label and Tab land on the right element.
• Focus visible. A 2 px outline in --ut-focus-ring with an offset, never outline: none without a replacement.
• Contrast. Text 4.5:1 against its background; borders, icons and the state of controls 3:1 (WCAG 1.4.11). Check both themes; --ut-muted-text is a safe outline colour, --ut-border is for decoration only.
• Target size. Pointer targets at least 24 × 24 px (2.5.8).
• Don't rely on colour alone, respect prefers-reduced-motion, and support forced-colors (Windows High Contrast) with system colours.
• States. disabled removes the control from the tab order; readonly keeps it focusable but unchangeable.

Troubleshooting

Related

• Forms — the designer, field types and the accessibility checker
• Custom workflow steps — the other kind of extension
• Workspace theme — where the theme tokens come from
• Packages — moving controls with forms and workflows