rolling-fields

Image by gnokii - Open Clipart, CC0

A simple library that dynamically generates fields for your React form.

Use rolling-fields to create forms on-the-fly from a field definition stored outside your deployed code and read in at runtime.

How you build your field schema is upto you. It could be a simple as a JSON file or an API call that fetches your field schema from a database.

rolling-fields also enables you make your form even more dynamic by loading different fields depending on the values a user selects inside the form.

rolling-fields is designed to be used within Formik or plain React forms.

To find out more about the benefits of using rolling-fields, check out this Rolling Your Own Dynamic Forms blog post.

Usage

Basic

import DynamicFieldBuilder from 'rolling-fields';

   const fields = [
      { name: 'green field' },
      { name: 'open field', type: 'password' },
      { type: 'submit', text: 'Submit' },
    ];

   <form>
    <DynamicFieldBuilder fields={fields} />
   </form>

renders:

 <form>
  <input name="green field" />
  <input name="open field" type="password" />
  <button type="submit">Submit</button>
 </form>

Props

  <DynamicFieldBuilder
    fields={} // Array of field objects
    mappings={} // Optional object to define how to render different types of fields
    fieldContext={} // Optional value that will be shared among all fields when using custom mappping
    onBlur={}
    onChange={}
    setFieldValue={} // Use for custom input that does not support HTML SyntheticEvent
  />

If no custom mappings are supplied, default mappings will be used.

Custom mappings

  const MyCustomInput = ({ name }) => (
    <input name={name} className="custom"> Something cool! </input>
    )

   const fields = [
      { name: 'green field' },
      { name: 'open field', type: 'custom' },
      { name: 'hide', type: 'invisible', },
      { name: 'show' type: 'visible', },
      { type: 'submit', text: 'Just do it!' },
    ];
    
    const mappings = {
      string: ({ name }) => (
        <input name={name} className="string-field" />
      ),
      custom: ({ name }) => (
        <MyCustomComponent name={name} />
      ),
      invisible: ({ name }, fieldContext) => !fieldContext.isVisible && (
        <input name={name} />
      ),
      visible: ({ name }, fieldContext) => fieldContext.isVisible && (
        <input name={name} />
      ),
      submit: ({ name, text }) => (
        <button type="submit" >{text}</button>
      ),
    };
    
  <form>
    <DynamicFieldBuilder
        fields={fields}
        mappings={mappings}
        fieldContext={{ isVisible: true }}
        />
  </form>

renders:

 <form>
  <input name="green field" class="string-field" />
  <input name="open field" class="custom"> Something cool! </input>
  <input name="show" />
  <button type="submit">Just do it!</button>
 </form>

Installation

npm i rolling-fields

Running the tests

Clone this repository and run

npm install

You can run the mocha unit tests with

npm test

Running storybook

You can run storybook locally using:

npm run storybook

License

This project is licensed under the MIT License - see the LICENSE file for details

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

Contribution

This project is brought to you by Tes engineers. Check out contributors who participated in this project.

If you have improvements to offer, please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.