enform

    2.3.0 • Public • Published

    Handle React forms with joy


    moubi Language grade: JavaScript moubi moubi moubi

    UsageExamplesAPIContributeLicense

    <Enform /> helps you manage:

    • form validation
    • form dirty state
    • form submission and reset
    • field values and changes
    • error messages

    Forms in React are common source of frustration and code repetition. Enform moves that hassle out of the way.

    ✔️ Check the docs with live demos or jump to the basic usage.

    So, another form component?

    Many form libraries are after wide range of use cases. As a result they grow in size bigger than the few form components one may ever need to handle. Enform is built for most common use cases without going to the edge. Thanks to that it remains small, but very powerful.

    Basic usage

    import React from "react";
    import Enform from "enform";
     
    const App = () => (
      <div>
        <h1>Simple form</h1>
        <Enform
          initial={{ name: "" }}
          validation={{ name: values => values.name === "" }}
        >
          {props => (
            <div>
              <input
                className={props.errors.name ? "error" : ""}
                type="text"
                value={props.values.name}
                onChange={e => {
                  props.onChange("name", e.target.value);
                }}
              />
              <button onClick={props.onSubmit}>Submit</button>
            </div>
          )}
        </Enform>
      </div>
    );

    Edit Basic form with enform

    View more intereactive examples here.

    This ⚠️ note on re-rendering gives answers to some common questions about auto updating field values based on changes in the initial prop.

    Install

    yarn add enform
    

    Requirements ✅

    Enform is using React hooks ↩ as per v2.0.0.

    Consumer projects should have react >= 16.8.0 (the one with hooks) in order to use it.

    API

    Component props

    Prop Type Required Description
    children function yes Function that your need to wrap your DOM with. It accepts the props object to help with form state manipulation.
    initial object yes Initial form field values in a form of { fieldName: value, ... }.
    validation object no Validation for the fields. It takes the form of { fieldName: function(values), ... } where function(values) accepts all form field values and should return an error message or truthy value. Example: { username: values => values.username === "" ? "This field is required" : false }.

    ✔️ Read more about these props here.

    State Api

    Enform exposes its handy Api by passing an object down to the function wrapper.

    <Enform initial={{ name: "" }}>
      {props => (
        <form />
          ...
        </form>
      )}
    </Enform>

    The props object contains 2 data items:

    prop Description
    values               Current field values - { fieldName: value, ... }.
    errors               Current field errors - { fieldName: errorMessage, ... }.

    and these 8 methods:

    method Description
    onChange Updates single field's value - onChange(fieldName, value). The value is usually what what comes from e.target.value. Side effects: clears previously set field error.
    onSubmit onSubmit(successCallback). Usually attached to a button click or directly to <form /> onSubmit. successCallback(values) will only be executed if all validations pass. Side effects: triggers validation or calls successCallback.
    reset Empties form elements.
    isDirty Reports if the form is dirty. It takes into account the initial field values passed to <Enform />.
    validateField     Triggers single form field validation - validateField(fieldName).
    clearError Clears single form field's error - clearError(fieldName).
    clearErrors Clears all errors in the form.
    setErrors Sets Enform's internal error state directly. This may be handy when props.errors needs to be updated based on an API call (async) and not on user input. Example: setErrors({ email: "Example error message" }, ...)

    props.values get updated with onChange and reset calls.

    props.errors get updated with onChange, onSubmit, reset, validateField, clearError, clearErrors and setErrors calls.

    ✔️ See more details about Enform's state API.

    Documentation

    Docs has its own home here. It further expands on the topics covered previously. Many examples and how to guides for variety of use cases take place on its pages too. Ref to this ⚠️ note on re-rendering for a common pitfall case.

    Development

    Run tests with jest in watch mode

    yarn test
    

    or no watch

    yarn test:nowatch
    

    Get gzip size by

    yarn size
    

    Build with

    yarn build
    

    That will pipe src/Enform.js through babel and put it as index.js under lib/ folder.

    Contributing

    You are welcome to open pull requests, issues with bug reports (use codesandbox) and suggestions or simply tweet about Enform. Check the relavant guides here.

    Immediate and fun contrubution: help create more usable examples. Is it a full-fetured form, third party integration or a filter form with bunch of options - feel free fork the basic form in codesandbox.

    Inspiration

    Enform is inspired by my experience with form refactoring, @jaredpalmer's great work on Formik and the way @kamranahmedse's presented driver.js.

    Authors

    Miroslav Nikolov (@moubi)

    License

    MIT

    Install

    npm i enform

    DownloadsWeekly Downloads

    39

    Version

    2.3.0

    License

    MIT

    Unpacked Size

    564 kB

    Total Files

    20

    Last publish

    Collaborators

    • moubi