Form Flow Rendering

This document explains how to use the Flow Renderer component to display your form flows and handle submissions.

Basic Usage

The FlowRender component from @getevy/evy-ui/flow-render is used to display your form flows:

import { FlowRender } from '@getevy/evy-ui/flow-render';
import { myFlow } from './myFlow';

function MyFormPage() {
  const handleSubmit = formData => {
    // Process the submitted form data
    console.log('Form submitted with data:', formData);

    // Submit to API, navigate to confirmation page, etc.
  };

  return <FlowRender flow={myFlow} locale="en" onSubmit={handleSubmit} />;
}

Props

The FlowRender component accepts the following props:

Required Props

• flow: The flow definition object created with the flow() function
• locale: The current locale for translations (e.g., ‘en’, ‘fr’)
• onSubmit: Callback function triggered when the flow is completed

Optional Props

• initialData: Object containing initial values for form fields
• onStepChange: Callback function triggered when the current step changes
• preserveHistory: Whether to preserve step history for back navigation (default: true)
• useStorage: Whether to store form state in localStorage (default: false)
• debugMode: Enable debug mode with additional debugging information (default: false)

Complete Example

import { FlowRender } from '@getevy/evy-ui/flow-render';
import { myFlow } from './myFlow';

function MyFormPage() {
  const handleSubmit = formData => {
    console.log('Form submitted with data:', formData);
    // Process submission
  };

  const handleStepChange = stepId => {
    console.log('Current step changed to:', stepId);
    // Update UI, analytics, etc.
  };

  return (
    <FlowRender
      flow={myFlow}
      locale="en"
      onSubmit={handleSubmit}
      onStepChange={handleStepChange}
      initialData={{
        'step-1': {
          firstName: 'John',
          lastName: 'Doe',
        },
      }}
      preserveHistory={true}
      useStorage={true}
      debugMode={false}
    />
  );
}

Local Storage Integration

When useStorage is enabled, the form state is preserved in localStorage. This is useful for:

• Handling page refreshes during form completion
• Multi-session form filling
• Integration with external routing systems

<FlowRender
  flow={myFlow}
  locale="en"
  onSubmit={handleSubmit}
  useStorage={true} // Enable localStorage persistence
/>

Note: When using useStorage, each flow should have a unique id to prevent conflicts between different flows.

External Routing Integration

The Form Flow system can be integrated with external routing systems like Next.js or React Router. When using useStorage, you can control which step is displayed based on the URL:

import { useRouter } from 'next/router';
import { FlowRender } from '@getevy/evy-ui/flow-render';
import { myFlow } from './myFlow';

function MyFormPage() {
  const router = useRouter();
  const { step } = router.query; // Get current step from URL

  const handleSubmit = formData => {
    console.log('Form submitted with data:', formData);
    router.push('/confirmation');
  };

  const handleStepChange = stepId => {
    // Update URL when step changes
    router.push(`/form?step=${stepId}`, undefined, { shallow: true });
  };

  return (
    <FlowRender
      flow={myFlow}
      locale="en"
      onSubmit={handleSubmit}
      onStepChange={handleStepChange}
      initialStep={step as string} // Set initial step from URL
      useStorage={true}
    />
  );
}

Limitations and Caveats

When using external routing with useStorage:

• The step history is not persisted, so you should have a linear sequence of steps
• The form context needs to be loaded before navigating, which requires useStorage to be enabled
• Back/forward navigation may not work as expected with complex conditional flows

Debug Mode

Enable debug mode to display additional information during development:

<FlowRender
  flow={myFlow}
  locale="en"
  onSubmit={handleSubmit}
  debugMode={true} // Show debug information
/>

In debug mode, a debug panel is displayed showing:

• Current step ID
• Form data for the current step
• Complete form data across all steps
• Navigation history
• Validation errors

This is useful for development and troubleshooting but should be disabled in production.