{"id":13481393,"url":"https://github.com/KadoBOT/react-gizmo","last_synced_at":"2025-03-27T12:30:46.045Z","repository":{"id":108708212,"uuid":"120078074","full_name":"KadoBOT/react-gizmo","owner":"KadoBOT","description":"🦎 React Gizmo - UI Finite State Machine for React","archived":true,"fork":false,"pushed_at":"2018-07-17T00:53:54.000Z","size":172,"stargazers_count":39,"open_issues_count":0,"forks_count":5,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-04-14T05:33:57.564Z","etag":null,"topics":["flow","react","state-machine","transition","xstate"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/KadoBOT.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2018-02-03T09:38:18.000Z","updated_at":"2023-08-15T16:25:12.000Z","dependencies_parsed_at":"2023-04-13T19:07:52.324Z","dependency_job_id":null,"html_url":"https://github.com/KadoBOT/react-gizmo","commit_stats":{"total_commits":30,"total_committers":2,"mean_commits":15.0,"dds":0.4666666666666667,"last_synced_commit":"0a0491bd6b91e1492074182c883026a26f4c1164"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KadoBOT%2Freact-gizmo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KadoBOT%2Freact-gizmo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KadoBOT%2Freact-gizmo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KadoBOT%2Freact-gizmo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KadoBOT","download_url":"https://codeload.github.com/KadoBOT/react-gizmo/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245844805,"owners_count":20681781,"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":["flow","react","state-machine","transition","xstate"],"created_at":"2024-07-31T17:00:51.462Z","updated_at":"2025-03-27T12:30:45.740Z","avatar_url":"https://github.com/KadoBOT.png","language":"JavaScript","funding_links":[],"categories":["Components"],"sub_categories":["Data"],"readme":"# React Gizmo\n\nUI Finite State Machine for React\n\n![Gizmo](https://78.media.tumblr.com/7e86a0e90f263f2c1da0bc2f01b91d9a/tumblr_of8yz2A9Tk1rp0vkjo1_500.gif)\n\n#### React Gizmo is a cute State Machine that doesn't become a monster if you throw water on it\n\n# Quick Start\n\n## Installation\n\n```sh\nyarn add react-gizmo\n```\n\n## Usage\n\n### PS: `react-gizmo` uses new React Context API. React 16.3 is needed for this library to work.\n\n```js\nimport { Machine, State } from \"react-gizmo\";\n\nconst state = {\n\tinitialState: { text: \"Next\" },\n\tflow: {\n\t\tinitial: \"start\",\n\t\tstates: {\n\t\t\tstart: { on: { NEXT: \"end\" } },\n\t\t\tend: { on: { PREV: \"start\" } }\n\t\t}\n\t}\n};\n\nconst MachineApp = () =\u003e (\n\t\u003cMachine log state={state}\u003e\n\t\t\u003cApp /\u003e\n\t\u003c/Machine\u003e\n);\n\nReactDOM.render(\u003cMachineApp /\u003e, document.getElementById(\"root\"));\n```\n\nApp.js\n\n```js\nclass App extends Component {\n\trender() {\n\t\treturn (\n\t\t\t\u003cReact.Fragment\u003e\n\t\t\t\t\u003cState on=\"start\"\u003e\n\t\t\t\t\t\u003cButtonStart /\u003e\n\t\t\t\t\u003c/State\u003e\n\t\t\t\t\u003cState on=\"end\"\u003e\n\t\t\t\t\t\u003cButtonEnd /\u003e\n\t\t\t\t\u003c/State\u003e\n\t\t\t\u003c/React.Fragment\u003e\n\t\t);\n\t}\n}\n```\n\nButtonStart.js\n\n```js\nclass ButtonNext extends Component {\n\thandleOnClick = () =\u003e {\n\t\tthis.props.transition(\"NEXT\", {\n\t\t\toff: \"start\",\n\t\t\tsetState: { text: \"Prev\" }\n\t\t});\n\t};\n\n\trender() {\n\t\treturn \u003cbutton onClick={this.handleOnClick}\u003e{this.props.text}\u003c/button\u003e;\n\t}\n}\n```\n\nButtonPrev.js\n\n```js\nclass ButtonPrev extends Component {\n\thandleOnClick = () =\u003e {\n\t\tthis.props.transition(\"PREV\", {\n\t\t\toff: \"end\",\n\t\t\tsetState: { text: \"Next\" }\n\t\t});\n\t};\n\n\trender() {\n\t\treturn \u003cbutton onClick={this.handleOnClick}\u003e{props.text}\u003c/button\u003e;\n\t}\n}\n```\n\n# API\n\n## \u0026lt;Machine /\u0026gt;\n\nThe \u0026lt;Machine /\u0026gt; wraps your App and is responsible for passing down the props to the \u0026lt;State /\u0026gt;. The \u0026lt;Machine /\u0026gt; should have only one children, similar to `react-router`. The `initialState` and `flow` are passed to the machine through the `state` prop.\n\n| Prop  | Type   | Description                                                                                                                                       |\n| ----- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |\n| graph | bool   | Display realtime statechart visualization                                                                                                         |\n| log   | bool   | If true logs state transitions                                                                                                                    |\n| state | object | The object containing the state machine and initial State: { initialState: any, flow: [statechart](http://davidkpiano.github.io/xstate/docs/#/) } |\n\n## \u0026lt;State /\u0026gt;\n\nThe \u0026lt;State /\u0026gt; represents the individual state of your flow. `on` prop is what glues the state to a specific flow state, and the `children` prop returns a function with the machine props. It's recommended to use class based component for the `children` of the State so it can be referenced by the Machine.\n\n```js\n...\nstates: {\n  start: { on: {  NEXT: 'end' }},\n  end: { on: { PREV: 'start' }}\n}\n...\n\u003cState on=\"start\"\u003e\n  \u003cPageOne /\u003e\n\u003c/State\u003e\n\u003cState on=\"end\"\u003e\n  \u003cPageTwo /\u003e\n\u003c/State\u003e\n```\n\n| Prop | Type   | Description                                                                        |\n| ---- | ------ | ---------------------------------------------------------------------------------- |\n| on   | string | Component that will be turned 'on' when flow transitions to a state with same name |\n\n### props.transition(state[,options])\n\nAs the name suggests, this function is responsible for transitioning your app from one state to another. The first argument is the value of the state to be transitioned, and the second argument can receive a bunch of options. Like `off` to hide other non-actives \u0026lt;State /\u0026gt; components, `setState` to update your `state`/`initialState`, `draftState` which temporarily stores your changes until it's `publish`ed and `condition` where you can pass [xState Guards](http://davidkpiano.github.io/xstate/docs/#/guides/guards)\n\n| Option     | Type                               | Description                                                                                                             |\n| ---------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |\n| off        | oneOfType(string, arrayOf(string)) | Component(s) that will be turned 'off' when transition is called                                                        |\n| setState   | object                             | Mutates `initialState` keys with passed values                                                                          |\n| draftState | object                             | Like `setState`, but changes take effect only after being published. Newer `draftState`s will replace unpublished ones. |\n| condition  | any                                | Check xState Contitional Transitions ([Guards](http://davidkpiano.github.io/xstate/docs/#/guides/guards))               |\n\n```js\nprops.transition(\"NEXT\", {\n\toff: \"end\",\n\tsetState: {\n\t\ttext: \"Will be updated\"\n\t},\n\tdraftState: {\n\t\ttext: \"Will update again, but only after publish\"\n\t},\n\tcondition: { shouldTransition: this.text.length \u003c 99 }\n});\n```\n\n### props.publish()\n\nPublishes unpublished state aka. `draftState`. Draft is merged into State and then draft is cleaned. This is usefull when you are not sure if you want to update your state, I.E if a user clicks a cancel button during an API request.\n\n```js\nprops.transition(\"NEXT\", { draftState: { text: \"Hello World\" } });\nconsole.log(this.props.text); // ''\nprops.publish();\nconsole.log(this.props.text); // 'Hello World'\n```\n\n### props[state]\n\nYour initialState/state, can be accessed directly via `props.YOUR_STATE_KEY`.\n\n```js\nconsole.log(this.props.text); // Hello\n```\n\n# Todo\n\n*   [ ] Connect state to Redux DevTools\n*   [ ] Examples\n*   [ ] Better integration with other State Managers like Redux and Mobx ie.\n*   [ ] Tests\n\n# Thanks\n\n[David](https://twitter.com/DavidKPiano) the creator of [xstate](https://github.com/davidkpiano/xstate) who made this library possible and [Michele](https://twitter.com/MicheleBertoli) for inspiring me with [react-automata](https://github.com/MicheleBertoli/react-automata). Even if you like `react-gizmo` I recommend you to give them a try.\nAlso, a big thanks to [Ryan Florence](https://twitter.com/ryanflorence) for giving a great talk about State Machine.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FKadoBOT%2Freact-gizmo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FKadoBOT%2Freact-gizmo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FKadoBOT%2Freact-gizmo/lists"}