Stepper

Description

A multi-step container. Most commonly used full screen or in a modal.

See live demos on storybook

Storybook Stepper Demos

Install bundle from npm-e

npm i @element-public/react-components @element-public/themes

Optional: install the component individually

npm i @element-public/react-stepper @element-public/themes

Open ~/.npmrc in an editor and add the following line to enable the @element-public scope:

@element-public:registry=https://npm.platforms.engineering

Troubleshooting

See below if you have never installed a package from Bayer's npm-enterprise or run into the following error:

npm ERR! code E401
npm ERR! Unable to authenticate, your authentication token seems to be invalid.
npm ERR! To correct this please trying logging in again with:
npm ERR!     npm login

Setup an access token

See the devtools npm-e guide to learn how to create an access token if this is the first time you are using a npm-e package at Bayer or you do not have a line that starts with the following in your ~/.npmrc file:

//npm.platforms.engineering/:_authToken=

Notes

Steps Schema

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 |

Stepper Props

| 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. |

Stepper Render Props

| 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. |

Step Props

| 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 |

Step Render Props

| 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. |

Step Events

| 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. |

Step Button Props

| 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 stepAccepted 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). |

Step Button Render Props

| Name | Type | Default | Required | Description | | ----------- | --------------- | --------- | -------- | ------------------------------------------------------ | | customLabel | React.ReactNode | undefined | false | Override the default button label of 'next' or 'prev'. |

Step Button Events

| Name | Default | Required | Params | Description | | ------- | --------- | -------- | ------ | ----------------------------------------------------------------------------------- | | onClick | undefined | false | | An optional custom event handler to be executed after internal events are complete. |

Step Content Props

| 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. |

Step Content Render Props

| Name | Type | Default | Required | Description | | -------- | --------------- | ------- | -------- | ------------------------------------------ | | children | React.ReactNode | null | false | Content to be rendered inside StepContent. |

Step Divider Props

| 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. |

Stepper Button Container Props

| 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. |

Stepper Button Container Render Props

| Name | Type | Default | Required | Description | | -------- | --------------- | ------- | -------- | ------------------------------------------ | | children | React.ReactNode | null | false | Content to be rendered inside StepContent. |

Stepper Container Props

| 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. |

Stepper Container Render Props

| Name | Type | Default | Required | Description | | -------- | --------------- | --------- | -------- | -------------------------------- | | children | React.ReactNode | undefined | false | The Stepper component to render. |

Stepper Container Events

| 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. |

Stepper Content Container Props

| 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. |

Stepper Content Container Render Props

| Name | Type | Default | Required | Description | | -------- | --------------- | ------- | -------- | ------------------------------------------ | | children | React.ReactNode | null | false | Content to be rendered inside StepContent. |