A zero-dependency, framework-agnostic form state management library with a plugin-based validation system. Manage form fields, validate with customizable error messages, and extend with built-in validation rules, only importing what you need.

Installation

npm install @keysdown/form-wrapper --save

Importing

import {createForm} from '@keysdown/form-wrapper'

const form = ref(createForm({
    first_name: null,
    last_name: null,
    username: null
}))

// Or

import FormWrapper from '@keysdown/form-wrapper'

const form = ref(new FormWrapper({
    first_name: null,
    last_name: null,
    username: null
}))

Validation Plugins

Validation rules are loaded via a plugin system, no rules are bundled in core. This keeps the base library minimal and lets you import only what you need.

Loading all rules

Use the formValidation plugin to register all 33 validation rules at once:

import FormWrapper from '@keysdown/form-wrapper'
import formValidation from '@keysdown/form-wrapper/plugins/formValidation'

FormWrapper.extend(formValidation)

Default error messages with locales

Validation rules have built-in default error messages. By default, messages are in English. You can change the language by loading a locale:

import FormWrapper from '@keysdown/form-wrapper'
import formValidation from '@keysdown/form-wrapper/plugins/formValidation'
import pt from '@keysdown/form-wrapper/plugins/locales/pt'

FormWrapper.extend(formValidation)
FormWrapper.locale(pt) // switch to Portuguese

Available locales: en (English, default), pt (Portuguese), es (Spanish).

Default messages support interpolation, placeholders like :field, :min, :max, :size, :digits, :other, :values are replaced with actual values:

The first name field is required.
The password must be at least 6.

Custom field display names with attribute

By default, the :field placeholder uses the field name with underscores replaced by spaces (e.g., first_name → "first name"). You can customize this with the attribute property:

const form = new FormWrapper({
    email: {
        value: null,
        validation: {
            rules: ['required', 'email']
        },
        attribute: 'contact email'
    }
})

// Default error message would show:
// "The contact email field is required."
// instead of "The email field is required."

const form = new FormWrapper({
    password: {
        value: null,
        validation: {
            rules: ['required', 'min:8']
        },
        attribute: 'senha'
    }
})

// With pt locale: "O campo senha deve ter no mínimo 8."

User-provided messages always override default messages:

const form = new FormWrapper({
    email: {
        value: null,
        validation: {
            rules: ['required', 'email'],
            messages: {
                required: 'Email is required.' // overrides the default message
                // email uses the default locale message
            }
        }
    }
})

Tree-shaking individual rules

Import only the rules you need and use them directly in the rules array for tree-shaking:

import FormWrapper from '@keysdown/form-wrapper'
import { required, email } from '@keysdown/form-wrapper/plugins/rules'

const form = new FormWrapper({
    email: {
        value: null,
        validation: {
            rules: [required, email],
            messages: {
                required: 'The email field is required.',
                email: 'The email must be a valid address.'
            }
        }
    }
})

You can also mix function rules with string rules (useful for parameterized rules like min:6):

import { required, email } from '@keysdown/form-wrapper/plugins/rules'

rules: [required, email, 'min:6']

Custom rules

Add inline validation rules directly in the rules array. A custom rule receives a destructured object {value, fail, form, field}:

const form = createForm({
    email: {
        value: null,
        validation: {
            rules: [({value, fail}) => {
                if (!value) fail('The email field is required.')
            }]
        }
    }
})

Access other form fields via the form parameter:

const form = createForm({
    password: { value: null, validation: {rules: []} },
    password_confirmation: {
        value: null,
        validation: {
            rules: [({value, fail, form}) => {
                if (value !== form.password) fail('Passwords do not match.')
            }]
        }
    }
})

Custom rules support async validation (e.g., API calls):

const form = createForm({
    email: {
        value: null,
        validation: {
            rules: [async ({value, fail}) => {
                const response = await fetch(`/api/check-email?email=${encodeURIComponent(value)}`)
                const { available } = await response.json()
                if (!available) fail('This email is already taken.')
            }]
        }
    }
})

You can mix custom rules with built-in rules:

import { required, email } from '@keysdown/form-wrapper/plugins/rules'

