S

useFormSteps

Step navigation with conditional routing and history-based back navigation.

useFormSteps

Manages step navigation — determines the next step based on conditions, maintains a history stack for back navigation, and tracks the current step.

You probably don’t need this directly. useFormState calls it internally. Use it when building custom step navigation outside the standard <Form /> component.

Signature

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

const { currentStepId, stepHistory, nextStep, prevStep, isLastStep, getNextStep } = useFormSteps(
  steps,
  initialStepId,
);

Parameters

ParameterTypeDescription
stepsStepsSteps configuration map (stepId to step config)
initialStepIdstringThe step to start on

Return Value

PropertyTypeDescription
currentStepIdstringThe active step ID
stepHistorystring[]Stack of previously visited step IDs
nextStep(values) => booleanNavigate forward. Returns true if successful
prevStep() => booleanNavigate back. Returns true if successful
isLastStep(values) => booleanWhether the current step is the last one
getNextStep(values) => string | undefinedResolve the next step ID without navigating

How Navigation Works

Forward (nextStep)

  1. Evaluates the current step’s next conditions against values
  2. First matching condition’s target becomes the next step
  3. If no conditions match, uses defaultNext
  4. Pushes currentStepId onto stepHistory and updates currentStepId
  5. Returns false if no valid next step exists

Backward (prevStep)

  1. Pops the last entry from stepHistory
  2. Sets it as the new currentStepId
  3. Returns false if the history stack is empty

History Stack

The history records the exact path the user took, not all available steps. This means “Back” always returns to where the user came from, even with conditional routing:

Step A → Step C → Step E    (history: ['A', 'C'])
         ^ Back goes to C, then A

Example

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

function StepWizard({ steps, initialStep, values }) {
  const { currentStepId, stepHistory, nextStep, prevStep, isLastStep } = useFormSteps(
    steps,
    initialStep,
  );

  return (
    <div>
      <p>Current: {currentStepId}</p>
      <p>History: {stepHistory.join(' → ')}</p>

      {stepHistory.length > 0 && <button onClick={prevStep}>Back</button>}

      {isLastStep(values) ? (
        <button onClick={() => console.log('Submit!')}>Submit</button>
      ) : (
        <button onClick={() => nextStep(values)}>Next</button>
      )}
    </div>
  );
}