A multi-step form component library built with React and Emotion styling

React Emotion Multi-step Form

A multi-step form component library built with React and styled with Emotion.

A declarative component library where input components are displayed in a multi-step form format with smooth page transitions. It's built with React hooks and React Context API so that form state and input prop values can be reused for UI customization.

Features

• Declarative display configuration - captions, page height, input icon and input validation
• Smooth/Optimized page transition animations
• Accessible keyboard-only navigation
• Responsive design
• Custom hook to access form state and input prop values for UI customization
• Supports SVG icons imported as React components (using SVGR that's built-in with Create-React-App)
• Three Input Components:
  1. HTML Input with HTML5 form validation
  2. Single-select Input - Radio Input with declarative configuration of radio options
  3. Multi-select Input - Multi-select Combobox with Autocomplete and Typeahead

Getting Started

Peer Dependencies

The following packages are required to be installed as dependencies for using this library:

• react: ^16.8.0
• react-dom": ^16.8.0
• react-scripts: ^3.4.0
• @emotion/core: ^10.0.27
• @emotion/styled: ^10.0.27
• emotion-theming: ^10.0.27

Installation

npm install --save react-emotion-multi-step-form

Basic Usage

import React from "react";
import {
  useInputs,
  FormBody,
  Input,
  RadioControl,
  RadioOption,
  withFormContextAndTheme,
} from "react-emotion-multi-step-form";

// Import SVG icons as React components using SVGR (built-in with create-react-app)
import { ReactComponent as LinkIcon } from "./assets/link.svg";
import { ReactComponent as TreeIcon } from "./assets/tree.svg";
import { ReactComponent as PriceTagsIcon } from "./assets/price-tags.svg";

function App() {
  const { error } = useInputs(); // grab the active input's error message
  const handleSubmit = (data) => {
    console.log(data);
  };

  return (
    <div>
      <FormBody onSubmit={handleSubmit}>
        <Input
          name="firstname" // name of each input component must be unique
          icon={LinkIcon} // icon to be displayed beside input component
          validationRules={{ required: true }}
        />
        <Input
          name="lastname"
          icon={TreeIcon}
          validationRules={{ required: true }} // default error message
        />
        <RadioControl
          name="age"
          icon={PriceTagsIcon}
          validationRules={{ required: "Please select an age group" }} // custom error message
        >
          <RadioOption value="<15" />
          <RadioOption value="15-64" />
          <RadioOption value="≥65" />
        </RadioControl>
      </FormBody>
      <div style={{ textAlign: "center", color: "red" }}>{error.message}</div>
    </div>
  );
}

// Wrap component with React Context.Provider and Emotion ThemeProvider
export default withFormContextAndTheme(App);

Learn how to get started here or check out the CodeSandbox.

All Examples

Check out the following CodeSandbox examples:

• Basic Usage Example
• "Subscription Form" Example

API Reference

The components and custom hook described below are publicly exposed in the top-level module.

Components

• <FormBody>
• Input Components
  1. <Input>
  2. <RadioControl> and <RadioOption>
  3. <ComboBoxMulti>
• <Captions>

HOCs & Hooks

• withFormContextAndTheme HOC
• useInputs hook

<FormBody>

The main component provided by the module which includes the body of the form, icon container, input container, navigation buttons, Tabs component and the Submit button. The icon container contains the icon of the currently active (displayed) input and the input container contains the active input (only one input can be active at a time). On click of the Next button, the active input is validated and the next input is made active if validation passes. The Submit button appears after the last input has been validated.

Props

Children

FormBody currently only accepts input components from this module as children. These input components will be contained within the input container and be displayed one at a time depending on which input is active.

  <FormBody onSubmit={handleSubmit}>
    <Input name="firstname" />
    <Input name="lastname" />
  </FormBody>

Input Components

This module provides the following custom input components to be used as form inputs within FormBody.

1. <Input>
2. <RadioControl> and <RadioOption>
3. <ComboBoxMulti>

These input components all share the following props in common which allow them to be registered in FormContext and displayed appropriately:

Base Props

Importing SVG Icons As React Components

Refer to the section in the Create React App documentation on adding SVGs.

Validation Rules

Input validation rules are passed as an object prop into each input component. The object contains the following key-value pairs where the key is the rule name and the value describes the validation criteria and/or the custom error message. The following table lists all of the available validation rules that validationRules can contain for all input components:

Note: Additional HTML5 validation rules can be defined for the <Input> component.

Example

  <ComboboxMulti
    name="interests"
    caption="What are your interests?"
    icon={PriceTagsIcon}
    validationRules={{
      validate: value => value.length >= 3 || 'Please select at least 3 topics.'
    }}
    options={options}
  />

<Input>

The component to be used for standard HTML inputs. It accepts the base props and the following props:

Props

HTML5 Validation Rules

In addition to the validation rules listed above, HTML5 validation rules can be specified for the <Input> component. The default error message for each HTML5 validation rule is the corresponding HTML5 validation message. Instead of a value, an object containing the value and a custom error message can be provided to replace the default HTML5 validation message.

The following table lists all of the available HTML5 validation rules that validationRules can contain for the <Input> component:

Note: Different HTML5 validation rules are supported by different input types according to this table.

Note: HTML5 validation is automatically performed on inputs based on the intrinsic constraints set by the type attribute (e.g. type="email" or type="URL").

Example

  <Input 
    name="username" 
    caption="Choose a username."
    icon={LinkIcon}
    validationRules={{ 
      required: 'Please enter a username for your new account.',
      pattern: {
        value: "[a-z]{4,8}",
        message: "Usernames must be lowercase letters and 4-8 characters in length."
      }
    }}
  />

<RadioControl> and <RadioOption>

The component to be used for radio inputs (single-select). <RadioControl> accepts the base props and accepts multiple <RadioOption> input components as children.

<RadioOption> accepts the following props:

Props (<RadioOption>)

Example

  <RadioControl
    name="frequency"
    caption="How often do you want to receive our newsletter?"
    icon={TreeIcon}
    validationRules={{ required: 'Please select a frequency' }}
  >
    <RadioOption value="daily" />
    <RadioOption value="weekly" />
    <RadioOption value="monthly" />
  </RadioControl>

<ComboboxMulti>

The component to be used for checkbox inputs (multi-select). It includes many features such as autocomplete/autofilter, typeahead, and tokens. The selected options will be stored as an array of strings. <ComboboxMulti> accepts the base props and the following props:

Props

Examples

If the checkbox options can be logically separated into multiple groups, then the array passed into the options prop should be in the following format:

const options = [
  ['fruits', 'vegetables', 'meats'],
  [
    [
      'papaya',
      'kiwi',
      'watermelon',
      'dragon fruit',
    ],
    [
      'brocolli',
      'spinach',
    ],
    [
      'chicken',
      'pork',
      'beef',
    ],
  ]
]

Otherwise, the array passed into the options prop should be in the following format:

const options = [
  ['colours'],
  [
    ['red', 'orange', 'yellow', 'green', 'blue', 'indigo', 'violet']
  ]
]

<Captions>

This component uses the useInputs hook to display the caption of the currently active input. It accepts the following props:

Props

withFormContextAndTheme HOC

This higher-order component (HOC) provides the wrapped component with access to the theme and FormContext which stores the form state. This HOC must be called with the parent component as follows:

const AppWithContextAndTheme = withFormContextAndTheme(App);
export default AppWithContextAndTheme;

Or simply:

export default withFormContextAndTheme(App);

useInputs Hook

This custom hook returns the following form state values from FormContext:

Returned Values

Example

These values and functions can be used, as follows, to create a custom component for navigating backwards to previous inputs in the form:

// All custom components not defined here are just styled components (Emotion) that only contain styling

// Labels component
const Labels = () => {
  const { inputs, activeIndex, changeActiveIndex, inputValues } = useInputs();

  return (
    <LabelsContainer>
      {(inputs.length > 0) ?
        inputs.map((input, index) => (
          <Label
            key={`${index}${input.name}`}
            label={input.label}
            inputValue={inputValues[input.name]}
            active={index === activeIndex}
            changeActiveIndex={() => changeActiveIndex(index)}
            activated={index < activeIndex}
          />
        ))
        : null // render null on initial form render
      }
    </LabelsContainer>
  )
}

// Label component
const Label = ({ 
  label, 
  inputValue, 
  active, 
  changeActiveIndex, 
  activated 
}) => {
  const handleClick = event => {
    if (!activated) return;
    changeActiveIndex();
  }

  return (
    <StyledLabel
      active={active} // for styling
      activated={activated} // for styling
      onClick={handleClick}
    >
      {inputValue || label}
    </StyledLabel>
  )
}

Feature Roadmap

• Web accessibility (WCAG 2.1 conformance)
• Test coverage
• Customizable theme/more props to customize styling
• More input components:

1. Range input (Slider)
2. Toggle/Switch input
3. Multi-select input - tag cloud format

• Ability to have multiple inputs on one page with declarative configuration
• Typescript support

Browser Support

Recent versions of the following browsers are supported:

• Chrome
• Firefox

GitHub