const form = createForm({
    email: {
        value: null,
        validation: {
            rules: [
                required,
                email,
                async ({value, fail}) => {
                    const response = await fetch(`/api/check-email?email=${encodeURIComponent(value)}`)
                    const { available } = await response.json()
                    if (!available) fail('This email is already taken.')
                }
            ],
            messages: {
                required: 'The email field is required.',
                email: 'The email must be a valid address.'
            }
        }
    }
})

Static methods on FormWrapper

| Method | Description | |---|---| | FormWrapper.extend(plugin) | Register a plugin (e.g., formValidation) | | FormWrapper.addRule(name, handler) | Register a single validation rule | | FormWrapper.locale(locale) | Set the default error messages locale | | FormWrapper.rules | Static rule registry | | FormWrapper.defaultMessages | Static default messages registry |

Basic example

Basic example using Vue.

<template>
  <form @submit.prevent="submit">
    <input type="text" v-model="form.first_name"/>
    <input type="text" v-model="form.last_name"/>
    <input type="text" v-model="form.username"/>
    <button type="submit" :disabled="form.awaiting"/>
  </form>
</template>

<script setup lang="ts">
  import axios from 'axios'
  import {ref} from 'vue'
  import {createForm} from '@keysdown/form-wrapper'

  const form = ref(createForm({
    first_name: null,
    last_name: null,
    username: null
  }))

  const submit = () => {
    form.value.setAwaiting(true)

    axios.post('some-api', form.value.values())
        .then(({data}) => {
          form.value.reset()

          // ...
        })
        .catch(({errors}) => {
          form.value.errors.fill(errors)
          
          form.value.setAwaiting(false)
        })
  }
</script>

Basic example with validation

Basic example with validation using Vue.

<template>
  <form @submit.prevent="submit">
    <input type="text" v-model="form.first_name"/>
    <input type="text" v-model="form.last_name"/>
    <input type="text" v-model="form.username"/>
    <button type="submit" :disabled="form.awaiting"/>
  </form>
</template>

<script setup lang="ts">
  import axios from 'axios'
  import {ref} from 'vue'
  import FormWrapper from '@keysdown/form-wrapper'
  import formValidation from '@keysdown/form-wrapper/plugins/formValidation'

  FormWrapper.extend(formValidation)

  const form = ref(new FormWrapper({
    first_name: {
      value: null,
      validation: {
        rules: ['required'],
        messages: {
          required: 'The first name field is required.'
        }
      }
    },
    last_name: {
      value: null,
      validation: {
        rules: ['required'],
        messages: {
          required: 'The last name field is required.'
        }
      }
    },
    username: {
      value: null,
      validation: {
        rules: ['required', 'min:6'],
        messages: {
          required: 'The username field is required.',
          min: 'The username field must have at least 6 characters'
        }
      }
    }
  }))

  const submit = () => {
    form.value.validate()
        .then((form) => {
          form.setAwaiting(true)

          axios.post('some-api', form.values())
              .then(({data}) => {
                form.reset()

                // ...
              })
              .catch(({errors}) => {
                form.errors.fill(errors)

                form.setAwaiting(false)
              })
        })
        .catch((form) => {
          console.log('error')
        })
  }
</script>

Form methods

addField(field, value)

Method used to add a single field to the form.

form.addField('username', null)

form.addField('username', {
    value: null,
    validation: {
        rules: ['required'],
        messages: {
            required: 'The username field is required.'
        }
    }
})

addFields(fields)

Method used to add multiple fields to the form.

form.addFields({
    full_name: null,
    username: null
})

form.addFields({
    full_name: {
        value: null,
        validation: {
            rules: ['required'],
            messages: {
                required: 'The full name field is required.'
            }
        }
    },
    username: {
        value: null,
        validation: {
            rules: ['required'],
            messages: {
                required: 'The username field is required.'
            }
        }
    }
})

fill(data, updateOriginalValues = false)

Method used when you want to fill in several form fields at once.

const form = createForm({
    username: null
})

console.log(form.values()) // {username: null}

form.fill({
    username: 'keysdown'
})

console.log(form.values()) // {username: 'keysdown'}

removeField(field)

