The useWorkflow Hook

The useWorkflowContext hook is your primary tool for interacting with the workflow's state and behavior from within any component nested under a WorkflowProvider. It gives you access to all the data, state, and actions you need to build custom navigation, display progress, or create complex interactions.

How to use it

To use the hook, simply import it from @rilaykit/workflow and call it within your component.

import { useWorkflowContext } from '@rilaykit/workflow';

function MyCustomWorkflowComponent() {
  const workflow = useWorkflowContext();

  // You can now access workflow.workflowState, workflow.goNext(), etc.
  
  return (
    <div>
      <p>Current Step: {workflow.currentStep.title}</p>
      <button onClick={() => workflow.goNext()}>
        Next Step
      </button>
    </div>
  );
}

Returned Values

The useWorkflowContext hook returns an object with the current state of the workflow and functions to control it.

State Properties

These properties give you a snapshot of the workflow's current state. They are read-only.

• workflowState: An object containing the raw state of the workflow.
  • currentStepIndex: The index of the active step.
  • allData: An object containing all data collected across all steps.
  • stepData: The data for the current step.
  • visitedSteps: A Set of visited step IDs.
  • isSubmitting: true if the entire workflow is currently being submitted.
  • isTransitioning: true during the transition between steps.
• currentStep: The full configuration object for the current step.
• context: A context object with useful derived state.
  • isFirstStep: true if the current step is the first one.
  • isLastStep: true if the current step is the last one.
  • totalSteps: The total number of steps.
• formConfig: If the current step is a form, this holds the form's configuration.

Action Functions

These functions allow you to change the workflow's state.

• goNext(): Navigates to the next step.
• goPrevious(): Navigates to the previous step.
• goToStep(stepIndex: number): Navigates to a specific step by its index.
• skipStep(): Skips the current step, if allowed.
• setValue(fieldId: string, value: any): Sets the value for a specific field in the current step's form.
• setStepData(data: object): Replaces the data for the current step.
• submitWorkflow(): Submits the entire workflow.
• resetWorkflow(): Resets the workflow to its initial state.

Example: Custom Navigation Bar

Here's an example of how you could build a custom navigation bar for your workflow.

import { useWorkflowContext } from '@rilaykit/workflow';

export function CustomWorkflowNav() {
  const { 
    goNext, 
    goPrevious, 
    submitWorkflow,
    context, 
    workflowState 
  } = useWorkflowContext();

  const { isFirstStep, isLastStep } = context;
  const { isTransitioning, isSubmitting } = workflowState;

  return (
    <div className="workflow-nav">
      {!isFirstStep && (
        <button 
          onClick={goPrevious} 
          disabled={isTransitioning}
        >
          Back
        </button>
      )}
      
      {!isLastStep ? (
        <button 
          onClick={goNext} 
          disabled={isTransitioning}
        >
          {isTransitioning ? 'Loading...' : 'Next'}
        </button>
      ) : (
        <button 
          onClick={submitWorkflow}
          disabled={isSubmitting}
        >
          {isSubmitting ? 'Submitting...' : 'Finish'}
        </button>
      )}
    </div>
  );
}

This component uses the hook to get navigation functions and state to conditionally render "Back", "Next", and "Finish" buttons, and disables them during transitions or submissions to prevent user errors.