The Phormal instance

The Phormal instance is the main class of the library. For basic usage, please refer to Getting started.

If you're using the Vue 3 component, the documentation below for fields and config, match the prop names of the component.

An instance of Phormal is initialized through the Phormal constructor. It takes two arguments:

• fields, which is an object containing configuration for the fields of the form.
• config, which is an object containing configuration for the form itself.

For example:

import {Phormal} from "@phormal/core";
 
const fields = {/** see #fields section below */}, config = {/** see #config section below */};
 
new Phormal(fields, config);

fields

The fields argument is an object containing configuration for the fields of the form. The keys of the object are the names of the fields, and the values are the configuration for each field. If we want to create a basic form with two fields, name and email, the fields argument could look like this:

const fields = {
    name: {
        label: "Name"
    },
    birthdate: {
        label: "Email",
        placeholder: "john.doe@example.com"
    },
    newsletter: {
        label: "Subscribe to newsletter",
        type: "checkbox",
        value: false
    }
};

The configuration for each field can take the following properties:

In some cases, you might need to react to the native events of a field. This is possible through the properties handleOnClick, handleOnInput, handleOnChange, handleOnFocus and handleOnBlur. These properties take the shape of a function, where the first argument is the event itself. For example:

new Phormal(
  {
    lastName: {
      label: 'Last name',
      handleOnFocus: (event, field) => {
        console.log(event.target.value); // the value of the field
      }
    }
  },
  { /** form config */ }
)

In some even more rare cases, you might want to access the internal APIs of a field. Therefore, the above-mentioned event handlers pass the field as the second argument. For available methods on the field object, see FormFieldInterface (opens in a new tab).

Field conditions

Some properties of a form field can be set conditionally, depending on the value of other fields. If, for example, you have a field named email, but you only want to display it if the checkbox newsletter is checked, this can be achieved the following way:

const fields = {
  newsletter: {
    type: 'checkbox',
    label: 'Subscribe to newsletter'
  },
  email: {
    label: 'Email',
    hideIf: {
      newsletter: false
    }
  }
}

A field condition always consists of key-value pairs, where the key is the name of the field that your field should depend on, and the value is the condition. In this case the condition was a boolean. Accepted values of the condition are:

config

The second parameter of the Phormal constructor is the form configuration. These are its available properties:

Methods

$values()

Returns an object with key-value pairs, where each key is the name of the fields you specified, and the values are the values of those fields.

$validate()

Runs all validators for all fields. Returns true if the values of all fields are valid, and false otherwise.