Method used when you want to remove a field from the form.

const form = createForm({
    username: null
})

console.log(form.values()) // {username: null}

form.removeField('username')

console.log(form.values()) // {}

removeFields(fields)

Method used to remove multiple fields to the form.

const form = createForm({
    username: null
})

console.log(form.values()) // {username: null}

form.removeFields(['username'])

console.log(form.values()) // {}

reset()

Method used to reset all form values to original state.

const form = createForm({
    username: null
})

form.username = 'keysdown'

console.log(form.values()) // {username: 'keysdown'}

form.reset()

console.log(form.values()) // {username: null}

wasChanged(field)

Method used to check if one or more fields have been changed from their original values. When an array is provided, returns true if any of the fields were changed.

const form = createForm({
    name: null,
    username: null
})

console.log(form.wasChanged('username')) // false

form.username = 'keysdown'

console.log(form.wasChanged('username')) // true

console.log(form.wasChanged(['name', 'username'])) // true (any changed)

filled(field, strict = true)

Method used to check if one or more fields are filled (not null, not undefined, not empty string '').

• strict: true (default) — When an array is provided, returns true only if all fields are filled.
• strict: false — When an array is provided, returns true if at least one field is filled.

const form = createForm({
    name: null,
    username: null
})

form.username = 'keysdown'

console.log(form.filled('username')) // true

console.log(form.filled('name')) // false

console.log(form.filled(['name', 'username'])) // false (name is not filled)

console.log(form.filled(['name', 'username'], false)) // true (username is filled)

setAwaiting(awaiting = true)

Method used to change the form loading state.

const form = createForm({
    username: null
})

console.log(form.awaiting) // false

form.setAwaiting()

console.log(form.awaiting) // true

form.setAwaiting(false)

console.log(form.awaiting) // false

validate(field = null)

Method used to validate the entire form or a specific field.

const form = createForm({
    username: {
        value: null,
        validation: {
            rules: ['required'],
            messages: {
                required: 'The username field is required.'
            }
        }
    }
})

form.validate('username')
    .then(() => {
        //...
    })
    .catch(() => {
        //...
    })

form.validate()
    .then((form) => {
        form.setAwaiting(true)

        // ...
    })
    .catch((form) => {
        console.log('error')
    })

validateField(field)

Method used to validate a specific field.

const form = createForm({
    username: {
        value: null,
        validation: {
            rules: ['required'],
            messages: {
                required: 'The username field is required.'
            }
        }
    }
})

form.validateField('username')
    .then(() => {
        //...
    })
    .catch(() => {
        //...
    })

// Same as:

form.validate('username')
    .then(() => {
        //...
    })
    .catch(() => {
        //...
    })

validateForm()

Method used to validate the entire form.

const form = createForm({
    username: {
        value: null,
        validation: {
            rules: ['required'],
            messages: {
                required: 'The username field is required.'
            }
        }
    }
})

form.validateForm()
    .then((form) => {
        //...
    })
    .catch((form) => {
        //...
    })

// Same as:

form.validate()
    .then((form) => {
        form.setAwaiting(true)

        // ...
    })
    .catch((form) => {
        console.log('error')
    })

values()

Method used to access all form values in json format.

const form = createForm({
    username: null
})

form.username = 'keysdown'

axios.post('some-api', form.values())

Filtering values

It is also possible to filter all accessed form values.

const form = createForm({
    first_name: null,
    last_name: null
})

form.first_name = 'keysdown'

axios.post('some-api', form.values(['first_name']))

filledValues()

Method used to access form values, excluding fields with null, undefined, or '' (empty string) values.

const form = createForm({
    username: null,
    email: null,
    role: 'admin'
})

form.username = 'keysdown'

axios.post('some-api', form.filledValues())
// sends { username: 'keysdown', role: 'admin' }

Note that 0 and false are considered filled values and will be included.

Filtering values

It is also possible to filter which fields are considered.

const form = createForm({
    first_name: null,
    last_name: null,
    role: 'admin'
})

form.first_name = 'keysdown'

axios.post('some-api', form.filledValues(['first_name', 'last_name']))
// sends { first_name: 'keysdown' }

