Forms and Fields

![NPM Version](https://www.npmjs.com/package/forms-and-fields)
!GitHub Workflow Status

A library for field validation and form submission.

Field elements are elements like input (of any type), select and textarea. Each field is defined by validation rules — validators.

You can use the required validator,
any validator from the validator library (e.g. isEmail),
the FileValidator or your own custom validators (including AJAX-based validation).

Usage

HTML:
``HTML


    
        Email:
        

        
    

    
        Password:

JS:`JS import { Form, Field, FieldStatus, FormStatus, SubmissionResult } from "forms-and-fields";

if (status === FieldStatus.Invalid) { fieldElement.insertAdjacentHTML( "afterend",

${validationResult.getMessage()}


                );
            }
        },
        onStatusChange: (
            status,
            validationResult,
            submissionResult,
            formElement
        ) => {
            if (status === FormStatus.No) {
                formElement.querySelector(".form-error")?.remove();
            }

if (status === FormStatus.NegativeSubmit) { formElement.insertAdjacentHTML( "beforeend",

${submissionResult.getMessage()}


                );
            }
            if (status === FormStatus.PositiveSubmit) {
                formElement.replaceWith("You are logged in");
            }
        }
    }
);

form.listen();`

You can experiment with the code above in CodePen.

More examples:

Find more examples in the sandbox.

`Installation`

npm install forms-and-fields

Or without installation and build tools:

`HTML`

`Documentation`

`$3`

To validate and submit a form, you need to create a Form object with Field objects (associated with the field elements), a submit function, and call its listen method.

Form validation involves validating all fields. A form is considered valid when all its fields are valid.

To validate an individual field (outside a form) you need to create a Field object and call its listen method.

When a user submits a form, validation is performed first. If the form passes validation, submission is then executed.

`$3`

Any custom validator must return a ValidationResult object. The internal validators return ValidationResult also.

#### ValidationResult class

| Method | Description | |-----------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | valid(resultDetails:object \| string = {}) | Static method. Creates a new valid result. The resultDetails object is expected to have the keys message and/or data. The resultDetailsstring is a message. | | invalid(resultDetails:object \| string = {}) | Static method. Creates a new invalid result. The resultDetails object is expected to have the keys message and/or data. The resultDetailsstring is a message. | | make(result:boolean, resultDetailsForInvalidCase: object \| string = {}, resultDetailsForValidCase: object \| string = {}) | Static method. Creates a new valid or invalid result depending on the result. | | isValid():bool | Returns trueif valid. | | isInvalid():bool | Returns trueif invalid. | | areValid(validationResults:ValidationResult[]): bool | Static method. Returns trueif all the specified validation results are valid. | | hasMessage():bool | Returns trueif a message exists. | | getMessage():string| Returns the message. | | getData():object | Returns the data. |

A form submit function must return a SubmissionResult object.

#### SubmissionResult class

| Method | Description | |---------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | positive(resultDetails:object \| string = {}) | Static method. Creates a new positive result. The resultDetails object is expected to have the keys message and/or data. The resultDetailsstring is a message. | | invalid(invalidData:object, data: object = {}) | Static method. Creates a new negative result with invalid data. The invalidData is an object in the following format: { [invalidFieldName]: message }, for groups: { [invalidFieldName.index]: message }, and for the entire form: {"*": message}. In this case, the form will set statuses and messages for the corresponding fields . | | negative(resultDetails:object \| string = {}) | Static method. Creates a new negative result. The resultDetails object is expected to have the keys message and/or data. The resultDetailsstring is a message. | | make(result:boolean, resultDetailsForNegativeCase: object \| string = {}, resultDetailsForPositiveCase: object \| string = {}) | Static method. Creates a new positive or negative result depending on the result. | | isPositive():boolean | Returns trueif positive. | | isNegative():boolean | Returns trueif negative. | | isValid():boolean | Returns true if valid (i.e., it was not created by the invalidmethod). | | isInvalid():boolean | Returns true if invalid (i.e., it was created by the invalidmethod). | | hasMessage():boolean | Returns trueif a message exists. | | getMessage():boolean| Returns the message. | | getData():object | Returns the data. |

`$3`

#### Field class

| Method | Description | |----------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | constructor (fieldSelector:string, containerSelector: string, validators: array = [], options: object = {}) | -fieldSelector: A selector to find the field element. -containerSelector: A selector to find the container element that contains the field element. Typically, this is the form selector. -validators: See the Field validators. -options: See the Field options. | | listen():() => void | Starts listening to events on the field element. This method must be called if the field is used outside of a form. Returns a function that stops listening. |

You can specify a CSS class for the field element and use it in the fieldSelectorparameter. For elements with the same name (e.g., radio buttons or a group of text input elements), use a singleFieldobject and specify a selector to find the first element. You can find examples in the sandbox.

You can also specify a CSS class for the container element containing the field element and use it in the containerSelector parameter. If the field element is inside a form, the container element should be the form itself.

#### Field validators

An array of validators. Each validator can be: - Astring: The name of the validator (e.g., required or any validator from the validator library, such as isEmail). - Afunction: A custom validator function that must return a ValidationResultobject. Can be promised. - Anobject with a validate method (that must return a ValidationResult object), such as the FileValidator (see Validation of files) or another custom object. Can be promised.

#### Field options

| Option | Type | Default | Description | |------------------------|------------|--------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | invalidMessages |object | {} | Messages for invalid values for each validator. For example: {isEmail: 'Invalid Email'}. | | defaultInvalidMessage |string | 'Invalid value.' | A default message for invalid values if no specific message is provided in the invalidMessages. | | trimEnabled |boolean | true| Specifies whether to trim the input value before validation. | | typingDelay |number| 1000 | The delay (in milliseconds) to consider a user as "typing" when the time between keystrokes is less than this value. | | validateOnChange |boolean | false| Specifies whether to validate the field when its value changes. | | validateOnType |boolean | false| Specifies whether to validate the field during typing. | | validatorParams |object | {} | Parameters for validator. For example: { isEmail: [{ allow_utf8_local_part: false }] }. | | validationCacheEnabled |boolean | true| Specifies whether to cache the validation result until the value changes. | | cssStatusEnabled |boolean | true| Specifies whether to add CSS classes when the status changes. | | onChange |function | NOOP | Triggered when the field value changes. Passed as arguments: value: any, fieldElement: HTMLElement, containerElement: Element. | | onTypingStart |function | NOOP | Triggered when the user starts typing. Passed as arguments: value: any, fieldElement: HTMLElement, containerElement: Element. | | onTypingEnd |function | NOOP | Triggered when the user stops typing. Passed as arguments: value: any, fieldElement: HTMLElement, containerElement: Element. | | onBeforeValidate |function | NOOP | Triggered before field validation. Passed as arguments: fieldElement: HTMLElement, containerElement: Element. | | onAfterValidate |function | NOOP | Triggered after field validation. Passed as arguments: validationResult: ValidationResult, fieldElement: HTMLElement, containerElement: Element. | | onValidationError |function | NOOP | Triggered when an error occurs during validation. Passed as arguments: error: any, fieldElement: HTMLElement, containerElement: Element. | | onStatusChange |function | NOOP | Triggered when the field status changes. Passed as arguments: status: string, validationResult: ValidationResult \| null, fieldElement: HTMLElement, containerElement: Element, wrapperElement: HTMLElement \| null. | | onStatusReset |function | NOOP | Triggered when the field status resets. Passed as arguments: fieldElement: HTMLElement, containerElement: Element, wrapperElement: HTMLElement \| null. |

`$3`

#### Form class

| Method | Description | |--------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | constructor(formSelector:string, fields: array, submit: function, options: object = {}) | -formSelector: A selector to find the form element. -fields: An array of Fieldobjects. -submit: A submit function, (a FormData object is passed as argument, must return a SubmissionResultobject), -options: See the Form options | | listen():() => void | Executes the listen method for all fields specified in the Form constructor and starts listening for the form submission event. This method must be called. Returns a function that stops listening. |

You can specify a CSS class for the form element and use it in the formSelector parameter.

#### Form options

The Form class supports all Field options and applies them to each field specified in the Form constructor. Field-specific options always take priority over form-level options.

Additionally, the Form class supports the following options:

| Option | Type | Default | Description | |------------------------|------------|---------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | cssStatusEnabled |boolean | true| Specifies whether to add CSS classes when the status changes. | | onBeforeValidate |function | NOOP | Triggered before form validation. Passed as argument: formElement: HTMLFormElement. | | validate |function | NOOP | An additional custom validation function, which must return a ValidationResult object. Passed as argument: formData: FormData. This is executed after field validation when all fields are valid. Can be promised. | | onAfterValidate |function | NOOP | Triggered after form validation. Passed as arguments: validationResult: { [fieldName]: ValidationResult, "*": ValidationResult }, formElement: HTMLFormElement. validationResultscontains the results for each field and the form itself. | | onValidationError |function | NOOP | Triggered when an error occurs during validation. Passed as arguments: error: any, formElement: HTMLFormElement. | | onBeforeSubmit |function | NOOP | Triggered before form submission. Passed as arguments: formData: FormData, formElement: HTMLFormElement. | | onAfterSubmit |function | NOOP | Triggered after form submission. Passed as arguments: submissionResult: SubmissionResult, formElement: HTMLFormElement. | | onSubmissionError |function | NOOP | Triggered when an error occurs during submission. Passed as arguments: error: any, formElement: HTMLFormElement. | | onStatusChange |function | NOOP | Triggered when the form status changes. Passed as arguments: status: string, validationResult: { [fieldName]: ValidationResult, "*": ValidationResult } \| null, submissionResult: SubmissionResult \| null, formElement: HTMLFormElement. | | onStatusReset |function | NOOP | Triggered when the form status resets. Passed as arguments: formElement: HTMLFormElement. | | onBeforeValidateField |function | NOOP | Triggered before validating any field specified in the Form constructor. Passed as arguments: fieldElement: HTMLElement, containerElement: Element. | | onAfterValidateField |function | NOOP | Triggered after validating any field specified in the Form constructor. Passed as arguments: validationResult: ValidationResult, fieldElement: HTMLElement, containerElement: Element. | | onFieldValidationError |function | NOOP | Triggered when an error occurs while validating any field specified in the Form constructor. Passed as arguments: error: any, fieldElement: HTMLElement, containerElement: Element. | | onFieldStatusChange |function | NOOP | Triggered when a status of any field specified in the Form constructor changes. Passed as arguments: status: string, validationResult: ValidationResult \| null, fieldElement: HTMLElement, containerElement: Element, wrapperElement: HTMLElement \| null. | | onFieldStatusReset |function | NOOP | Triggered when a status of any field specified in the Form constructor resets. Passed as arguments: fieldElement: HTMLElement, containerElement: Element, wrapperElement: HTMLElement \| null. |

#### Important

The next options are intended for the entire form: -onBeforeValidate-onAfterValidate-onValidationError-onStatusChange-onStatusReset

If you want to apply them to each field specified in the Form constructor use:

- onBeforeValidateField-onAfterValidateField-onFieldValidationError-onFieldStatusChange-onFieldStatusReset

`$3`

Use the FileValidator for file validation. See an example of usage in the sandbox.

The FileValidator constructor accepts two objects: rules and invalidMessages.

| Rule | Example | Related option for invalid message | Allowed placeholders | |--------------------|------------------------------|------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------| | maxSize (in bytes) |1073741824 | maxSize | {file}, {fileSize}, {fileSizeInKib}, {fileSizeInMiB}, {fileSizeInGiB}, {maxSize}, {maxSizeInKiB}, {maxSizeInMiB}, {maxSizeInGiB}| | allowedMimeTypes |['image/jpg', 'image/png'] | allowedMimeTypes | {file}, {fileMimeType}, {allowedMimeTypes}| | allowedExtensions |['.jpg', '.png'] | allowedExtensions | {file}, {allowedExtensions}| | maxCount |3 | maxCount | {maxCount} |

Example:

`JS new Field('.js-file', '.js-container', [ new FileValidator({ maxSize: 536870912, allowedMimeTypes: ['image/jpg'] }, { maxSize: 'The size of {file} must be less than {maxSizeInMiB} MiB.' }); ])`

`$3`

Use a single Field object for radio buttons with the same name:

HTML:`HTML


    
    Man
    
    Woman

JS:`JS import { Form, Field, SubmissionResult } from "forms-and-fields";

const form = new Form( ".js-form", [ new Field(".js-sex", ".js-form", ["required"]), ], (formData) => SubmissionResult.positive()}, );

