Forms Reference

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

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).

  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.

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

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).

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

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.

  <template id="custom-input">
    <div class="field">
      <label for="input-element"></label>
      <input id="input-element" ref="input" type="text" value placeholder>
    </div>
  </template>
  
  &lt;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('')
        })
      }
    })
  &lt;/script&gt;

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

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.

  onFormReset(() => {
    state.value = initialDefaultValue
    setFormValue(state.value)
    setValidity({})
  })

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

  onFormDisabled((isDisabled) => {
    state.disabled = isDisabled
    if (refs.input) {
      refs.input.disabled = isDisabled
    }
  })

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'.

  onFormRestore((restoredValue, reason) => {
    if (restoredValue) {
      state.value = restoredValue
      setFormValue(restoredValue)
    }
  })