valuesAsFormData()

Method used to access all form values as form data.

const form = createForm({
    username: null
})

form.username = 'keysdown'

axios.post('some-api', form.valuesAsFormData(), {
    headers: {
        'Content-Type': 'multipart/form-data'
    }
})

Filtering values

It is also possible to filter all accessed form values.

const form = createForm({
    first_name: null,
    last_name: null
})

form.first_name = 'keysdown'

axios.post('some-api', form.valuesAsFormData(['first_name']))

Validation

There is a property in the form object dedicated to validations, you can access everything related to validations through the validation property:

form.validation.errors.all()

form.validation.messages.all()

form.validation.rules.all()

You can also use the following shortcuts:

form.errors.all()

form.messages.all()

form.rules.all()

Validation collections

Both errors, messages and rules work using collections, the methods for managing collections are as follows:

all()

Returns all items in the collection.

form.errors.all()
form.messages.all()
form.rules.all()

first(key)

Returns the first item in the collection.

form.errors.first('username')
form.messages.first('username')
form.rules.first('username')

get(key)

Returns the value for the given key, or null if not found.

form.errors.get('username')
form.messages.get('username')
form.rules.get('username')

any()

Returns true if the collection has any items and false if it is empty.

form.errors.any()
form.messages.any()
form.rules.any()

fill(items)

Inserts values into a collection, replacing any previous values.

form.errors.fill({
    username: [
        'The username field is required.'
    ]
})

form.messages.fill({
    username: {
        required: 'The username field is required.'
    }
})

form.rules.fill({
    username: ['required']
})

push(key, data)

Inserts a single value into an item in a collection.

form.errors.push('username', 'The username field is required.')

form.messages.push('username', {
    required: 'The username field is required.'
})

form.rules.push('username', ['required'])

has(key)

Checking if the collection has an item with the key. Accepts a single key or an array of keys. When an array is provided, returns true if any of the keys exist.

form.errors.has('username')
form.errors.has(['username', 'email'])
form.messages.has('username')
form.rules.has('username')

unset(key)

Remove an item from the collection.

form.errors.unset('username')
form.messages.unset('username')
form.rules.unset('username')

clear()

Clears the entire collection, making it empty.

form.errors.clear()
form.messages.clear()
form.rules.clear()

Validation rules

The formValidation plugin provides 33 validation rules. Rules are loaded via plugins, see Validation Plugins for setup instructions.

| Rule | Parameters | Description | |---|---|---| | required | — | Field must be present and not empty | | email | — | Must be a valid email address | | url | — | Must be a valid URL | | min | min:6 | Minimum length (string) or value (number) or count (array) | | max | max:255 | Maximum length/value/count | | between | between:1,10 | Between min and max | | size | size:10 | Exact length/value/count | | alpha | — | Only alphabetic characters | | alphaNumeric | — | Only letters and numbers | | string | — | Must be a string | | integer | — | Must be an integer | | numeric | — | Must be numeric | | array | — | Must be an array | | boolean | — | Must be boolean (true, false, 0, 1, '0', '1') | | date | — | Must be a valid date | | same | same:field | Must match another field | | different | different:field | Must differ from another field | | confirmed | confirmed:field | Must match field_confirmation | | in | in:admin,user | Value must be in list | | notIn | notIn:admin,user | Value must not be in list | | regex | regex:/pattern/ | Must match regex pattern | | startsWith | startsWith:foo,bar | Must start with one of the values | | endsWith | endsWith:foo,bar | Must end with one of the values | | digits | digits:4 | Must have exactly N digits | | digitsBetween | digitsBetween:3,6 | Must have between min and max digits | | ip | — | Must be a valid IP (v4 or v6) | | json | — | Must be a valid JSON string | | uuid | — | Must be a valid UUID | | lessThan | lessThan:field | Numeric value less than another field | | greaterThan | greaterThan:field | Numeric value greater than another field | | lessThanOrEqual | lessThanOrEqual:field | Less than or equal to another field | | greaterThanOrEqual | greaterThanOrEqual:field | Greater than or equal to another field | | nullable | — | Allows null/empty (always passes) |

License

MIT