Reference

Write a field with setValue()

Writes a value into a field and dispatches the correct DOM event so watchers, validators, and visual state run as if a user typed.

Writes a value into a field and dispatches the correct DOM event so watchers, validators, and visual state run as if a user typed.

Signature

setValue(name: string, value: unknown): FormController

Parameters

Name Type Required Description
name string yes The name attribute of the target field.
value unknown yes The value to write. Coerced per field type.

Returns

The same FormController — chainable. Returns the controller unchanged when the field does not exist.

Behaviour by field type

Field type How value is applied
<input> (text-like: text, email, password, …) String(value) is assigned to field.value.
<input> (text-like) with name="foo[]" receiving an array One array element per input, in order: input[i].value = String(value[i]). Inputs beyond the array length are cleared to ''; extra array elements (more elements than inputs) are dropped.
<input type="checkbox"> (single) field.checked = String(value) === field.value.
<input type="checkbox"> (group with the same name) Each checkbox is checked if Array.isArray(value) includes its value, otherwise all unchecked.
<input type="radio"> (group with the same name) The radio whose value matches String(value) is checked.
<input type="file"> File inputs are read-only — setValue cannot assign a file. Passing [] clears the input.
<select> (single) String(value) must match an option value.
<select multiple> Every option whose value occurs in the supplied array is selected. A scalar selects its matching option.
<select> (group with name="foo[]") receiving an array One array element per select, in order: select[i].value = String(value[i]). Inputs beyond the array length are cleared to ''; extra array elements are dropped.
<textarea> String(value) is assigned to field.value.
<textarea> (group with name="foo[]") receiving an array One array element per textarea, in order: textarea[i].value = String(value[i]). Inputs beyond the array length are cleared to ''; extra array elements are dropped.

After writing, the controller dispatches one synthetic input event on the first matching field.

The synthetic event flows through the form-level delegated listener, so the rest of the pipeline runs as if the user had typed: manual errors are cleared (default), validation runs (if autoValidate), watchers fire, subscribers are notified, and autoSubmit is scheduled.

Examples

Set a text value

import { form } from '@samline/forms'

const contact = form('contact-form')
contact.setValue('email', 'hello@example.com')

Toggle checkboxes

const signup = form('signup-form')

// Multiple values — array form.
signup.setValue('interests', ['design', 'code'])

// Single value — string form.
signup.setValue('terms', 'yes')

Select a radio

const shipping = form('shipping-form')
shipping.setValue('method', 'express')

Reset a file input

const upload = form('upload-form')
upload.setValue('attachments', [])

Chain with other setup

form('contact-form').setValue('subject', 'Question about pricing').setValue('message', 'Hello,')

Distribute values across a name="foo[]" group

const signup = form('signup-form')

// Each input gets one array element, in order. With two inputs and
// `name="docusign_email[]"`, this writes the first email to the first
// input and the second email to the second input.
signup.setValue('docusign_email[]', ['a@example.com', 'b@example.com'])

// When the array is shorter than the input count, the surplus inputs
// are cleared to ''.
signup.setValue('docusign_email[]', ['a@example.com'])

// When the array is longer than the input count, the extra array
// elements are dropped — there's no input to write to.
signup.setValue('docusign_email[]', ['a@example.com', 'b@example.com', 'c@example.com'])

Edge cases

  • The synthetic event is dispatched only on the first matching field. For radio/checkbox groups, this is intentional — the event bubbles, and the controller only needs to react once.
  • Passing null or undefined writes an empty string. This is treated as a value, not as “skip”, so the field becomes empty and watchers fire.
  • setValue is a no-op for unknown field names — the chain still works, but no event fires and no watchers run.
  • setValue cannot assign to <input type="file">. Browsers do not allow programmatic file assignment for security reasons. Use a DataTransfer or a real file picker.
  • The name="foo[]" suffix is the explicit opt-in for multi-value inputs. A field with the suffix that receives an array distributes one element per input (surplus inputs are cleared, surplus array elements are dropped). Bare names — name="foo" with multiple inputs — keep the original broadcast semantics and receive the same value on every matching input.
  • Manual errors for the field are cleared by default (because the synthetic event triggers the delegated handler). Pass clearManualErrorsOnChange: false to keep them.
  • getValue — read the current value.
  • getField — read the underlying DOM element.
  • reset — restore the form’s initial values.
  • format — when a field is formatted, setValue('<field>', x) writes the raw to the hidden mirror and reformats the visible; setValue('<field>_displayed', x) writes the formatted to the visible and recomputes the raw. See the mirror convention.