hackworks-forms

A custom component for React & ChakraUI which renders forms dynamically based on a provided array of objects representing form elements.

Please note that has been developed as an internal tool and is not intended for public consumption.

Usage

Install it:

npm install @hackworks/forms

OR

yarn add @hackworks/forms

Import it:

import { Form } from '@hackworks/forms'

Use it:

return (
    <>
      <Form schema={formSchema} onSubmit={onSubmit} buttonText="Submit" />
    </>
  );

Dependencies

The Form component utilizes React Hook Form to simplify the form building and management process, and Yup, combined with the RHF Yup Resolver, for form validation. In addition, forms are built using components from Chakra UI.

https://react-hook-form.com/

https://github.com/jquense/yup

Details

The Form component requires three props:

• @param {array} schema Array of objects where each object represents a form element to be rendered
• @param {function} onSubmit The function used to handle the form submission
• @param {string} buttonText The text to be displayed on the submit button.

There are also a number of optional props:

• @param {function} handleValues A function that will be invoked using the results of getValues() as its argument. Useful if form values need to handled in a manner separate from standard form submission. If handle values is passed, an additional button appears next to the Submit button.
• @param {string} valuesButtonText The text to be displayed on the secondary button (i.e. the button that retrieves form values)
• @param {boolean} validateWithYup If true, a Yup validation schema will be built using any Yup methods that are present in the schema objects. If false, validation will fall back to react-hook-form. In this case, it is important to note that any fields deemed to be REQUIRED have the required boolean present in the corresponding schema object.

The element schema should be in the following format:

  const schema = [
    {type: String, name: String, label: String, helperText: String, options: [String, String, ...], order: Number, variant: String, resolver: Array, required: Boolean, styles: Object}
    {...},
    {...}
  ];

Each object in the array represents a form element to be rendered. Type is the kind of form element to be rendered, name is the name/id of the element, label is the label for the field (if not provided, a label is generated based on the provided name string), helperText provides direction/clarification to the user, and order is where in the form the element should be positioned.

Options is a property unique to select and radio elements and is used to construct the list of choices that the user can pick from.

Variant is an optional property that denotes what type of INPUT element should be rendered (e.g. date, time, file, etc.). If no variant is specified, the input defaults to text.

Resolver is an optional property that defines what Yup validation to apply to a form element. It is an array of arrays, where the first value in each array is a Yup validation method, and any additional value is the argument to supply to the validation method.

Required is used as a flag to signal to Chakra UI that the required field decorator and appropriate aria attributes should be applied.

Styles contains additional props to be applied to the Chakra UI form element (e.g. placeholder for an input element).

An example schema is below:

  const schema = [
    {
      type: 'input',
      name: 'event_name',
      label: 'Event Name',
      helperText: 'This is an example',
      order: 1,
      resolver: [['yup.string'], ['yup.required', 'Name is required']],
      required: true,
      styles: {placeholder: 'Please provide your name'}
    },
    { type: 'input', name: 'URL', order: 2 },
    { type: 'input', name: 'location', order: 3 },
    { type: 'input', name: 'start_date', order: 4, variant: 'datetime-local' },
    { type: 'input', name: 'end_date', order: 5, variant: 'datetime-local' },
    { type: 'input', name: 'banner_upload', order: 6, variant: 'file' },
    { type: 'input', name: 'card_upload', order: 7, variant: 'file' },
    {
      type: 'select',
      name: 'event_visibility',
      options: ['public', 'private'],
      order: 8,
    },
  ];

Additional Features

The Form component also supports the React Hook Form watch method. To enable the watching of a form, pass in a function, watchValues, to return the values to parent component.

The function will be invoked via useEffect whenever the watched fields change in value.

Styling

<Form> renders a Chakara <Stack> component, and as such any props that are accepted by the Chakra <Stack> component can be passed to <Form>.

Additionally, the buttonProps and valuesButtonProps props accept an object of Chakra UI button props to be passed to the button. See: https://chakra-ui.com/docs/form/button for supported button props.

Supported Elements:

<Form> currently supports five different form elements:

• Input (with support for standard HTML input types)
  • HWInput
  • 'input'
• Select
  • HWSelect
  • 'select'
• Text Area
  • HWTextArea
  • 'textarea'
• Radio
  • HWRadio
  • 'radio'
• Checkbox
  • HWCheckbox
  • 'checkbox'
• File/Upload
  • HWFile
  • 'file'
• Heading
  • HWHeading
  • 'heading'