S

useFormStepsInfo

Step metadata for building progress bars, tab navigators, and step indicators.

useFormStepsInfo

Computes rich metadata for every step — status, error counts, completion, progress percentage. Designed to power UI components like progress bars, tab navigators, and step indicators.

This is the most useful hook for custom UI. Unlike the other hooks, you’ll often use this one directly when building a custom step progress component.

Signature

import { useFormStepsInfo } from '@saastro/forms';

const info = useFormStepsInfo({ steps, currentStepId, stepHistory, fields });

Must be called inside a React Hook Form FormProvider (it reads useFormContext() for error state).

Parameters

ParameterTypeDescription
stepsStepsSteps configuration map
currentStepIdstringActive step ID
stepHistorystring[]Stack of visited step IDs
fieldsFieldsField definitions map

Return Value: FormStepsInfo

PropertyTypeDescription
stepsStepInfo[]Metadata for every step (see below)
currentStepIdstringActive step ID
totalStepsnumberTotal number of steps
completedStepsnumberCount of completed steps
progressnumberCompletion percentage (0-100)
stepHistorystring[]Stack of visited step IDs
canGoNextbooleanWhether forward navigation is possible
canGoPrevbooleanWhether back navigation is possible
getStepInfo(id)(string) => StepInfoGet info for a specific step
getStepStatus(id)(string) => StepStatusGet status for a specific step

StepInfo

PropertyTypeDescription
idstringStep ID
fieldsstring[]Field names in this step
fieldCountnumberNumber of fields
statusStepStatus'pending', 'current', 'completed', or 'error'
hasErrorsbooleanWhether any fields have validation errors
errorCountnumberNumber of fields with errors
isVisitedbooleanWhether the step has been visited
isCurrentbooleanWhether this is the active step
isCompletedbooleanVisited, not current, no errors, all fields valid
canNavigatebooleanWhether the user can navigate to this step

StepStatus

type StepStatus = 'pending' | 'current' | 'completed' | 'error';
  • 'pending' — Not yet visited
  • 'current' — Active step
  • 'completed' — Visited, all fields valid
  • 'error' — Visited, has validation errors

Example: Custom Progress Bar

import { useFormStepsInfo } from '@saastro/forms';

function StepProgress({ steps, currentStepId, stepHistory, fields }) {
  const info = useFormStepsInfo({ steps, currentStepId, stepHistory, fields });

  return (
    <div>
      <div className="flex gap-2 mb-4">
        {info.steps.map((step) => (
          <div
            key={step.id}
            className={`flex-1 h-2 rounded ${
              step.isCompleted
                ? 'bg-green-500'
                : step.isCurrent
                  ? 'bg-blue-500'
                  : step.hasErrors
                    ? 'bg-red-500'
                    : 'bg-gray-200'
            }`}
          />
        ))}
      </div>
      <p className="text-sm text-muted-foreground">
        Step {info.steps.findIndex((s) => s.isCurrent) + 1} of {info.totalSteps} ({info.progress}%
        complete)
      </p>
    </div>
  );
}

Example: Step Navigator with Error Badges

function StepNav({ steps, currentStepId, stepHistory, fields, onStepClick }) {
  const info = useFormStepsInfo({ steps, currentStepId, stepHistory, fields });

  return (
    <nav className="flex gap-1">
      {info.steps.map((step, i) => (
        <button
          key={step.id}
          onClick={() => step.canNavigate && onStepClick(step.id)}
          disabled={!step.canNavigate}
          className={`px-3 py-1 rounded text-sm ${
            step.isCurrent
              ? 'bg-primary text-white'
              : step.isCompleted
                ? 'bg-green-100 text-green-800'
                : 'bg-gray-100 text-gray-500'
          }`}
        >
          {i + 1}. {step.id}
          {step.hasErrors && <span className="ml-1 text-xs text-red-500">({step.errorCount})</span>}
        </button>
      ))}
    </nav>
  );
}