form.listen();`

`$3`

Sometimes it's necessary to add fields with the same name, for example, a group of addresses. In this case, use the data-group-field attribute and a single Field object:

HTML:`HTML


    
        Address 1:
        

        
    

    
        Address 2:

JS:`JS import { Form, Field, SubmissionResult } from "forms-and-fields"

const form = new Form( ".js-form", [ new Field(".js-address", ".js-form", ["required"]), ], (formData) => SubmissionResult.positive()}, )

form.listen()`

Important! Don't use the data-group-field attribute for radio buttons.

`$3`

The statuses of forms and fields change during validation and submission. You can subscribe to these events via onStatusChange.

List of statuses:

- FieldStatus.Validating ("ff-field-validating") -FieldStatus.Valid ("ff-field-valid") -FieldStatus.Invalid ("ff-field-invalid") -FormStatus.Validating ("ff-form-validating") -FormStatus.Valid ("ff-form-valid") -FormStatus.Invalid ("ff-form-invalid") -FormStatus.Submitting ("ff-form-submitting") -FormStatus.PositiveSubmit ("ff-form-positive-submit") -FormStatus.NegativeSubmit ("ff-form-negative-submit")

Also, by default, statuses are dynamically added as CSS classes to form and field elements.

You can wrap any field element in a container with the data-field-wrapperattribute then the classes will then be applied to this wrapper instead of the field element itself. This is particularly useful for checkboxes and radio buttons. To disable adding CSS classes, setcssStatusEnabled to false.

