Form System

Dashforge Form System eliminates the manual wiring required for dynamic forms. No scattered useEffect hooks. No prop drilling. No manual re-render coordination. Instead, you declare what fields depend on each other, and the system handles all orchestration automatically.

It's built on top of React Hook Form, adding a reactive engine, declarative reactions, and runtime state management. Together, they handle validation, submission, async coordination, and field dependencies without boilerplate.

Most form libraries handle static forms well: you define fields, add validation, submit the form. But real-world applications need dynamic behavior:

• Selecting "United States" should load a list of states for the next dropdown
• Checking "Ship to different address" should reveal additional fields
• Changing payment method should update available billing options
• Selecting a product category should filter available subcategories

Without a system to orchestrate these behaviors, you end up with:

• Scattered useEffect hooks throughout your form component
• Manual field state management alongside form state
• Complex event handlers that know too much about form structure
• Difficult-to-test spaghetti logic

Dashforge Form System provides three key primitives to solve this problem:

React Hook Form is excellent for form state and validation. But when fields need to interact—one field loading options based on another—you fall back to imperative code:

// Without Dashforge: Manual orchestration required
function AddressForm() {
  const { watch, setValue } = useFormContext();
  const [stateOptions, setStateOptions] = useState([]);
  const [loading, setLoading] = useState(false);
  
  const country = watch('country');
  
  useEffect(() => {
    if (!country) {
      setStateOptions([]);
      setValue('state', null);
      return;
    }
    
    let cancelled = false;
    setLoading(true);
    
    fetchStates(country).then(states => {
      if (!cancelled) {
        setStateOptions(states);
        setLoading(false);
      }
    });
    
    return () => { cancelled = true; };
  }, [country, setValue]);
  
  return (
    <>
      <Select name="country" options={countries} />
      <Select 
        name="state" 
        options={stateOptions}
        loading={loading}
      />
    </>
  );
}

With Dashforge, all orchestration is declarative:

// With Dashforge: Pure declaration
const reactions = [{
  id: 'load-states',
  watch: ['country'],
  run: async (ctx) => {
    const country = ctx.getValue('country');
    if (!country) return;
    
    const requestId = ctx.beginAsync('states');
    ctx.setRuntime('state', { status: 'loading' });
    const states = await fetchStates(country);
    
    if (ctx.isLatest('states', requestId)) {
      ctx.setRuntime('state', { 
        status: 'ready', 
        data: { options: states } 
      });
    }
  }
}];

<DashForm reactions={reactions}>
  <Select name="country" options={countries} />
  <Select name="state" optionsFromFieldData />
</DashForm>

• No useEffect: Reactions replace imperative effect management
• No component state: Runtime store handles async metadata
• No manual cancellation: beginAsync/isLatest pattern built in
• No prop drilling: Fields read from runtime store directly

Here's the high-level architecture of how the Form System orchestrates dynamic form behavior:

The Form System is separate from the UI components. Individual input components like TextField, Select, and Autocomplete are documented in the UI Components section.

This Form System section focuses on:

• How to set up the form provider and engine
• How to define reactions and orchestrate field behavior
• How to handle dynamic forms with conditional fields
• How to structure complex forms for maintainability
• How the runtime store and async operations work

For documentation about specific input components (props, variants, examples), see the UI Components section.