React Native Progress Steps

A simple and fully customizable React Native component that implements a progress stepper UI.

• Each steps content is displayed inside of a customizable ScrollView.
• Customizable buttons are displayed at the bottom of the component to move between steps.

✨ What's New in v2.0

• 🎯 Full TypeScript Support - Complete type definitions for an enhanced development experience
• 🔄 Modern Component Architecture - Refactored to use functional components and React hooks
• 🎨 Major UI/UX Improvements
  • Enhanced responsiveness and layout
  • Modernized styling with new step icons, default colors, and button design
  • Improved performance
  • Better readability
• 💫 Smooth Step Transitions - Added subtle animations when changing between steps
• 🛠️ Enhanced Customization - Streamlined props with new customization options and removal of legacy features
• ⛔️ Breaking Changes - Some props have been removed and renamed. See the Migration Guide for more details.

Example

examples/example.jsx

Installation

npm i react-native-progress-steps

Usage

import { ProgressSteps, ProgressStep } from 'react-native-progress-steps';

Simply place a <ProgressStep /> tag for each desired step within the <ProgressSteps /> wrapper.

<View style={{flex: 1}}>
    <ProgressSteps>
        <ProgressStep label="First Step">
            <View style={{ alignItems: 'center' }}>
                <Text>This is the content within step 1!</Text>
            </View>
        </ProgressStep>
        <ProgressStep label="Second Step">
            <View style={{ alignItems: 'center' }}>
                <Text>This is the content within step 2!</Text>
            </View>
        </ProgressStep>
        <ProgressStep label="Third Step">
            <View style={{ alignItems: 'center' }}>
                <Text>This is the content within step 3!</Text>
            </View>
        </ProgressStep>
    </ProgressSteps>
</View>

Button Styling Usage

Navigation buttons are customizable using the various props provided to the ProgressStep component. See the Progress Step Component section for more details.

Simple example to set a specific button text:

return (
    <View style={{flex: 1}}>
        <ProgressSteps>
            <ProgressStep label="First Step" buttonNextText="Next Step" buttonPreviousText="Previous Step">
                <View style={{ alignItems: 'center' }}>
                    <Text>This is the content within step 1!</Text>
                </View>
            </ProgressStep>
            <ProgressStep label="Second Step" buttonNextText="Next Step" buttonPreviousText="Previous Step">
                <View style={{ alignItems: 'center' }}>
                    <Text>This is the content within step 2!</Text>
                </View>
            </ProgressStep>
        </ProgressSteps>
    </View>
)

Hiding the Button Row

To hide the button row, set the removeBtnRow prop to true. The current step can be changed without the buttons by updating and managing the activeStep prop on the <ProgressSteps /> component.

const [activeStep, setActiveStep] = useState(0);

<ProgressSteps activeStep={activeStep}>
    <ProgressStep label="First Step" removeBtnRow>
        <View style={{ alignItems: 'center' }}>
            <Text>This is the content within step 1!</Text>
        </View>
    </ProgressStep>
</ProgressSteps>

Current Step Error and Validation Handling

The errors prop should be used if there's a need for validation and error handling when clicking the next button. If you would like to prevent the next step from being rendered, set the errors prop to true. By default, it will be false.

Example usage of validation check:

const [isValid, setIsValid] = useState(false);
const [errors, setErrors] = useState(false);

const onNextStep = () => {
    if (!isValid) {
      setErrors(true);
    } else {
      setErrors(false);
    }
};

return (
    <View style={{ flex: 1 }}>
        <ProgressSteps>
          <ProgressStep label="First Step" onNext={onNextStep} errors={errors}>
            <View style={{ alignItems: 'center' }}>
              <Text>This is the content within step 1!</Text>
            </View>
          </ProgressStep>
          <ProgressStep label="Second Step">
            <View style={{ alignItems: 'center' }}>
              <Text>This is the content within step 2!</Text>
            </View>
          </ProgressStep>
        </ProgressSteps>
      </View>
);

Documentation

Progress Steps Component

