{"id":13468662,"url":"https://github.com/americanexpress/react-albus","last_synced_at":"2025-05-13T23:07:52.146Z","repository":{"id":40507673,"uuid":"82104729","full_name":"americanexpress/react-albus","owner":"americanexpress","description":"✨ React component library for building declarative multi-step flows.","archived":false,"fork":false,"pushed_at":"2024-10-29T16:10:21.000Z","size":1712,"stargazers_count":1109,"open_issues_count":16,"forks_count":91,"subscribers_count":30,"default_branch":"main","last_synced_at":"2025-05-05T17:31:54.688Z","etag":null,"topics":["multi-step","one-app","react","wizard"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/americanexpress.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-02-15T20:44:09.000Z","updated_at":"2025-04-03T19:09:06.000Z","dependencies_parsed_at":"2023-11-22T17:32:04.034Z","dependency_job_id":"2709451a-786f-4858-bcc2-1db75c6131ae","html_url":"https://github.com/americanexpress/react-albus","commit_stats":{"total_commits":65,"total_committers":19,"mean_commits":"3.4210526315789473","dds":0.6307692307692307,"last_synced_commit":"f2d04e8e8fd4bca6d8c69975f660ceb3e5e3780c"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/americanexpress%2Freact-albus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/americanexpress%2Freact-albus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/americanexpress%2Freact-albus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/americanexpress%2Freact-albus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/americanexpress","download_url":"https://codeload.github.com/americanexpress/react-albus/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253133137,"owners_count":21859110,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["multi-step","one-app","react","wizard"],"created_at":"2024-07-31T15:01:16.075Z","updated_at":"2025-05-13T23:07:47.132Z","avatar_url":"https://github.com/americanexpress.png","language":"JavaScript","funding_links":[],"categories":["Components","JavaScript","Libraries"],"sub_categories":["Misc"],"readme":"# React Albus · [![Build Status](https://img.shields.io/travis/americanexpress/react-albus/main.svg?style=flat)](https://travis-ci.org/americanexpress/react-albus) [![Coverage Status](https://coveralls.io/repos/github/americanexpress/react-albus/badge.svg?branch=main)](https://coveralls.io/github/americanexpress/react-albus?branch=main) [![npm version](https://img.shields.io/npm/v/react-albus.svg?style=flat)](https://www.npmjs.com/package/react-albus)\n\n\u003e “Let us `\u003cStep\u003e` into the night and pursue that flighty temptress, adventure.”\n\u003e\n\u003e \\-- _Albus Dumbledore_\n\n## 🤹‍ What is React Albus?\nReact 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.\n\nReact Albus is otherwise unopinionated and allows you to compose functionality such as routing, animation, and analytics however you see fit.\n\n## 💻 Installation\n\n```\nnpm install react-albus\n```\n\n## 📘 Example\n\n```jsx\nimport React from 'react';\nimport { Wizard, Steps, Step } from 'react-albus';\n\nconst Example = () =\u003e (\n  \u003cWizard\u003e\n    \u003cSteps\u003e\n      \u003cStep\n        id=\"merlin\"\n        render={({ next }) =\u003e (\n          \u003cdiv\u003e\n            \u003ch1\u003eMerlin\u003c/h1\u003e\n            \u003cbutton onClick={next}\u003eNext\u003c/button\u003e\n          \u003c/div\u003e\n        )}\n      /\u003e\n      \u003cStep\n        id=\"gandalf\"\n        render={({ next, previous }) =\u003e (\n          \u003cdiv\u003e\n            \u003ch1\u003eGandalf\u003c/h1\u003e\n            \u003cbutton onClick={next}\u003eNext\u003c/button\u003e\n            \u003cbutton onClick={previous}\u003ePrevious\u003c/button\u003e\n          \u003c/div\u003e\n        )}\n      /\u003e\n      \u003cStep\n        id=\"dumbledore\"\n        render={({ previous }) =\u003e (\n          \u003cdiv\u003e\n            \u003ch1\u003eDumbledore\u003c/h1\u003e\n            \u003cbutton onClick={previous}\u003ePrevious\u003c/button\u003e\n          \u003c/div\u003e\n        )}\n      /\u003e\n    \u003c/Steps\u003e\n  \u003c/Wizard\u003e\n);\n\nexport default Example;\n```\n## ✨ Demo\n\nCheck out the [demo page](https://americanexpress.io/react-albus)!\n\n## 🎛️ API\n\n- [`\u003cWizard\u003e`](#wizard)\n- [`\u003cSteps\u003e`](#steps)\n- [`\u003cStep\u003e`](#step)\n- [`withWizard`](#withwizard)\n- [`wizardShape`](#wizardShape)\n- [`context.wizard`](#contextwizard)\n\n---\n\n### `\u003cWizard\u003e`\n\n#### Props\n##### `onNext(wizard)`: function *(optional)*\nA function that will be called by `\u003cWizard\u003e` to determine the next step to proceed to.  An action must be taken within `onNext` to navigate to a `Step`.  To navigate to the next `Step`, use `push()`.\n\n##### Params\n\n* `wizard` (object): The [`context.wizard`](#contextwizard) object.\n\nIf you do not pass an `onNext` prop, `\u003cWizard\u003e` will proceed directly to the next step.\n\n##### `render(wizard)`: function *(optional)*\nA function that will be used as the render function of `\u003cWizard\u003e`.\n\n##### Params\n* `wizard` (object): The [`context.wizard`](#contextwizard) object.\n\n---\n\n### `\u003cSteps\u003e`\nWraps all of the `\u003cStep\u003e` components in your journey.  The only direct children of `\u003cSteps\u003e` should be `\u003cStep\u003e` components.\n\n#### Props\n##### `step`: object ***(optional)***\nAn object describing the current step with the structure: `{ id: string }`.  Defining a `step` prop will make `\u003cSteps\u003e` a [controlled component](https://facebook.github.io/react/docs/forms.html).\n\n------\n\n### `\u003cStep\u003e`\n\nWraps all the content that will be conditionally shown when the step is active.\n\n#### Props\n\n##### `id`: string\n\nUnique key for each step.\n\nIn addition to `id`, any additional props added to `\u003cStep\u003e` will be available on each `step` object.  This can be used to add names, descriptions, or other metadata to each step.\n\n`\u003cWithWizard\u003e` is an alias for `\u003cStep\u003e` that can be used to access [`context.wizard`](#contextwizard) anywhere within the `\u003cWizard\u003e` tree.\n\n---\n\n### `withWizard()`\nA higher order component that adds [`context.wizard`](#contextwizard) as a `wizard  ` prop on the wrapped component.\n\n---\n\n### `context.wizard`\n`\u003cWizard\u003e` provides an object on context with the following properties:\n\n* `step` (object): Describes the current step with structure: `{ id: string }`.\n* `steps` (array): Array of `step` objects in the order they were declared within `\u003cSteps\u003e`.\n* `history` (object): The backing [`history`](https://github.com/ReactTraining/history#properties) object.\n* `preserveQuery` (boolean): Whether or not to preserve the query string when navigating between steps.\n* `next()` (function): Moves to the next step in order.\n* `previous()` (function): Moves to the previous step in order.\n* `go(n)` (function): Moves `n` steps in history.\n* `push(id)` (function): Pushes the step with corresponding `id` onto history.  If no `id` is provided, the next step will be pushed onto history.\n* `replace(id)` (function): Replaces the current step in history with the step with corresponding `id`.\n* `set(id)` (function): Move to step `id`.\n\n## 📘 Usage with React Router\n\nInternally, React Albus uses [history](https://github.com/ReactTraining/history) to maintain the ordering of steps.  This makes integrating with React Router (or any other router) as easy as providing `\u003cWizard\u003e` with `history` and `basename` props.\n\n```jsx\nimport React from 'react';\nimport { Route } from 'react-router-dom';\nimport { Wizard } from 'react-albus';\n\nconst RoutedWizard = ({ children }) =\u003e\n  \u003cRoute\n    render={({ history, match: { url } }) =\u003e\n      \u003cWizard history={history} basename={url}\u003e\n        {children}\n      \u003c/Wizard\u003e}\n  /\u003e;\n\nexport default RoutedWizard;\n```\n\n\n## 🏆 Contributing\nWe 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](https://cla-assistant.io/americanexpress/react-albus).\n\n## 🗝️ License\nAny contributions made under this project will be governed by the [Apache License 2.0](https://github.com/americanexpress/react-albus/blob/master/LICENSE.txt).\n\n## 🗣️ Code of Conduct\nThis project adheres to the [American Express Community Guidelines](https://github.com/americanexpress/react-albus/wiki/Code-of-Conduct).\nBy participating, you are expected to honor these guidelines.\n\n[![Analytics](https://ga-beacon.appspot.com/UA-85897603-1/react-albus/README.md?useReferrer)](https://github.com/americanexpress/react-albus)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famericanexpress%2Freact-albus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Famericanexpress%2Freact-albus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famericanexpress%2Freact-albus/lists"}