Please note, that this library is still in its beta versions. You can use it in production, but be sure to check the changelogs in /packages/*/ (opens in a new tab) before updating the version of any Phormal package.

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


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: ""
    newsletter: {
        label: "Subscribe to newsletter",
        type: "checkbox",
        value: false

The configuration for each field can take the following properties:

PropertyType/Possible valuesDefault
typetext, select, checkbox, radiogroup, number, email, password, date, datetime-local, time'text'
placeholder (has no effect in material theme; label acts a placeholder)string''
valuestring (for most types) or boolean (for checkbox)'' or false
disabledIfSee field conditionsundefined
hideIfSee field conditionsundefined
rowCombine several fields visually into a flex row, by giving them the property row and assigning them a common string value of your choiceundefined
options (only for radiogroup and select)Array of options with type { label: string, value: string }[]
hooksArray of returned hooks
min (only for date, datetime-local, and time inputs)See MDN docs (opens in a new tab)
max (only for date, datetime-local, and time inputs)See MDN docs (opens in a new tab)

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(; // 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:

emptyCheck if the value of targeted field is an empty string
not-emptyCheck if the value of targeted field is a string with a length > 0
RegEx, e.g. /^US$/Test a regex
booleanConditionally do something, based on whether a field has the values true or false


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

elstringSelector of HTML element on which to mount the formyes-
themestringName of themenobasic
languagestringSet the language in which error messages should be shown, for example 'us' or 'de'. Should be of ISO 639-1 standard (opens in a new tab)noen
fallbackLanguagestringIf you dynamically set the language for the form, and the possibility remains, that this language is not yet supported by this library, you will want to set a fallback languagenoen
validationstringactive for automatic validation of form, on all user-input. passive for disabling automatic validationnoactive



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.


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


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'



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


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.

Last updated on January 26, 2023