The onResetStatus callback can be useful for clearing form or field errors that were set using the onAfterValidate or onAfterSubmit` callbacks, for example.

License

This library is released under the MIT license.

Forms and Fields

![NPM Version](https://www.npmjs.com/package/forms-and-fields)
!GitHub Workflow Status

A library for field validation and form submission.

Field elements are elements like input (of any type), select and textarea. Each field is defined by validation rules — validators.

You can use the required validator,
any validator from the validator library (e.g. isEmail),
the FileValidator or your own custom validators (including AJAX-based validation).

Usage

HTML:
``HTML


    
        Email:
        

        
    

    
        Password:

JS:`JS import { Form, Field, FieldStatus, FormStatus, SubmissionResult } from "forms-and-fields";

if (status === FieldStatus.Invalid) { fieldElement.insertAdjacentHTML( "afterend",

${validationResult.getMessage()}


                );
            }
        },
        onStatusChange: (
            status,
            validationResult,
            submissionResult,
            formElement
        ) => {
            if (status === FormStatus.No) {
                formElement.querySelector(".form-error")?.remove();
            }

if (status === FormStatus.NegativeSubmit) { formElement.insertAdjacentHTML( "beforeend",

${submissionResult.getMessage()}


                );
            }
            if (status === FormStatus.PositiveSubmit) {
                formElement.replaceWith("You are logged in");
            }
        }
    }
);

