<HeadlessForm /> component

UsageAPI

EncolaJS provides a component wrapper (HeadlessForm) for complete control over your form's UI while maintaining robust state management and validation capabilities.

📔 For a complete working example check out the headless components example

Basic example

The HeadlessForm component wraps useForm with a Vue component interface:

<template>
  <HeadlessForm
    :data="formData"
    :validator="validator"
    :submit-handler="handleSubmit"
    @submit_success="handleSuccess"
    @submit_error="handleError"
    @validation_fail="handleValidationError"
    @field_changed="handleFieldChange"
    @field_focused="handleFieldFocus"
    @field_blurred="handleFieldBlur"
    @form_initialized="handleInitialized"
    @reset="handleReset"
  >
    <template v-slot="form">
      <!-- Form content goes here -->
      <div>
        <label for="name">Name</label>
        <input id="name" v-model="form.name" />
        <div v-if="form['name.$errors'].length">
          {{ form['name.$errors'][0] }}
        </div>
      </div>

      <button type="submit">Submit</button>
      <button type="button" @click="form.reset">Reset</button>
    </template>
  </HeadlessForm>
</template>

<script setup>
import { reactive } from 'vue';
import { HeadlessForm } from '@encolajs/enforma';
import { createEncolaValidator } from '@encolajs/enforma/validators/encola';

const formData = reactive({
  name: '',
  email: ''
});

const validator = createEncolaValidator({
  name: 'required',
  email: 'required|email'
});

async function handleSubmit(data, formController) {
  // Handle submission
}

function handleSuccess(data, formController) {
  // Handle successful submission
}

function handleError(error, formController) {
  // Handle submission error
}

function handleFieldChange(path, value, fieldController, formController) {
  // Handle field change
}
</script>

DEPRECATED

The :rules and :customMessages props are deprecated in v1.3.0. Use the :validator prop instead.

Old way (deprecated):

<HeadlessForm :data="formData" :rules="{ email: 'required|email' }" />

New way (recommended):

<script setup>
import { createEncolaValidator } from '@encolajs/enforma/validators/encola'
const validator = createEncolaValidator({ email: 'required|email' })
</script>
<template>
  <HeadlessForm :data="formData" :validator="validator" />
</template>

See the Migration Guide for more details.