@egodesign/form v1.8.0

EgoForm

Lightweight, dependency-free JavaScript/Typescript library for comprehensive form validation and submission. Customize validation rules with ease and seamlessly integrate into any vanilla project.

Main features:

• Comprehensive Validation: Supports various data types, custom validations, and minimum/maximum length checks.
• Customization: Control class names and error messages to match your design.
• Flexible Submission: Choose between fetch, get, or post methods for form submission.
• Event Handling: Respond to validation errors, form submission events, and successful/failed responses.
• TypeScript Support: Fully typed and well-documented.

Usage:

1. Download or install it using the most popular PMs:

npm install @egodesign/form

or

yarn add @egodesign/form

2. Import the EgoForm class into your file and create as many instances as needed.

import EgoForm from '@egodesign/form';

const myForm = new EgoForm({
    element: document.getElementById('myForm'),
    submitType: 'fetch',
    debug: true,
    submitDataFormat: 'formData',
    requestHeaders: {},
    fieldGroups: {
        phone_numbers: [
            'phone',
            'mobile'
        ]
    },
    extraFields: [
        {
            name: 'extra',
            value: 'value'
        }
    ],
    serializerIgnoreList: ['ignore'],
    classes: {
        requiredField: '--required',
        requiredIfFilledField: '--required-if-filled',
        fieldHasError: '--has-error',
        controlHasError: 'is-danger',
        hiddenErrorMessage: 'is-hidden',
        formSubmittingState: '--submitting',
        buttonSubmittingState: 'is-loading'
    },
    customValidations: {
        test: [{
            name: 'isValid',
            condition: (value) => value === 'testing',
            message: 'This field value should be "testing".'
        }]
    },
    customValidationsMessages: {
        "fieldName": {
            "empty": "message",
            "invalid": "message",
        }
    },
    onStepChange: (previous, next) => console.log(current, next),
    onBeforeSubmit: () => console.log('Before submit'),
    onValidationError: fields => console.log(fields),
    onSubmitStart: () => console.log('Submit start'),
    onSubmitEnd: () => console.log('Submit end'),
    onSuccess: resp => console.log('Success', resp),
    onError: err => console.log('Error', err)
});

import EgoForm from '@egodesign/form';

const myForm: EgoForm = new EgoForm({
    element: document.getElementById('myForm'),
    submitType: 'fetch',
    debug: true,
    submitDataFormat: 'formData',
    requestHeaders: {},
    fieldGroups: {
        phone_numbers: [
            'phone',
            'mobile'
        ]
    },
    extraFields: [
        {
            name: 'extra',
            value: 'value'
        }
    ],
    serializerIgnoreList: ['ignore'],
    classes: {
        requiredField: '--required',
        requiredIfFilledField: '--required-if-filled',
        fieldHasError: '--has-error',
        controlHasError: 'is-danger',
        hiddenErrorMessage: 'is-hidden',
        formSubmittingState: '--submitting',
        buttonSubmittingState: 'is-loading'
    },
    customValidations: {
        test: [{
            name: 'isValid',
            condition: (value: string | number) => value === 'testing',
            message: 'This field value should be "testing".'
        }]
    },
    customValidationsMessages: {
        "fieldName": {
            "empty": "message",
            "invalid": "message",
        }
    },
    onValidationError: (fields: string[], instance: EgoForm) => {
            console.log(instance, fields);
        },
        onStepChange: (prev: string, next: string) => console.log(prev, next),
        onSubmitStart: () => console.log('Submit start'),
        onSubmitEnd: () => console.log('Submit end'),
        onSuccess: (resp: Response) => console.log('Success', resp),
        onError: (err: Error) => console.log('Error', err)
});

HTML structure sample:

<form method="GET" action="https://jsonplaceholder.typicode.com/todos/1" id="myForm" novalidate>
    <div class="form__field --required" data-type="text">
        <label for="nameInput">Name</label>
        <input class="form__control" 
            type="text" 
            name="name" 
            id="nameInput" 
            placeholder="Text input"
            aria-invalid="false" 
            aria-errormessage="nameInputError"
            required>
            <p class="form__error" id="nameInputError"></p>
    </div>
    
    <div class="form__field --required" data-type="email">
        <label for="emailInput">Email</label>
        <input class="form__control" 
            type="email" 
            name="email" 
            id="emailInput" 
            placeholder="Email input"
            aria-invalid="false" 
            aria-errormessage="emailInputError"
            required>
        <p class="form__error" id="emailInputError"></p>
    </div>

    <div class="form__field" data-type="file" data-max-size="15">
        <label for="fileInput">File upload</label>
        <small>Max. file size 2MB</small>
        <input class="file-input form__control" 
            type="file" 
            name="resume"
            id="fileInput" 
            aria-invalid="false" 
            aria-errormessage="fileInputError">
        <p class="form__error" id="fileInputError"></p>
    </div>
    
    <div class="form__field" data-type="text">
        <label>Message</label>
        <textarea class="form__control" 
            name="message" 
            placeholder="Textarea"
            aria-errormessage="msgTextError">
        </textarea>
        <p class="form__error" id="msgTextError"></p>
    </div>
    
    <button type="submit">Submit</button>
</form>

Required Classes

Customizable Classes

Options

Events

Validation:

In order to use validations, you must set the correct data type for each field. You can do so by adding a type data attribute to the field element, e.g; <div class="form__field" data-type="text">. This attribute will be used by the validator to run certain tests. Here's a list of the different available data types: | Name | Description | | ---| --- | | text | This can be considered as the default type. It's use for simple text input and it doesn't have any special validation appart from the required ones. | | email | Used for email inputs. It validates the value to comply the requirement for a well formed email address. | | url | Used for URL inputs. It validates the value to comply the requirement for a well formed URL. | | cuit / cuil | It validates the value to comply the requirement for a valid CUIT or CUIL number, applying the official formula. | | password_repeat | Use this type alogn with a password field whit an ID of password, to validate that both fields have the same value. Mostly intended for password reset forms. | | single_checkbox | This type validates that a specific checkbox is checked. Useful for cases like terms and conditions acceptance. |

In addition you can validate the minimum and maximum length of a field. You can do so by adding the data-min-length and data-max-length attributes to the field element. | Attribute | Description | | ---| --- | | data-min-length | The minimum length of the field. | | data-max-length | The maximum length of the field. |

Masks:

Add this class names to the field element in order to apply some masks and filters to your inputs.

Extras

Toggle password visibility

Add a button with the class name form__toggle-password-visibility inside the field element to toggle the control (input) type between password and text. Note: the control and the button must be siblings.

Serialization

When the submitDataFormat option is set to json, EgoForm will serialize the form data using its own logic. For example, if any field with multiple values is present (like a select with the multiple attribute on) it will be serialized to an array.