React Status Tracker

React Status Tracker is a reusable status / step / workflow tracker component for React applications.
It supports both horizontal and vertical layouts and is built using Material UI (MUI).

This component can be used for:

• Workflow tracking
• Order or shipment status
• Approval pipelines
• Process steps
• Progress visualization

It supports active and inactive steps, an optional flagged (error) state, sequential animated progress, full TypeScript support, and extensive customization options for colors, sizes, and animation behavior.
The component is lightweight, production-ready, and compatible with MUI v5.

Installation

npm install react-status-tracker

Peer Dependencies

npm install @mui/material @mui/system @mui/utils @emotion/react @emotion/styled

Usage Example

import { Box } from "@mui/material";
import StatusTracker from "react-status-tracker";

const steps = [
  "TESTING",
  "TESTING COMPLETE",
  "TESTING REVIEW",
  "TESTING APPROVED",
];

export default function Example() {
  return (
    <Box sx={{ p: 4 }}>
      <StatusTracker
        steps={steps}
        currentStatus="TESTING REVIEW"
      />
    </Box>
  );
}

Vertical Layout Example

<StatusTracker
  steps={steps}
  currentStatus="TESTING REVIEW"
  orientation="vertical"
/>

Flagged (Error) State Example

<StatusTracker
  steps={steps}
  currentStatus="TESTING REVIEW"
  flagged
/>

Animation Examples

Sequential Animated Progress (Default)

<StatusTracker
  steps={steps}
  currentStatus="TESTING REVIEW"
/>

• Progress animates step-by-step from the first step to the current step
• Grey connector lines are always visible
• Active progress animates over the grey base line

Disable Animation

<StatusTracker
  steps={steps}
  currentStatus="TESTING REVIEW"
  animate={false}
/>

Custom Animation Speed

<StatusTracker
  steps={steps}
  currentStatus="TESTING REVIEW"
  stepDelay={800}
  transitionDuration={600}
/>

Custom Styling Example

<StatusTracker
  steps={steps}
  currentStatus="TESTING REVIEW"
  activeColor="#2e7d32"
  inactiveColor="#e0e0e0"
  circleSize={24}
  lineThickness={3}
  transitionDuration={400}
  stepDelay={300}
/>

Props

| Prop Name | Type | Description | Default | |-----------------------|---------------------------|----------------------------------------------------------|---------------| | steps | string[] | Ordered list of step labels | Required | | currentStatus | string | Current active step | Required | | orientation | horizontal | vertical | Layout direction | horizontal | | flagged | boolean | Error or alert state | false | | activeColor | string | Active step color | Auto | | inactiveColor | string | Inactive step / base line color | #ccc | | circleSize | number | Step indicator size | 20 | | lineThickness | number | Connector thickness | 2 | | animate | boolean | Enable or disable sequential animation | true | | stepDelay | number | Delay between each step animation (ms) | 500 | | transitionDuration | number | CSS transition duration for steps and connectors (ms) | 500 |

Behavior Notes

• Steps animate sequentially from the first step to the current step
• Grey connector lines are always visible, even for incomplete steps
• Active progress animates over the grey base connector
• All steps before and including the current step are marked active
• If animate is set to false, the tracker renders instantly
• If the provided currentStatus does not exist in the steps array, the first step is selected
• Text labels never affect layout alignment

TypeScript Support

import type { StatusTrackerProps } from "react-status-tracker";

Compatibility

• React 18+
• React 19+
• Material UI v5.x
• Emotion v11

Common Use Cases

• Order tracking
• Shipment workflows
• Approval pipelines
• Task progression
• Multi-step form indicators

Planned Enhancements

• Icons inside steps
• Clickable steps
• Tooltip support
• Accessibility (ARIA stepper roles)
• SVG-based rendering option

Developed by Mohamed Ruwaid