Skip to content

formio/ai / plugin/skills/formio-form

formio-form

Verified

Embed and render Form.io forms in any web app with the `@formio/js` renderer — by URL or JSON, pre-filled, controlled from JavaScript — and own field behavior: conditionals, calculated values, JSON Logic validation, cascading selects. The default "embed a form" entry point. Use when the user asks to "embed a form", "render a form", "add this form to my page", "pre-fill a form", "show or hide a field based on another field", "calculate a field value", "add custom validation to a field", or add conditional wizard pages — field behavior in ANY framework's form stays here. Not for: Angular (see `formio-angular`) or React-named (see `formio-react`) embedding; building an app (see `formio-application`) or its data model (see `formio-resource-planner`); REST endpoints (see `formio-api`); the raw SDK (see `formio-sdk`); creating a new form (see `formio-form-builder`); agent-filled forms or chats (see `formio-uag`).

references/javascript-api.md

View on GitHub
# Controlling the Form with JavaScript

## Overview

`Formio.createForm` resolves to the form instance. Everything below hangs off that instance — keep the reference:

```js
const form = await Formio.createForm(el, srcOrJson, options);
```

## Events

Register handlers with `form.on(event, handler)`; remove with `form.off(event)`. The renderer's core events:

| Event | Fires when | Handler receives |
| --- | --- | --- |
| `change` | any component value changes (and once on initial load) | the changed submission (`{ data, ... }`) plus a change detail |
| `submit` | validation passes and, for a URL-backed form (a `src` URL, or a definition with an `action`), after the server has saved the submission | `(submission, saved)` — the server's response, including `_id`, when `saved` is true |
| `submitDone` | immediately after `submit`, only when the renderer saved the submission | the saved submission |
| `error` | submission failed validation or the server rejected it | the error(s) |

```js
form.on('change', (submission) => {
  console.log('data is now', submission.data);
});

form.on('submit', (submission) => {
  console.log('submitted', submission.data);
});

form.on('submitDone', (submission) => {
  console.log('saved with id', submission._id);
});

form.on('error', (errors) => {
  console.log('validation or server errors', errors);
});
```

Forms rendered from inline JSON have no server: `submit` still fires, but persisting the data is your handler's job. `submitDone` only fires for URL-backed forms.

## Reading and writing submission data

```js
// Read the current data.
const data = form.submission.data;

// Replace the submission (pre-fill). The property setter is asynchronous
// under the hood; await setSubmission when later code depends on the values.
form.submission = { data: { firstName: 'Jane' } };
await form.setSubmission({ data: { firstName: 'Jane' } });
```

## Working with components

`form.getComponent(key)` returns the live component instance for a key:

```js
const firstName = form.getComponent('firstName');
firstName.setValue('Jane'); // triggers change + validation
const value = firstName.getValue();
```

Component instances expose `setValue`, `getValue`, `disabled`, `visible`, `component` (the JSON schema), and `redraw()`. For bulk traversal use the Utilities documented in the `formio-sdk` skill (`references/utils-form-traversal.md`).

## Submitting programmatically

```js
form.submit();
```

Runs the `beforeSubmit` hooks and validation, saves to the server when the form is URL-backed, then emits `submit` and, when saved, `submitDone`. It returns a promise resolving to the (saved) submission and rejects with the errors when validation or the save fails, so `await form.submit()` when you need the result inline.

The full order is: `submitButton`, each component's `beforeSubmit`, `options.hooks.beforeSubmit`, validation, `options.hooks.customValidation`, the server save, `submit`, then `submitDone`; a failure emits `submitError` and then `error`. Because `submit` fires after the save, code that must run before it — adding a field, rejecting the submission — goes in `options.hooks.beforeSubmit` ([options.md](./options.md)), not in a `submit` handler.

## Other instance controls

```js
form.emit('customEvent', payload); // fire an event through the form
form.redraw(); // re-render after external mutation
form.destroy(); // tear down listeners before removing the element
```

## See also

- [rendering.md](./rendering.md) — obtaining the form instance.
- [options.md](./options.md) — options that change instance behavior.
- [wizards.md](./wizards.md) — wizard-specific navigation methods.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall