- Docs
- Find controls with getField()
Find controls with getField()
Returns the DOM control or controls for a field name: null, one element, or an array for radios, checkbox groups and repeated fields.
Returns the underlying DOM field(s) for a given name. Useful when you need direct DOM access — for example, to focus a field, attach a third-party widget, or read custom attributes.
Signature
getField(name: string): FormFieldElement | FormFieldElement[] | null
type FormFieldElement = HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
name |
string |
yes | The name attribute of the target field. |
Returns
- A single
FormFieldElementwhen exactly one matching field exists. - An array of
FormFieldElementwhen multiple fields share the samename(radios, checkbox groups). nullwhen no field with thatnameexists.
Behaviour
- The lookup is performed against the live DOM, including dynamically added fields (the
MutationObserverkeeps the cache fresh). - The returned element(s) are live references — mutations you make to them are reflected in the form, but they bypass the controller’s normal pipeline. If you want watchers and validation to run, prefer
setValue.
Examples
Focus a field after submit
import { form } from '@samline/forms'
const profile = form('profile-form')
profile.onSubmit(async (_element, _data, formData) => {
const response = await fetch('/profile', { method: 'POST', body: formData })
if (response.status === 422) {
const field = profile.getField('email') as HTMLInputElement | null
field?.focus()
}
})
Iterate a radio group
const shipping = form('shipping-form')
const radios = shipping.getField('method')
if (Array.isArray(radios)) {
for (const radio of radios) {
radio.addEventListener('change', () => console.log(radio.value))
}
}
Read a custom data attribute
const profile = form('profile-form')
const field = profile.getField('avatar') as HTMLInputElement | null
const maxSize = Number(field?.dataset.maxSize ?? '0')
Edge cases
nullmeans “no field with that name” — distinct from[]which means “no matching fields but the lookup ran”.- The array form is only used when more than one field matches. A single checkbox that happens to be a group of one is still returned as a single element, not an array.
getFielddoes not throw when the controller has no bound form — it returnsnull.
Related
getValue— read the value.setValue— write a value through the controller.format— when a field is formatted,getField('<field>')returns the hidden raw mirror andgetField('<field>_displayed')returns the visible input. See the mirror convention.