The Phormal instance

The Phormal instance is the main class of the library. 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.

If you're using a framework adapter like the React adapter, the fields and config arguments are simply passed to the useForm function.

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.

$reset()

If called with no arguments, this method resets all fields to their initial values. You can also specify the name of your different fields as arguments to the method. This will then only reset the specified fields. For example:

const phormal = new Phormal({
  name: {
    label: 'Name'
  },
  email: {
    label: 'Email'
  },
  password: {
    label: 'Password'
  }
})
 
phormal.$reset('email', 'password') // resets only the fields 'email' and 'password'

Properties

$isDirty

Returns true if the value of any field has been changed since initializing the form, and false otherwise.

$errors

Returns an object with key-value pairs, where the key refers to the name of the field, and the value is an array of errors that currently apply to the field.