A multi-step container for Element React
A multi-step container. Most commonly used full screen or in a modal.
- Verify that you have access to (https://docs.int.bayer.com/cloud/devops/artifactory/)[Bayer Artifactory]
- Verify your token is correctly set up in your .npmrc as per the link above
- Verify you have the @element scope configured in your .npmrc
- @element:registry=https://artifactory.bayer.com/artifactory/api/npm/npm-platforms-engineering/
- Install the component and themes bundles
- npm i @element/react-components @element/themes
- alternatively install the component individually along with the themes bundle npm i @element/react-stepper @element/themes
Steps may be passed to the Stepper component using the steps prop. They must be formatted as an object array using a similar schema as the Step props:
| Field | Description | Required |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
| dense | Override the Stepper global density _(not recommended)_. | optional |
| errorState | Set this flag to have a step display incomplete or in error/danger while maintaining internal variant logic. It is commonly useful with form validation. This will only show when a linear Stepper has moved beyond the flagged step. For non-linear Steppers, it will always show if the flag is set except for the active step. | optional |
| id | A unique id for the step. | required |
| onClick | Fired when the step is clicked. Primarily used in non-linear mode. | optional |
| onStepEnter | Fired when the step becomes visible. Note: the order of the parameters follows the Stepper convention of the step being entered followed by the step being left. | optional |
| onStepLeave | Fired when the step becomes invisible. Note: the order of the parameters follows the Stepper convention of the step being entered followed by the step being left. | optional |
| secondaryText | A secondary subtitle for the step. | optional |
| stepIndex | Override the automatically calculated step index _(not recommended)_. | optional |
| tag | Optionally override the default component of button. If using a tag other than button or input, keyboard events (such as onKeyUp) will need to be added for accessability compliance. | optional |
| textBubbleProps | Optional custom props to be passed to the TextBubble. See the Element TextBubble for more information. | optional |
| textBubbleText | Optionally override the text for the TextBubble. This is normally managed by the parent Stepper. | optional |
| textBubbleThemeColor | Optionally override the TextBubble themeColor. This is normally managed by the parent Stepper. | optional |
| title | The primary heading for the step. | required |
| variant | Optionally override the step variant - the step will ignore any internal variant logic. This is normally managed by the parent Stepper except for error/validation cases. | optional |
| Name | Type | Default | Required | Description |
| --------- | ------------------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| border | string | 'default' | false | Change the default border. The Stepper will normally have a bottom border in horizontal mode and a trailing border in vertical mode.
Accepted Values: none, default |
| className | string | undefined | false | The css class name to be passed through to the component markup. |
| dense | boolean | false | false | The steps will be closer together with smaller icons. |
| nonLinear | boolean | false | false | Non-linear will allow the user to navigate steps in any order by making the individual steps clickable. |
| progress | number | undefined | false | Optionally override the current active step. Only used when tracking Stepper progress in the parent application. |
| rtl | boolean | false | false | Improves layout for right-to-left languages. |
| steps | [object] | undefined | false | An array of objects describing the steps to show. See readme for full schema. |
| tag | string\|React.ElementType | 'div' | false | By default StepButton will render a div, this allow another tag to be used instead. A block type component is suggested. |
| vertical | boolean | false | false | Stacks steps vertically. |
| Name | Type | Default | Required | Description |
| -------- | --------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| children | React.ReactNode | undefined | false | Steps to be rendered inside the Stepper when managing Stepper state in a parent application. Not needed when using the steps prop. |
| Name | Type | Default | Required | Description |
| -------------------- | ------------------------- | --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| className | string | undefined | false | The css class name to be passed through to the component markup. |
| dense | boolean | false | false | Optionally override the global Stepper density. The step will be smaller with smaller icons. |
| errorState | string | undefined | false | Set this flag to have a step display incomplete or in error/danger while maintaining internal variant logic. It is commonly useful with form validation. This will only show when a linear Stepper has moved beyond the flagged step. For non-linear Steppers, it will always show if the flag is set except for the active step.
Accepted Values: incomplete, danger |
| id | string | undefined | false | A unique id used to associate the step with StepContent when using StepperContainer. |
| stepIndex | number | undefined | false | Optionally override the stepIndex. Normally, this is automatically calculated when using Stepper with a StepperContainer. |
| tag | string\|React.ElementType | 'button' | false | Optionally override the default component of button. If using a tag other than button or input, keyboard events (such as onKeyUp) will need to be added for accessability compliance. |
| textBubbleProps | object | undefined | false | Optional custom props to be passed to the TextBubble. See the Element TextBubble for more information. |
| textBubbleText | object | undefined | false | Optionally override the text for the TextBubble. This is normally managed by the parent Stepper. |
| textBubbleThemeColor | object | undefined | false | Optionally override the TextBubble themeColor. This is normally managed by the parent Stepper. |
| variant | string | undefined | false | Optionally override the step variant - the step will ignore any internal variant logic. This is normally managed by the parent Stepper except for error/validation cases.
Accepted Values: inactive, completed, active, incomplete, danger |
| Name | Type | Default | Required | Description |
| ------------- | --------------- | --------- | -------- | ---------------------------------- |
| secondaryText | React.ReactNode | undefined | false | Secondary text for the given step. |
| title | React.ReactNode | undefined | false | Primary text for the given step. |
| Name | Default | Required | Params | Description |
| ----------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| onClick | undefined | false | 1. Name: currentIndex, Type: number, Description: The index of this step. | Fired when the step is clicked. Primarily used in non-linear mode. |
| onStepEnter | undefined | false | 1. Name: currentIndex, Type: number, Description: The index of this step.,2. Name: prevStepIndex, Type: number, Description: The index of the previous step shown. | Fired when the step becomes visible. Note: the order of the parameters follows the Stepper convention of the step being entered followed by the step being left. |
| onStepLeave | undefined | false | 1. Name: nextStepIndex, Type: number, Description: The index of the next step to show.,2. Name: currentIndex, Type: number, Description: The index of this step. | Fired when the step becomes invisible. Note: the order of the parameters follows the Stepper convention of the step being entered followed by the step being left. |
| Name | Type | Default | Required | Description |
| --------------- | ------------------------- | --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| buttonProps | object | undefined | false | Additional props to be passed to the underlying button. See the Element Button documentation for more information. |
| className | string | undefined | false | The css class name to be passed through to the component markup. |
| confirmDisabled | boolean | false | false | Prevent user interaction with the button on the last step\*. Can be used with form validation. |
| direction | string | 'next' | false | The type of button, next or previous. Will automatically become a confirm button on the last step
Accepted Values: next, prev |
| disabled | boolean | false | false | Prevent user interaction with the button. Can be used with form validation. |
| persistent | boolean | false | false | Hide the button using display:none instead of removing it from the dom. May be useful with animations. |
| tag | string\|React.ElementType | undefined | false | Optionally override the default component of Element Button (such as an IconButton). |
| Name | Type | Default | Required | Description |
| ----------- | --------------- | --------- | -------- | ------------------------------------------------------ |
| customLabel | React.ReactNode | undefined | false | Override the default button label of 'next' or 'prev'. |
| Name | Default | Required | Params | Description |
| ------- | --------- | -------- | ------ | ----------------------------------------------------------------------------------- |
| onClick | undefined | false | | An optional custom event handler to be executed after internal events are complete. |
| Name | Type | Default | Required | Description |
| ---------- | ------------------------- | ---------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- |
| className | string | undefined | false | The css class name to be passed through to the component markup. |
| fullWidth | boolean | false | false | Disable the normal width of 600px and apply a full-width style to fill it's container. |
| padding | string | 'standard' | false | Change the default padding. The StepContent will normally use standard padding.
Accepted Values: none, dense, standard, airy |
| persistent | boolean | false | false | Hide the button using display:none instead of removing it from the dom. May be useful with animations. |
| stepId | string | undefined | true | The id of the associated step. |
| tag | string\|React.ElementType | 'div' | false | By default a div will be rendered, this allow another tag to be used instead. A block type component is suggested. |
| Name | Type | Default | Required | Description |
| -------- | --------------- | ------- | -------- | ------------------------------------------ |
| children | React.ReactNode | null | false | Content to be rendered inside StepContent. |
| Name | Type | Default | Required | Description |
| ---------------- | ------- | --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| active | boolean | undefined | false | Optionally override automatic active tracking - only needed when managing Stepper state in the parent application. Will use the primary color when true and the stroke color when false. Only used with linear Steppers. |
| className | string | undefined | false | The css class name to be passed through to the component markup. |
| dividerProps | object | undefined | false | Optional props to be passed to the underlying Element Divider component. See Divider documentation for more info. |
| nearestStepIndex | number | undefined | false | The step index immediately preceding the StepDivider. Used for calculating the active state with a linear Stepper. |
| Name | Type | Default | Required | Description |
| --------- | ------------------------- | ---------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| border | string | 'default' | false | Change the default border. The Stepper Button Container will normally have a top border.
Accepted Values: none, default |
| className | string | undefined | false | The css class name to be passed through to the component markup. |
| fullWidth | boolean | undefined | false | Disable the normal width of 600px and apply a 100% width style to fill it's container. Note, this is automatically enabled with vertical steppers. |
| padding | string | 'standard' | false | Change the default padding. The Stepper Button Container will normally use standard padding.
Accepted Values: none, dense, standard, airy |
| tag | string\|React.ElementType | 'div' | false | By default a div will be rendered, this allow another tag to be used instead. A block type component is suggested. |
| Name | Type | Default | Required | Description |
| -------- | --------------- | ------- | -------- | ------------------------------------------ |
| children | React.ReactNode | null | false | Content to be rendered inside StepContent. |
| Name | Type | Default | Required | Description |
| --------- | ------------------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------ |
| className | string | undefined | false | The css class name to be passed through to the component markup. |
| tag | string\|React.ElementType | 'div' | false | By default a div will be rendered, this allow another tag to be used instead. A block type component is suggested. |
| Name | Type | Default | Required | Description |
| -------- | --------------- | --------- | -------- | -------------------------------- |
| children | React.ReactNode | undefined | false | The Stepper component to render. |
| Name | Default | Required | Params | Description |
| ------------ | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| onConfirm | undefined | false | | Fired when the confirm button is clicked. |
| onNext | undefined | false | 1. Name: nextStepIndex, Type: number, Description: The index of the next step to show.,2. Name: prevStepIndex, Type: number, Description: The index of the previous step. | Using onStepChange is usually preferred as it catches non-linear step clicks. OnNext is fired only when the next button is clicked. |
| onPrev | undefined | false | 1. Name: nextStepIndex, Type: number, Description: The index of the next step to show.,2. Name: prevStepIndex, Type: number, Description: The index of the previous step. | Using onStepChange is usually preferred as it catches non-linear step clicks. OnPrev is fired only when the prev button is clicked. |
| onStepChange | undefined | false | 1. Name: nextStepIndex, Type: number, Description: The index of the next step to show.,2. Name: prevStepIndex, Type: number, Description: The index of the previous step. | An alternative to onNext and onPrev, onStepChange will fire when the progress is changed in any way. Note: this _does not_ fire when the confirm button is clicked. |
| Name | Type | Default | Required | Description |
| --------- | ------------------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------ |
| className | string | undefined | false | The css class name to be passed through to the component markup. |
| tag | string\|React.ElementType | 'div' | false | By default a div will be rendered, this allow another tag to be used instead. A block type component is suggested. |
| Name | Type | Default | Required | Description |
| -------- | --------------- | ------- | -------- | ------------------------------------------ |
| children | React.ReactNode | null | false | Content to be rendered inside StepContent. |