README.md

Introduction

Multistep-form is an open-source lib written in React created by @Loft's software engineering team to facilitate the development of a multi-step form. It abstracts all the logic necessary for the form to work: next, previous and skip to step n, in addition to facilitating the calculation of progress.

Installation

To have access to multistep-form, simply install using npm:

npm i --save @loft/multistep-form

or yarn:

yarn add @loft/multistep-form

Usage

To make use of the facilities that the multistep-form provides, simply use the MultiStep component passing the steps configuration and your children will receive all the intelligence through the props:

import { MultiStep } from '@loft/multistep-form';

<MultiStep steps={steps} stepId={stepId}>
  {Children}
</MultiStep>;

or

import { MultiStep } from '@loft/multistep-form';

<MultiStep steps={steps} stepId={stepId}>
  {(props) => {
    /* Content */
  }}
</MultiStep>;

When using this component, a React context will be created that you can access using the useMultiStepContext hook:

import { useMultiStepContext } from '@loft/multistep-form';

const MyComponent = () => {
  const context = useMultiStepContext();

  return <Fragment>blah</Fragment>;
};

Properties accepted by the MultiStep component

Steps

The steps property is a list of configuration objects, it's the initial information regarding the steps of the form, here's an example:

const steps = [
  {
    id: 'first-step',
    Component: () => <p>I am a dummy component</p>,
  },
  {
    id: 'second-step',
    Component: () => <p>I am another dummy component</p>,
  },
  {
    id: 'jumped-step',
    Component: () => <p>I am a jumped step</p>,
  },
  {
    id: 'third-step',
    Component: () => <p>I am third dummy component</p>,
  },
];

As we can see in the example above, each step is composed of an id and a component may it be functional or not.

StepId

The stepId property is the identifier of the first step that will be displayed when rendering, it's optional and if it's not provided, the identifier of the first step of the configuration list is assumed, here is an example:

const stepId = 'second-step';

Properties injected by MultiStep into the children

Step

The step property injected by the MultiStep component is the current step the user is in, it's the following signature:

// Container component
const Container = ({ step: { id, Component, nextStepId }, next }) => {
  return (
    <Fragment>
      <p>
        You're in step with id <span>{id}</span>
      </p>
      <Component />
      {nextStepId && <button onClick={next}>Next</button>}
    </Fragment>
  );
};

// Using provider
const MyForm = () => {
  return <Multistep steps={steps}>{Container}</Multistep>;
};

Progress

The progress property injected by the MultiStep component is the progress of the steps completed by the user.

// Container component
const Container = ({
  progress: { first, current, last },
  step: { Component },
}) => {
  return (
    <Fragment>
      <p>
        You're in step <span>{current}</span>
        of the form that starts at <span>{first}</span>
        and ends at <span>{last}</span>
      </p>
      <Component />
    </Fragment>
  );
};

// Using provider
const MyForm = () => {
  return <Multistep steps={steps}>{Container}</Multistep>;
};

Methods injected by MultiStep into the children

Next

The next method is responsible for transitioning the step, it's linear, that is, the user will go to the next step provided in the configuration.

// Container component
const Container = ({ step: { Component }, next }) => {
  return (
    <Fragment>
      <Component />
      <button onClick={next}>Next</button>
    </Fragment>
  );
};

// Using provider
const MyForm = () => {
  return <Multistep steps={steps}>{Container}</Multistep>;
};

Previous

The previous method is useful for returning to the previous step.

// Container component
const Container = ({ step: { Component }, previous }) => {
  return (
    <Fragment>
      <Component />
      <button onClick={previous}>Previous</button>}
    </Fragment>
  );
};

// Using provider
const MyForm = () => {
  return <Multistep steps={steps}>{Container}</Multistep>;
};

JumpTo

The jumpTo method allows you to jump directly to a step, which can be before or after the current step.

// Container component
const Container = ({ step: { Component }, jumpTo }) => {
  return (
    <Fragment>
      <Component />
      <button onClick={() => jumpTo('third-step')}>Jump!</button>
    </Fragment>
  );
};

// Using provider
const MyForm = () => {
  return <Multistep steps={steps}>{Container}</Multistep>;
};

Examples

TBD

Extra informations

• How to contribute?
• Our code of conduct

Created using TSDX