form.listen();`

You can experiment with the code above in CodePen.

More examples:

Find more examples in the sandbox.

`Installation`

npm install forms-and-fields

Or without installation and build tools:

`HTML`

`Documentation`

`$3`

To validate and submit a form, you need to create a Form object with Field objects (associated with the field elements), a submit function, and call its listen method.

Form validation involves validating all fields. A form is considered valid when all its fields are valid.

To validate an individual field (outside a form) you need to create a Field object and call its listen method.

When a user submits a form, validation is performed first. If the form passes validation, submission is then executed.

`$3`

Any custom validator must return a ValidationResult object. The internal validators return ValidationResult also.

#### ValidationResult class

A form submit function must return a SubmissionResult object.

#### SubmissionResult class

`$3`

#### Field class

#### Field validators

#### Field options

`$3`

#### Form class

You can specify a CSS class for the form element and use it in the formSelector parameter.

#### Form options

The Form class supports all Field options and applies them to each field specified in the Form constructor. Field-specific options always take priority over form-level options.

Additionally, the Form class supports the following options:

#### Important

The next options are intended for the entire form: -onBeforeValidate-onAfterValidate-onValidationError-onStatusChange-onStatusReset

If you want to apply them to each field specified in the Form constructor use:

- onBeforeValidateField-onAfterValidateField-onFieldValidationError-onFieldStatusChange-onFieldStatusReset

`$3`

Use the FileValidator for file validation. See an example of usage in the sandbox.

The FileValidator constructor accepts two objects: rules and invalidMessages.

Example:

`JS new Field('.js-file', '.js-container', [ new FileValidator({ maxSize: 536870912, allowedMimeTypes: ['image/jpg'] }, { maxSize: 'The size of {file} must be less than {maxSizeInMiB} MiB.' }); ])`

`$3`

Use a single Field object for radio buttons with the same name:

HTML:`HTML


    
    Man
    
    Woman

JS:`JS import { Form, Field, SubmissionResult } from "forms-and-fields";

const form = new Form( ".js-form", [ new Field(".js-sex", ".js-form", ["required"]), ], (formData) => SubmissionResult.positive()}, );

form.listen();`

`$3`

Sometimes it's necessary to add fields with the same name, for example, a group of addresses. In this case, use the data-group-field attribute and a single Field object:

HTML:`HTML


    
        Address 1:
        

        
    

    
        Address 2:

JS:`JS import { Form, Field, SubmissionResult } from "forms-and-fields"

const form = new Form( ".js-form", [ new Field(".js-address", ".js-form", ["required"]), ], (formData) => SubmissionResult.positive()}, )

form.listen()`

Important! Don't use the data-group-field attribute for radio buttons.

`$3`

The statuses of forms and fields change during validation and submission. You can subscribe to these events via onStatusChange.

List of statuses:

Also, by default, statuses are dynamically added as CSS classes to form and field elements.

The onResetStatus callback can be useful for clearing form or field errors that were set using the onAfterValidate or onAfterSubmit` callbacks, for example.

License

This library is released under the MIT license.

forms-and-fields

Forms and Fields

Usage

Installation

Documentation

$3

$3

$3

$3

$3

$3

$3

$3

License

forms-and-fields

Forms and Fields

Usage

Installation

Documentation

$3

$3

$3

$3

$3

$3

$3

$3

License

Dist Tags

`Installation`

`Documentation`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`Installation`

`Documentation`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`