forms-and-fields v3.0.0

Forms and Fields

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:

<form class="js-form">
    <div>
        <label for="email">Email:</label>
        <br />
        <input id="email" type="text" name="email" class="js-email" />
    </div>
    <div>
        <label for="password">Password:</label>
        <br />
        <input id="password" type="password" name="password" class="js-password" />
    </div>
    <br />
    <button type="submit">Login</button>
</form>

JS:

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

const form = new Form(
    ".js-form",
    [
        new Field(".js-email", ".js-form", ["required", "isEmail"]),
        new Field(".js-password", ".js-form", ["required"])
    ],
    (formData) => {
        const isOk =
            formData.get("email") === "test@example.com" &&
            formData.get("password") === "123456";
        return SubmissionResult.make(isOk, "Incorrect credentials");
    },
    {
        invalidMessages: {
            required: "This field is required",
            isEmail: "Invalid email"
        },
        onFieldStatusChange: (status, validationResult, fieldElement) => {
            if (status === FieldStatus.No) {
                fieldElement.parentNode.querySelector(".error")?.remove();
            }

            if (status === FieldStatus.Invalid) {
                fieldElement.insertAdjacentHTML(
                    "afterend",
                    `<div class="error">${validationResult.getMessage()}</div>`
                );
            }
        },
        onStatusChange: (
            status,
            validationResult,
            submissionResult,
            formElement
        ) => {
            if (status === FormStatus.No) {
                formElement.querySelector(".form-error")?.remove();
            }

            if (status === FormStatus.NegativeSubmit) {
                formElement.insertAdjacentHTML(
                    "beforeend",
                    `<div class="form-error"><br />${submissionResult.getMessage()}</div>`
                );
            }

            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:

<script type="module">
    import { Field } from 'https://esm.sh/forms-and-fields';
</script>

Documentation

Common

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.

Validation and Submission results

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

Fields

Field class

You can specify a CSS class for the field element and use it in the fieldSelector parameter. For elements with the same name (e.g., radio buttons or a group of text input elements), use a single Field object 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:

• A string: The name of the validator (e.g., required or any validator from the validator library, such as isEmail).
• A function: A custom validator function that must return a ValidationResult object. Can be promised.
• An object 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

Forms

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

Validation of files

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

The FileValidator constructor accepts two objects: rules and invalidMessages.

Example:

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

Radio buttons

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

HTML:

<form class="js-form">
    <input id="sex-man" type="radio" name="sex" class="js-sex" value="man" />
    <label for="sex-man">Man</label>
    <input id="sex-woman" type="radio" name="sex" class="js-sex" value="woman" />
    <label for="sex-woman">Woman</label>
    <button type="submit">Submit</button>
</form>

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

Groups

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:

<form class="js-form">
    <div>
        <label for="address-1">Address 1:</label>
        <br />
        <input id="address-1" type="text" name="address" class="js-address" data-group-field="" />
    </div>
    <div>
        <label for="address-2">Address 2:</label>
        <br />
        <input id="address-2" type="text" name="address" class="js-address" data-group-field="" />
    </div>
    <br />
    <button type="button">Add an address</button>
    <br />
    <button type="submit">Submit</button>
</form>

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.

Statuses

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-wrapper attribute 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, set cssStatusEnabled 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.