GitHub v1.3.1

Forms Reference

Reference

Complete reference for Form-Associated Custom Elements (FACE), ElementInternals integration, setFormValue, setValidity, and form lifecycle hooks in Coralite.

This reference documents Coralite's support for standard web platform Form-Associated Custom Elements (FACE), ElementInternals synchronization, and native form lifecycle hooks.

1. Form-Associated Custom Elements (FACE)

By default, custom elements do not participate in native HTML <form> submission or constraint validation. Setting formAssociated: true in defineComponent opts the custom element into Form-Associated Custom Elements (FACE).

javascript
Code copied!
  import { defineComponent } from 'coralite'
  
  export default defineComponent({
    formAssociated: true,
  
    attributes: {
      name: String,
      value: String,
      required: Boolean
    }
  })

When formAssociated: true is enabled:

  • The custom element attaches W3C standard ElementInternals on host initialization.
  • The component participates directly in parent <form> submissions, including FormData collection.
  • The host element supports native form properties like element.form, element.validity, element.validationMessage, and element.checkValidity().
  • The framework injects FACE helper functions (setFormValue, setValidity, onFormReset, onFormDisabled, onFormRestore) into the component's client() execution context.

2. ElementInternals Helpers

The client() block context provides helper methods to sync internal component state and validation constraints with the surrounding form:

setFormValue(value)

Updates the entry value submitted for this component when its parent <form> submits. Accepts a string, File, or FormData instance (or null to clear value).

javascript
Code copied!
  // Sync a simple string input value
  setFormValue('user@example.com')
  
  // Clear the submitted form value
  setFormValue(null)

setValidity(flags, message, anchor)

Sets the constraint validation state on the element's ElementInternals instance.

  • flags — Validity state flags object (e.g. { valueMissing: true } or { customError: true }). Pass {} to mark the component valid.
  • message — Optional validation error message string displayed by browser popups or validationMessage property.
  • anchor — Optional internal element reference (e.g. refs.input) targeted for browser focus during validation reporting.

Complete Custom Input Example

html
Code copied!
  <template id="custom-input">
    <div class="field">
      <label for="input-element">{{ label }}</label>
      <input id="input-element" ref="input" type="text" value="{{ value }}" placeholder="{{ placeholder }}">
    </div>
  </template>
  
  <script type="module">
    import { defineComponent } from 'coralite'
  
    export default defineComponent({
      formAssociated: true,
  
      attributes: {
        label: String,
        placeholder: String,
        value: {
          type: String,
          default: ''
        },
        required: Boolean
      },
  
      client ({ state, refs, signal, setFormValue, setValidity, onFormReset }) {
        function validate (val) {
          if (state.required && !val) {
            setValidity({ valueMissing: true }, 'This field is required', refs.input)
          } else {
            setValidity({})
          }
        }
  
        // Initial synchronization
        setFormValue(state.value)
        validate(state.value)
  
        // Sync state and validity on DOM input events
        if (refs.input) {
          refs.input.addEventListener('input', (e) => {
            state.value = e.target.value
            setFormValue(state.value)
            validate(state.value)
          }, { signal })
        }
  
        // Handle native form reset
        onFormReset(() => {
          state.value = ''
          if (refs.input) {
            refs.input.value = ''
          }
          setFormValue('')
          validate('')
        })
      }
    })
  </script>

3. Form Lifecycle Hooks

Form-Associated components receive lifecycle hooks to react to native form events triggered by user actions or browser restoration:

onFormReset(callback)

Fires when the enclosing <form> element is reset via a reset button or form.reset() call. Use this hook to restore internal component state and form values back to initial defaults.

javascript
Code copied!
  onFormReset(() => {
    state.value = initialDefaultValue
    setFormValue(state.value)
    setValidity({})
  })

onFormDisabled(callback)

Fires whenever the component's disabled status changes, such as when an ancestor <fieldset disabled> is enabled or disabled. Receives boolean isDisabled argument.

javascript
Code copied!
  onFormDisabled((isDisabled) => {
    state.disabled = isDisabled
    if (refs.input) {
      refs.input.disabled = isDisabled
    }
  })

onFormRestore(callback)

Fires when the browser automatically restores form state, such as during back/forward page navigation or auto-fill restoration. Receives (state, reason) where reason is either 'restore' or 'autocomplete'.

javascript
Code copied!
  onFormRestore((restoredValue, reason) => {
    if (restoredValue) {
      state.value = restoredValue
      setFormValue(restoredValue)
    }
  })