React Progress Tracker

A flexible, customizable progress tracker component for React applications with TypeScript support. Perfect for multi-step forms, onboarding flows, checkout processes, and any step-by-step user journey.

Installation

npm install @aniruddha1806/progress-tracker

Features

• 🎨 Extensive customization options (colors, sizes, styles)
• 📱 Responsive design with multiple size options
• 🔧 Custom step rendering support
• 🎭 Built-in icons and labels with sublabels
• 📊 Visual state management (active, completed, inactive)
• 🎨 CSS class and inline style support
• 📝 TypeScript support with full type definitions
• ♿ Accessibility-friendly structure
• 🪶 Zero dependencies and lightweight

Quick Start

import ProgressTracker from '@aniruddha1806/progress-tracker';

function App() {
  const steps = [
    { 
      label: 'Account', 
      sublabel: 'Create your account',
      icon: '👤' 
    },
    { 
      label: 'Profile', 
      sublabel: 'Complete your profile',
      icon: '📝' 
    },
    { 
      label: 'Verification', 
      sublabel: 'Verify your email',
      icon: '✉️' 
    },
    { 
      label: 'Complete', 
      sublabel: 'All done!',
      icon: '✅' 
    }
  ];

  return (
    <ProgressTracker
      steps={steps}
      currentStep={1} // 0-indexed (step 2 is active)
    />
  );
}

Props

ProgressTrackerProps

| Prop | Type | Default | Description | |------|------|---------|-------------| | steps | Step[] | required | Array of step objects | | currentStep | number | required | Current active step (0-indexed) | | className | string | "" | CSS class for container | | stepClassName | string | "" | CSS class for step elements | | labelClassName | string | "" | CSS class for step labels | | sublabelClassName | string | "" | CSS class for step sublabels | | iconClassName | string | "" | CSS class for step icons | | connectorClassName | string | "" | CSS class for connectors | | activeConnectorClassName | string | "" | CSS class for active connectors | | inactiveConnectorClassName | string | "" | CSS class for inactive connectors | | activeColor | string | "#0074D9" | Color for active/completed steps | | inactiveColor | string | "#E1E8ED" | Color for inactive steps | | showLabels | boolean | true | Show step labels | | showConnectors | boolean | true | Show connectors between steps | | size | "small" \| "medium" \| "large" | "medium" | Overall component size | | renderCustomStep | function | undefined | Custom step render function |

Step Interface

interface Step {
  label: string;           // Step title
  sublabel?: string;       // Optional subtitle
  icon: React.ReactNode;   // Icon (emoji, SVG, component)
}

Examples

Basic Horizontal Progress

Simple horizontal progress tracker:

import ProgressTracker from '@aniruddha1806/progress-tracker';

function BasicExample() {
  const steps = [
    { label: 'Start', icon: '🚀' },
    { label: 'Progress', icon: '⚡' },
    { label: 'Complete', icon: '🎉' }
  ];

  return (
    <ProgressTracker
      steps={steps}
      currentStep={1}
    />
  );
}

Custom Colors and Styling

Customize appearance with colors and CSS classes:

import ProgressTracker from '@aniruddha1806/progress-tracker';
import './custom-progress.css'; // Your custom CSS

function CustomStyledExample() {
  const steps = [
    { label: 'Design', icon: '🎨' },
    { label: 'Develop', icon: '💻' },
    { label: 'Test', icon: '🧪' },
    { label: 'Deploy', icon: '🚀' }
  ];

  return (
    <ProgressTracker
      steps={steps}
      currentStep={2}
      activeColor="#28a745"
      inactiveColor="#f8f9fa"
      size="large"
      connectorStyle="dashed"
      className="custom-progress"
      stepClassName="custom-step"
      labelClassName="custom-label"
    />
  );
}

CSS file (custom-progress.css):

.custom-progress {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  border-radius: 12px;
  padding: 24px;
}

.custom-step {
  transition: transform 0.2s ease;
}

.custom-step:hover {
  transform: scale(1.05);
}

.custom-label {
  font-family: 'Inter', sans-serif;
  font-weight: 600;
  color: white;
}

With React Icons

Use popular icon libraries:

import ProgressTracker from '@aniruddha1806/progress-tracker';
import { 
  FaUser, 
  FaCreditCard, 
  FaShippingFast, 
  FaCheckCircle 
} from 'react-icons/fa';

function IconExample() {
  const steps = [
    { 
      label: 'Account', 
      sublabel: 'Sign up or login',
      icon: <FaUser /> 
    },
    { 
      label: 'Payment', 
      sublabel: 'Enter payment details',
      icon: <FaCreditCard /> 
    },
    { 
      label: 'Shipping', 
      sublabel: 'Choose delivery option',
      icon: <FaShippingFast /> 
    },
    { 
      label: 'Confirmation', 
      sublabel: 'Order complete',
      icon: <FaCheckCircle /> 
    }
  ];

  return (
    <ProgressTracker
      steps={steps}
      currentStep={1}
      activeColor="#007bff"
      size="large"
    />
  );
}

Different Sizes

Show all available sizes:

import ProgressTracker from '@aniruddha1806/progress-tracker';

function SizesExample() {
  const steps = [
    { label: 'Start', icon: '🚀' },
    { label: 'Middle', icon: '⚡' },
    { label: 'End', icon: '🎉' }
  ];

  return (
    <div style={{ padding: '20px' }}>
      <h3>Small Size</h3>
      <ProgressTracker
        steps={steps}
        currentStep={1}
        size="small"
        activeColor="#dc3545"
      />
      
      <h3 style={{ marginTop: '40px' }}>Medium Size (Default)</h3>
      <ProgressTracker
        steps={steps}
        currentStep={1}
        size="medium"
        activeColor="#ffc107"
      />
      
      <h3 style={{ marginTop: '40px' }}>Large Size</h3>
      <ProgressTracker
        steps={steps}
        currentStep={1}
        size="large"
        activeColor="#28a745"
      />
    </div>
  );
}

TypeScript Usage

The component provides full TypeScript support:

import ProgressTracker, { Step, ProgressTrackerProps } from '@aniruddha1806/progress-tracker';
import { ReactNode } from 'react';

interface CustomStep extends Step {
  id: string;
  duration?: number;
  isOptional?: boolean;
}

interface WizardProps {
  steps: CustomStep[];
  onStepChange: (stepIndex: number) => void;
}

const CustomWizard: React.FC<WizardProps> = ({ steps, onStepChange }) => {
  const [currentStep, setCurrentStep] = useState<number>(0);

  const handleStepClick = (stepIndex: number): void => {
    setCurrentStep(stepIndex);
    onStepChange(stepIndex);
  };

  const renderCustomStep = (
    step: Step, 
    index: number, 
    isCompleted: boolean, 
    isActive: boolean
  ): ReactNode => {
    const customStep = step as CustomStep;
    
    return (
      <div
        key={customStep.id}
        onClick={() => handleStepClick(index)}
        style={{
          cursor: 'pointer',
          opacity: customStep.isOptional && !isCompleted ? 0.6 : 1
        }}
      >
        {/* Custom step rendering */}
      </div>
    );
  };

  const progressProps: ProgressTrackerProps = {
    steps,
    currentStep,
    renderCustomStep,
    activeColor: '#6366f1',
    size: 'large'
  };

  return <ProgressTracker {...progressProps} />;
};