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
Copy file name to clipboardExpand all lines: README.md
+35-57Lines changed: 35 additions & 57 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,9 +4,8 @@ _Unopinionated multi step interface builder._
4
4
5
5
## Overview
6
6
7
-
React Step Builder allows you to combine states of multiple _step_components in a single main state and navigate between components without losing the local states of the _steps_.
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.
8
8
9
-
<br />
10
9
<br />
11
10
12
11
## Installation
@@ -16,7 +15,6 @@ Using [npm](https://www.npmjs.com/):
16
15
$ npm install --save react-step-builder
17
16
18
17
<br />
19
-
<br />
20
18
21
19
## Usage
22
20
@@ -28,18 +26,16 @@ Using [npm](https://www.npmjs.com/):
28
26
</Steps>
29
27
```
30
28
31
-
<br />
32
29
<br />
33
30
34
31
### `<Steps />`
35
32
36
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.
|**`order`**_integer_| Defines the order of the Step component. Order numbers must start with `1` and be consecutive.|
51
+
#### `<Step />` Properties
52
+
53
+
-`order`_integer_- defines the order of the `Step`. Order numbers must start with `1` and be consecutive.
58
54
59
-
<br />
60
55
<br />
61
56
62
57
## Composing Step Components
63
58
64
-
There are some props available to your components that you render in `Step` component.
59
+
Following `props` available to your step components.
65
60
66
61
### `mainState`_(object)_
67
62
68
-
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. You can refer in any step component as `props.mainState`.
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.
69
64
70
65
### `setMainState`_(function)_
71
66
72
-
_(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.) You can refer in any step component as `props.setMainState`.
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.)
73
68
74
69
### `handleChange(event)`_(function)_
75
70
76
-
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 must be `{props.mainState.username}`.
77
-
78
-
In order to get rid of `uncontrolled/controlled component` error, simply put your value like this: `value={props.mainState.<inputName> || ''}`. Another way is, creating the `step` with `persist` keyword before ordered `step` components and define all your form value names inside that persistent step component's useEffect hook. Like this:
79
-
80
-
```js
81
-
exportconstPersistentStep=props=> {
82
-
useEffect(() => {
83
-
props.setMainState({
84
-
name:props.mainState.name||"", //For Step 1
85
-
age:props.mainState.age||"", // For Step 2
86
-
email:props.mainState.email||""// For Step 3
87
-
});
88
-
}, []);
89
-
90
-
return (
91
-
//Your component design
92
-
);
93
-
};
94
-
```
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}`.
95
72
96
73
### `steps`_(object)_
97
74
98
-
This object has two values: `total` and `current`. You can refer as `props.steps.total` and `props.steps.current`. If you would like to build a navigation bar, previous/next buttons, % X completed bar etc. refer to this object.
75
+
-`total` - Number of total steps.
76
+
-`current` - Current step that user is on.
99
77
100
78
### `prevStep`_(function)_
101
79
102
-
This function moves to the previous step. Refer as `props.prevStep()`
80
+
This function moves to the previous step.
103
81
104
82
### `nextStep`_(function)_
105
83
106
-
This function moves to the next step. Refer as `props.nextStep()`
84
+
This function moves to the next step.
107
85
108
86
### `jumpToStep(step)`_(function)_
109
87
110
-
This function moves to the specified step. Refer as `props.jumpToStep(stepNumber)`
88
+
This function moves to the specified step.
111
89
112
-
<br />
113
90
<br />
114
91
115
92
## UI Components
116
93
117
-
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.
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.
118
95
119
-
<br />
120
96
<br />
121
97
122
98
### `<Button />`
123
99
124
100
It renders a button with either prev or next functionality.
|**`text`**_String_| the text that will button render|
136
-
|**`prev`**_Boolean_| gives the button 'Go to Previous Step' functionality. Disabled in the first step.|
137
-
|**`next`**_Boolean_| gives the button 'Go to Next Step' functionality. Disabled in the last step.|
138
-
|_any props_| all the other props passed to the **Button** component will be passed any props to the button element |
109
+
#### `<Button />` Properties
110
+
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.
139
115
140
-
<br />
141
116
<br />
142
117
143
118
### `<Navigation />`
@@ -147,13 +122,16 @@ It renders a button for each step with the default text of Step number. The butt
147
122
Example usages:
148
123
149
124
```js
150
-
<Navigation />// if you have 3 steps, it renders 3 buttons, each has the text of [1, 2, 3] consecutively
151
-
<Navigation text="*"/>// if you have 3 steps, it renders 3 buttons, each has the text of * (asterix)
152
-
<Navigation before="HEY " after=" HI"/>// if you have 3 steps, it renders 3 buttons, each step number has 'HEY' before and 'HI' after (HEY 1 HI, HEY 2 HI, HEY 3 HI)
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