Name	Description	Default	Type
borderWidth	Width of the progress bar between steps	2	Number
activeStepIconBorderColor	Outside border color for the active step	#2D2D2D	String
progressBarColor	Color of the default progress bar	#EBEBE4	String
completedProgressBarColor	Color of the completed progress bar	#2D2D2D	String
activeStepIconColor	Color of the active step icon	transparent	String
completedStepIconColor	Color of the completed step icon	#2D2D2D	String
disabledStepIconColor	Color of the disabled step icon	#EBEBE4	String
labelFontFamily	Font family for the step icon label	System default	String
labelColor	Color of the default label	#D3D3D3	String
labelFontSize	Font size for the step icon label	14	Number
activeLabelColor	Color of the active label	#2D2D2D	String
activeLabelFontSize	Optional font size for the active step icon label	14	Number
completedLabelColor	Color of the completed label	#2D2D2D	String
activeStepNumColor	Color of the active step number	#2D2D2D	String
completedStepNumColor	Color of the completed step number	#2D2D2D	String
disabledStepNumColor	Color of the disabled step number	#FFFFFF	String
completedCheckColor	Color of the completed step checkmark	#FFFFFF	String
activeStep	Manually specify the active step	0	Number
isComplete	Set all Steps to active state	false	Boolean
topOffset	Set progress bar top offset	60	Number
marginBottom	Set progress bar bottom margin	30	Number

Progress Step Component

Name	Description	Default	Type
label	Title of the current step to be displayed	undefined	String
onNext	Function called when the next step button is pressed	undefined	Func
onPrevious	Function called when the previous step button is pressed	undefined	Func
onSubmit	Function called when the submit step button is pressed	undefined	Func
scrollViewProps	Object to provide props to ScrollView component	undefined	Object
scrollable	The content of the Progress Step should be scrollable	true	Boolean
viewProps	Object to provide props to view component if scrollable is false	undefined	Object
errors	Used to assist with current step validation. If true, the next step won't be rendered	false	Boolean
removeBtnRow	Used to render the progress step without the button row	false	Boolean
buttonNextText	Text to display inside the next button	Next	String
buttonPreviousText	Text to display inside the previous button	Previous	String
buttonFinishText	Text to display inside the button on the last step	Submit	String
buttonNextDisabled	Value to disable/enable next button	false	Boolean
buttonPreviousDisabled	Value to disable/enable previous button	false	Boolean
buttonFinishDisabled	Value to disable/enable finish button	false	Boolean
buttonTopOffset	Set button row top offset	12	Number
buttonBottomOffset	Set button row bottom offset	20	Number
buttonHorizontalOffset	Set button row horizontal offset	30	Number
buttonFillColor	Background color for the next/finish buttons	#2D2D2D	String
buttonBorderColor	Border color for the previous button	#2D2D2D	String
buttonNextTextColor	Text color for the next button	#FFFFFF	String
buttonPreviousTextColor	Text color for the previous button	#2D2D2D	String
buttonFinishTextColor	Text color for the finish button	#FFFFFF	String
buttonDisabledColor	Background color for disabled buttons	#CDCDCD	String
buttonDisabledTextColor	Text color for disabled buttons	#FFFFFF	String

Migration Guide (v1 to v2)

Breaking Changes

Renamed Props

The following props have been renamed for better clarity and consistency:

Old Prop Name	New Prop Name	Component
nextBtnText	buttonNextText	ProgressStep
previousBtnText	buttonPreviousText	ProgressStep
finishBtnText	buttonFinishText	ProgressStep
nextBtnDisabled	buttonNextDisabled	ProgressStep
previousBtnDisabled	buttonPreviousDisabled	ProgressStep

Removed Props

The following props have been removed in favor of the new styling system:

Removed Prop	Alternative
nextBtnStyle	Use buttonFillColor and other button styling props
nextBtnTextStyle	Use buttonNextTextColor instead
previousBtnStyle	Use buttonBorderColor and other button styling props
previousBtnTextStyle	Use buttonPreviousTextColor instead
finishBtnStyle	Use buttonFillColor and other button styling props
finishBtnTextStyle	Use buttonFinishTextColor instead
borderStyle	No longer supported

New Button Styling System

Instead of using style objects, the new version provides specific props for common button customizations:

// Old way
<ProgressStep
  nextBtnStyle={{ backgroundColor: '#2D2D2D' }}
  nextBtnTextStyle={{ color: '#FFFFFF' }}
>
  {/* content */}
</ProgressStep>

// New way
<ProgressStep
  buttonFillColor="#2D2D2D"
  buttonNextTextColor="#FFFFFF"
>
  {/* content */}
</ProgressStep>

See the Progress Step Component section for all available button styling props.

Contributing

Pull requests are always welcome! Feel free to open a new GitHub issue for any changes that can be made.

Working on your first Pull Request? You can learn how from GitHub's First Contributions guide or their How to Contribute to Open Source guide.

Author

Colby Miller | https://colbymillerdev.com

License

MIT