React material stepper

Implementation of Material Stepper for React. React material stepper encapsulates logic of step state maintianing, and provides API for control over the step resolution

Features

• Simple, declarative configuration
• Typescript typings
• Horizontal and vertical layouts
• Dynamic steps
• locking
• Default material themes provided
• Customizable by SCSS

Examples

• Simple horizontal stepper (source)
• Simple verical stepper (source)
• Full featured stepper (source)

Getting started

import Stepper, { Step } from "react-material-stepper";

const StepperExample = () => (
  <Stepper>
    <Step
      stepId={STEP1}
      data="Step 1 initial state"
      title="Step One"
      description="This step is optional"
    >
      <Step1 />
    </Step>
    <Step stepId={STEP2} title="Step Two" description="Login is required">
      <Step2 />
    </Step>
    <Step stepId={STEP3} title="Step Three" >
      <Step3 />
    </Step>
  </Stepper>
);

Example1: Basic stepper configuration, where Step1, Step2 and Step3 is arbitary user defined components

In order to work with stepper API StepperContext could be used:

import {
  StepperAction,
  StepperContent,
  StepperContext
} from "react-material-stepper";

export const STEP1 = "step-one";

const Step1 = ({ vertical = false }) => {
  const { resolve, getData } = React.useContext(StepperContext);

  const data = getData(STEP1);

  const onSubmit = (event: React.FormEvent) => {
    event.preventDefault();
    // resolve will set data for current step and proceed to the next step
    resolve("step1 resolved data");
  };

  return (
    <StepperContent
      onSubmit={onSubmit}
      actions={
        <StepperAction align="right" type="submit">
          Continue
        </StepperAction>
      }
    >
      Step1 resolved:
      <pre>{data}</pre>
    </StepperContent>
  );
};

Example2: StepperContext allows step data resolution. Saved data is accessible by getData method

API

Stepper

| Prop | Type | Description | |-------------|-------------------------------------|----------------------------------------------------------------------| | initialStep | string | number | Stets initital step by StepId | | onResolve | (stepId) => {} | Callback that will be executed on each step resolution | | onReject | (stepId) => {} | Callback that will be executed on each step rejection | | contextRef | MutableRefObject | Stepper controller reference | | className | string | Custom classname will be added to the root stepper container | | vertical | boolean | Indicates either horizontal or vertical steppr layout should be used |

Step

<Step
  stepId="2"
  title="Step Two"
  loading={isLoading(STEP2)}
  description="Login is required"
>
  ...
</Step>

Example3: Step component describes step configuration

| Prop | Type | Description | |-------------|-----------------|--------------------------------------------------| | title* | string | Step title. Required | | stepId* | string | number | Unique step identifier. Required | | children* | ReactNode | React component that will be rendered when step is activated. Required | | description | string | Step description or hint. Optional | | loading | boolean | Indicates whether step content is beign loading. | | disabled | boolean | Indicates whether step is beign disabled | | data | any | Initial state of step | | className | string | Custom classname | | index | number | Step index |

StepperContext

Provides API for control over stepper

| Prop | Type | Description | |----------------|------------------------------|-------------------------------------------------------------------| | updateStep | (stepId, state) => {} | Updates step state by id. | | goAt | stepId => {} | Activates certain step at provided stepId | | resolve | data => {} | Resolves current step with provided data | | reject | (message, description) => {} | Rejects current step with error and description | | isLoading | () => boolean | Indicates whether any of stepper steps is being loading | | getCurrentStep | () => StepState | Returns current step state | | getStep | stepId => StepState | Returns step state by stepId | | getData | (stepId, fallback) | Returns step data, fallback is used when step data is not defined |

StepperContent

StepperContent extends form interface, Could be used in custom steps for convenience and styling. Additionally StepperContent accept actions prop, that will be rendered in the footer of stepper content

StepperAction

StepperAction extends button interface, Could be used in custom steps for convenience and styling. Additionally StepperAction accept align ('left' or 'right') prop.

Customization

As part of material theme

$mdc-theme-primary: #fcb8ab;
$mdc-theme-secondary: #feeae6;
$mdc-theme-on-primary: #442b2d;
$mdc-theme-on-secondary: #442b2d;

@import "react-material-stepper/src/index.scss";
@import "material-components-web/material-components-web";

By SCSS variables

$stepper-color-hover: lightblue;
$stepper-color-index: darkblue;
$stepper-color-success: green;
$stepper-color-error: red;
$stepper-color-connector: cornflowerblue;
$stepper-header-height-horizontal: 64px;

@import "react-material-stepper/src/index.scss";

By CSS override

Stepper components allows passing custom className, and use it for override existing styles by applying css rules

import 'react-material-stepper/dist/react-stepper.css';

<Stepper className="custom-theme">
  <Step
    stepId={STEP1}
    title="Step One"
  >
    <Step1 />
  </Step>
  ...
</Stepper>

.stepper.custom-theme {
  background: red;
}