1.0.0 • Published 12 months ago

@element-public/react-stepper v1.0.0

Weekly downloads
-
License
ISC
Repository
github
Last release
12 months ago

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:

FieldDescriptionRequired
denseOverride the Stepper global density (not recommended).optional
errorStateSet 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
idA unique id for the step.required
onClickFired when the step is clicked. Primarily used in non-linear mode.optional
onStepEnterFired 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
onStepLeaveFired 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
secondaryTextA secondary subtitle for the step.optional
stepIndexOverride the automatically calculated step index (not recommended).optional
tagOptionally 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
textBubblePropsOptional custom props to be passed to the TextBubble. See the Element TextBubble for more information.optional
textBubbleTextOptionally override the text for the TextBubble. This is normally managed by the parent Stepper.optional
textBubbleThemeColorOptionally override the TextBubble themeColor. This is normally managed by the parent Stepper.optional
titleThe primary heading for the step.required
variantOptionally 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

NameTypeDefaultRequiredDescription
borderstring'default'falseChange 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
classNamestringundefinedfalseThe css class name to be passed through to the component markup.
densebooleanfalsefalseThe steps will be closer together with smaller icons.
nonLinearbooleanfalsefalseNon-linear will allow the user to navigate steps in any order by making the individual steps clickable.
progressnumberundefinedfalseOptionally override the current active step. Only used when tracking Stepper progress in the parent application.
rtlbooleanfalsefalseImproves layout for right-to-left languages.
stepsobjectundefinedfalseAn array of objects describing the steps to show. See readme for full schema.
tagstring|React.ElementType'div'falseBy default StepButton will render a div, this allow another tag to be used instead. A block type component is suggested.
verticalbooleanfalsefalseStacks steps vertically.

Stepper Render Props

NameTypeDefaultRequiredDescription
childrenReact.ReactNodeundefinedfalseSteps to be rendered inside the Stepper when managing Stepper state in a parent application. Not needed when using the steps prop.

Step Props

NameTypeDefaultRequiredDescription
classNamestringundefinedfalseThe css class name to be passed through to the component markup.
densebooleanfalsefalseOptionally override the global Stepper density. The step will be smaller with smaller icons.
errorStatestringundefinedfalseSet 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
idstringundefinedfalseA unique id used to associate the step with StepContent when using StepperContainer.
stepIndexnumberundefinedfalseOptionally override the stepIndex. Normally, this is automatically calculated when using Stepper with a StepperContainer.
tagstring|React.ElementType'button'falseOptionally 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.
textBubblePropsobjectundefinedfalseOptional custom props to be passed to the TextBubble. See the Element TextBubble for more information.
textBubbleTextobjectundefinedfalseOptionally override the text for the TextBubble. This is normally managed by the parent Stepper.
textBubbleThemeColorobjectundefinedfalseOptionally override the TextBubble themeColor. This is normally managed by the parent Stepper.
variantstringundefinedfalseOptionally 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

NameTypeDefaultRequiredDescription
secondaryTextReact.ReactNodeundefinedfalseSecondary text for the given step.
titleReact.ReactNodeundefinedfalsePrimary text for the given step.

Step Events

NameDefaultRequiredParamsDescription
onClickundefinedfalse1. Name: currentIndex, Type: number, Description: The index of this step.Fired when the step is clicked. Primarily used in non-linear mode.
onStepEnterundefinedfalse1. 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.
onStepLeaveundefinedfalse1. 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

NameTypeDefaultRequiredDescription
buttonPropsobjectundefinedfalseAdditional props to be passed to the underlying button. See the Element Button documentation for more information.
classNamestringundefinedfalseThe css class name to be passed through to the component markup.
confirmDisabledbooleanfalsefalsePrevent user interaction with the button on the last step*. Can be used with form validation.
directionstring'next'falseThe type of button, next or previous. Will automatically become a confirm button on the last stepAccepted Values: next, prev
disabledbooleanfalsefalsePrevent user interaction with the button. Can be used with form validation.
persistentbooleanfalsefalseHide the button using display:none instead of removing it from the dom. May be useful with animations.
tagstring|React.ElementTypeundefinedfalseOptionally override the default component of Element Button (such as an IconButton).

Step Button Render Props

NameTypeDefaultRequiredDescription
customLabelReact.ReactNodeundefinedfalseOverride the default button label of 'next' or 'prev'.

Step Button Events

NameDefaultRequiredParamsDescription
onClickundefinedfalseAn optional custom event handler to be executed after internal events are complete.

Step Content Props

NameTypeDefaultRequiredDescription
classNamestringundefinedfalseThe css class name to be passed through to the component markup.
fullWidthbooleanfalsefalseDisable the normal width of 600px and apply a full-width style to fill it's container.
paddingstring'standard'falseChange the default padding. The StepContent will normally use standard padding.Accepted Values: none, dense, standard, airy
persistentbooleanfalsefalseHide the button using display:none instead of removing it from the dom. May be useful with animations.
stepIdstringundefinedtrueThe id of the associated step.
tagstring|React.ElementType'div'falseBy default a div will be rendered, this allow another tag to be used instead. A block type component is suggested.

Step Content Render Props

NameTypeDefaultRequiredDescription
childrenReact.ReactNodenullfalseContent to be rendered inside StepContent.

Step Divider Props

NameTypeDefaultRequiredDescription
activebooleanundefinedfalseOptionally 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.
classNamestringundefinedfalseThe css class name to be passed through to the component markup.
dividerPropsobjectundefinedfalseOptional props to be passed to the underlying Element Divider component. See Divider documentation for more info.
nearestStepIndexnumberundefinedfalseThe step index immediately preceding the StepDivider. Used for calculating the active state with a linear Stepper.

Stepper Button Container Props

NameTypeDefaultRequiredDescription
borderstring'default'falseChange the default border. The Stepper Button Container will normally have a top border.Accepted Values: none, default
classNamestringundefinedfalseThe css class name to be passed through to the component markup.
fullWidthbooleanundefinedfalseDisable the normal width of 600px and apply a 100% width style to fill it's container. Note, this is automatically enabled with vertical steppers.
paddingstring'standard'falseChange the default padding. The Stepper Button Container will normally use standard padding.Accepted Values: none, dense, standard, airy
tagstring|React.ElementType'div'falseBy 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

NameTypeDefaultRequiredDescription
childrenReact.ReactNodenullfalseContent to be rendered inside StepContent.

Stepper Container Props

NameTypeDefaultRequiredDescription
classNamestringundefinedfalseThe css class name to be passed through to the component markup.
tagstring|React.ElementType'div'falseBy default a div will be rendered, this allow another tag to be used instead. A block type component is suggested.

Stepper Container Render Props

NameTypeDefaultRequiredDescription
childrenReact.ReactNodeundefinedfalseThe Stepper component to render.

Stepper Container Events

NameDefaultRequiredParamsDescription
onConfirmundefinedfalseFired when the confirm button is clicked.
onNextundefinedfalse1. 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.
onPrevundefinedfalse1. 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.
onStepChangeundefinedfalse1. 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

NameTypeDefaultRequiredDescription
classNamestringundefinedfalseThe css class name to be passed through to the component markup.
tagstring|React.ElementType'div'falseBy 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

NameTypeDefaultRequiredDescription
childrenReact.ReactNodenullfalseContent to be rendered inside StepContent.