Skip to content
React component library for building declarative multi-step flows.
JavaScript HTML
Branch: master
Clone or download
Latest commit e3056a2 Feb 23, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
__tests__ feat(v2): updates for React 16, external API tests, and removing all JSX Dec 4, 2017
docs feat(examples): track codesandbox examples Feb 23, 2018
examples
src feat(v2): updates for React 16, external API tests, and removing all JSX Dec 4, 2017
.babelrc Use `babel-preset-env`. Oct 12, 2017
.editorconfig 1.0.0 Mar 22, 2017
.eslintignore Step supports extra config props Aug 15, 2017
.eslintrc.js Step supports extra config props Aug 15, 2017
.gitignore
.travis.yml
LICENSE.txt 1.0.0 Mar 22, 2017
README.md fix(readme): fixed readme typo (#18) Feb 8, 2018
index.dev.js
index.html feat(examples): track codesandbox examples Feb 23, 2018
package.json feat(examples): track codesandbox examples Feb 23, 2018
webpack.config.babel.js feat(examples): track codesandbox examples Feb 23, 2018
yarn.lock feat(examples): track codesandbox examples Feb 23, 2018

README.md

React Albus · Build Status Coverage Status npm version

“Let us <Step> into the night and pursue that flighty temptress, adventure.”

-- Albus Dumbledore

What is React Albus?

React Albus is a React component library used to build declarative multi-step journeys (also known as Wizards). You define your step content and ordering and React Albus will manage the journey-related state for you.

React Albus is otherwise unopinionated and allows you to compose functionality such as routing, animation, and analytics however you see fit.

Installation

npm install react-albus

Example

import React from 'react';
import { Wizard, Steps, Step } from 'react-albus';

const Example = () => (
  <Wizard>
    <Steps>
      <Step
        id="merlin"
        render={({ next }) => (
          <div>
            <h1>Merlin</h1>
            <button onClick={next}>Next</button>
          </div>
        )}
      />
      <Step
        id="gandalf"
        render={({ next, previous }) => (
          <div>
            <h1>Gandalf</h1>
            <button onClick={next}>Next</button>
            <button onClick={previous}>Previous</button>
          </div>
        )}
      />
      <Step
        id="dumbledore"
        render={({ previous }) => (
          <div>
            <h1>Dumbledore</h1>
            <button onClick={previous}>Previous</button>
          </div>
        )}
      />
    </Steps>
  </Wizard>
);

export default Example;

Demo

Check out the demo page!

API


<Wizard>

Props

onNext(wizard): function (optional)

A function that will be called by <Wizard> to determine the next step to proceed to.

Params

If you do not pass an onNext prop, <Wizard> will proceed directly to the next step.

render(wizard): function (optional)

A function that will be used as the render function of <Wizard>.

Params

<Steps>

Wraps all of the <Step> components in your journey. The only direct children of <Steps> should be <Step> components.

Props

step: object (optional)

An object describing the current step with the structure: { id: string }. Defining a step prop will make <Steps> a controlled component.


<Step>

Wraps all the content that will be conditionally shown when the step is active.

Props

id: string

Unique key for each step.

In addition to id, any additional props added to <Step> will be available on each step object. This can be used to add names, descriptions, or other metadata to each step.

<WithWizard> is an alias for <Step> that can be used to access context.wizard anywhere within the <Wizard> tree.


withWizard()

A higher order component that adds context.wizard as a wizard prop on the wrapped component.


context.wizard

<Wizard> provides an object on context with the following properties:

  • step (object): Describes the current step with structure: { id: string }.
  • steps (array): Array of step objects in the order they were declared within <Steps>.
  • history (object): The backing history object.
  • next() (function): Moves to the next step in order.
  • previous() (function): Moves to the previous step in order.
  • go(n) (function): Moves n steps in history.
  • push(id) (function): Pushes the step with corresponding id onto history.
  • replace(id) (function): Replaces the current step in history with the step with corresponding id.

Usage with React Router

Internally, React Albus uses history to maintain the ordering of steps. This makes integrating with React Router (or any other router) as easy as providing <Wizard> with history and basename props.

import React from 'react';
import { Route } from 'react-router-dom';
import { Wizard } from 'react-albus';

const RoutedWizard = ({ children }) =>
  <Route
    render={({ history, match: { url } }) =>
      <Wizard history={history} basename={url}>
        {children}
      </Wizard>}
  />;

export default RoutedWizard;

Contributing

We welcome Your interest in the American Express Open Source Community on Github. Any Contributor to any Open Source Project managed by the American Express Open Source Community must accept and sign an Agreement indicating agreement to the terms below. Except for the rights granted in this Agreement to American Express and to recipients of software distributed by American Express, You reserve all right, title, and interest, if any, in and to Your Contributions. Please fill out the Agreement.

License

Any contributions made under this project will be governed by the Apache License 2.0.

Code of Conduct

This project adheres to the American Express Community Guidelines. By participating, you are expected to honor these guidelines.

Analytics

You can’t perform that action at this time.