You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
### React Step Builder is a UI-agnostic multi step interface builder.
4
4
5
5
## Overview
6
6
7
-
React Step Builder allows you to combine states of multiple components in a single main state and navigate between components without losing the local states of individual step components.
7
+
React Step Builder allows you to combine states of multiple components in one place
8
+
and navigate between components without losing the state from other step components.
9
+
10
+
It only provides wrapper components and methods to be able to render your step components
11
+
without being forced to use certain UI features in your step structure.
8
12
9
13
<br />
10
14
@@ -19,119 +23,112 @@ Using [npm](https://www.npmjs.com/):
19
23
## Usage
20
24
21
25
```js
22
-
<Steps total={3}>
23
-
<Step order={1} component={Step1} />
24
-
<Step order={2} component={Step2} />
25
-
<Step order={3} component={Step3} />
26
+
<Steps>
27
+
<Step title="My First Step" component={Step1} />
28
+
<Step title="My Second Step" component={Step2} />
29
+
<Step title="My Third Step" component={Step3} />
26
30
</Steps>
27
31
```
28
32
29
33
<br />
30
34
31
-
### `<Steps />`
32
-
33
-
This is the wrapper component. You must define every step component under `<Steps />` component. It takes `total` as a prop which must match the number of `Step` components inside.
35
+
## Documentation
34
36
35
-
#### Properties
36
-
37
-
-`total`_integer_ - is the number of steps you want to create.
|`<Steps />`| Wrapper component for Step components. Step components must be wrapped in `<Steps />` component. |
40
+
|`<Step />`| This is the component you create for each `step` in your application. The `title` prop takes a title for the step, which is provided back in `props` in the step component. The `component` prop takes the component that you would like to show in that step. |
38
41
39
42
<br />
40
43
41
-
### `<Step />`
44
+
### Following `props` are available to your step components.
42
45
43
-
This is the component you create for each `step` in your application. It takes `order` prop for ordering the steps in the flow. `Step` that has `order={1}` prop renders default. The `component` prop takes the component that you would like to show in that step.
46
+
<hr />
44
47
45
-
If you would like to create a persistent component that appears in every `Step`, you must remove the `order` prop and pass `persist` as a prop to a `Step` component. It is recommended to have that persistent step either in the beginning of the steps or at the end depending on where would you like to render that component (top or bottom).
48
+
### <strong>`props.current`</strong>
46
49
47
-
```js
48
-
<Step persist component={PersistentComponent} />
49
-
```
50
+
`number`
50
51
51
-
#### Properties
52
+
The current step's order number
52
53
53
-
-`order`_integer_ - defines the order of the `Step`. Order numbers must start with `1` and be consecutive.
54
+
<hr />
54
55
55
-
<br />
56
+
### <strong>`props.next`</strong>
56
57
57
-
## Composing Step Components
58
+
`function()`
58
59
59
-
Following `props` available to your step components.
60
+
Moves to the next step if it exists.
60
61
61
-
### `mainState`_(object)_
62
+
<hr />
62
63
63
-
It gives you all the state pieces combined from your `Step` components. As your user move forward in steps, the forms they fill before all accumulate under this value.
64
+
### <strong>`props.prev`</strong>
64
65
65
-
### `setMainState`_(function)_
66
+
`function()`
66
67
67
-
_(Not recommended to be used by default)_ By this function, you can manipulate your `mainState` in any of your state components. You may consider using it if the data you would like to save in your `mainState` object is not coming from a form element (technically, if the data is coming from a source without a synthetic event.)
68
+
Moves to the previous step if it exists.
68
69
69
-
### `handleChange(event)`_(function)_
70
+
<hr />
70
71
71
-
You may pass this function to any onChange event on any form element. One thing to always remember: Your form element must have name property, which eventually becomes its key in the `mainState` object. If your form element has `name="username"` then its value would be `{props.mainState.username}`.
72
+
### <strong>`props.jump`</strong>
72
73
73
-
### `steps`_(object)_
74
+
`function(<order>)`
74
75
75
-
-`total` - Number of total steps.
76
-
-`current` - Current step that user is on.
76
+
Jumps to the step with the provided step order if it exists.
77
77
78
-
### `prevStep`_(function)_
78
+
<hr />
79
79
80
-
This function moves to the previous step.
80
+
### <strong>`props.state`</strong>
81
81
82
-
### `nextStep`_(function)_
82
+
`object`
83
83
84
-
This function moves to the next step.
84
+
Contains all the state pieces combined from your `Step` components.
85
+
The user data that was entered accross the steps accumulate under this value.
85
86
86
-
### `jumpToStep(step)`_(function)_
87
+
<hr />
87
88
88
-
This function moves to the specified step.
89
+
### <strong>`props.getState`</strong>
89
90
90
-
<br />
91
+
`function(<key>)`
91
92
92
-
## UI Components
93
+
Returns the state value for the provided `key`. If the key does not exist, returns empty string.
93
94
94
-
React Step Builder is principally designed to minimally interfere with UI. However, creating the most basic next and previous buttons and navigation between steps might be time consuming for those who do not expect much from the design. Here are some components that comes in the box so that you can directly use in any **`Step`** component.
95
+
<hr />
95
96
96
-
<br />
97
+
### <strong>`props.setState`</strong>
97
98
98
-
### `<Button />`
99
+
`function(<key, value>)`
99
100
100
-
It renders a button with either prev or next functionality.
101
+
Manipulates your `state` directly. You must provide `key` and `value` to be stored in your state.<br />
102
+
_<strong>NOTE</strong>: If your data is coming from a synthetic React event (via `onChange`), use `props.handleChange` instead._
101
103
102
-
Example usage:
104
+
<hr />
103
105
104
-
```js
105
-
<Button next text="Next Step">
106
-
<Button prev text="Previous Step">
107
-
```
106
+
### <strong>`props.handleChange`</strong>
108
107
109
-
#### Properties
108
+
`function(<event>)`
110
109
111
-
-`text`_String_ - is the text that will button render.
112
-
-`prev`_Boolean_ - gives the button 'Go to Previous Step' functionality. Disabled in the first step.
113
-
-`next`_Boolean_ - gives the button 'Go to Next Step' functionality. Disabled in the last step.
114
-
-_any props_ - passed to the **Button** component will be passed to the button element on the DOM.
110
+
You may pass this function to `onChange` events in your form elements.
111
+
Your form element must have a `name` property, which eventually becomes its key in the `state` object.
112
+
If your form element has `name="username"`, then it is stored in state as `{props.state.username}`.
115
113
116
-
<br />
114
+
<hr />
117
115
118
-
### `<Navigation />`
116
+
### <strong>`props.step`</strong>
119
117
120
-
It renders a button for each step with the default text of Step number. The button for current step is disabled.
118
+
`object <StepNode>`
121
119
122
-
Example usages:
120
+
This object provides information about current step and methods to move between steps. Available properties and methods:
123
121
124
-
```js
125
-
<Navigation />// if you have 3 steps, it renders 3 buttons, each of which has the text of [1, 2, 3] consecutively
126
-
<Navigation text="*"/>// if you have 3 steps, it renders 3 buttons, each of which has the text of * (asterix)
127
-
<Navigation before="HEY " after=" HI"/>// if you have 3 steps, it renders 3 buttons, each of which has 'HEY' before and 'HI' after the step number (HEY 1 HI, HEY 2 HI, HEY 3 HI)
0 commit comments