@aniruddha1806/progress-tracker/README.md

A customizable progress tracker component for React applications

# 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

```bash
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

```jsx
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

```typescript
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:

```jsx
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:

```jsx
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):
```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:

```jsx
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:

```jsx
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:

```typescript
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} />;
};
```