react-native-progress-steps

![](https://img.shields.io/npm/v/react-native-progress-steps.svg) ![](https://img.shields.io/npm/dm/react-native-progress-steps) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](http://makeapullrequest.com) # 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](#migration-guide-v1-to-v2) for more details. ## Example <img src="assets/example.png" width="300" height="600" style="border-radius: 15px; border: 2px solid #ccc; display: block;" /> <a href="examples/example.jsx">examples/example.jsx</a> ## 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](#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](#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](https://github.com/firstcontributions/first-contributions) guide or their [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/) guide. ## Author Colby Miller | [https://colbymillerdev.com](https://colbymillerdev.com) ## License [MIT](./LICENSE)