Mobx React Form Events

Skill: mobx-react-form-events

Mission

Guide the user through using event hooks and event handlers in mobx-react-form — the lifecycle system that reacts to user interactions and form actions.

Use this skill when the user needs to:

• React to value changes (onChange)
• Track focus/blur state
• Handle form submission lifecycle
• Execute code on form/field initialization
• Handle file drops or key events
• Extend default handler behavior

Event Lifecycle

The lifecycle of all events is:

User Input → Event Handler / Action → Mutate Store → Event Hook

Event Handlers

Event handlers are the functions that mutate the form/field state in response to user interactions.

Available Handlers

| Handler | Affected Property | Available On | Description | |---------|------------------|-------------|-------------| | sync(e) | value | Field | Update value (no hooks) | | onChange(e) / onSync(e) | value | Field | Update value + onChange hook | | onToggle(e) | value | Field | Update value + onToggle hook | | onFocus(e) | focused | Field | Set focused=true, touched=true | | onBlur(e) | touched | Field | Set focused=false, blurred=true | | onDrop(e) | files | Field | Handle file drops | | onKeyDown(e) | — | Field | Key down event | | onKeyUp(e) | — | Field | Key up event | | onSubmit(e, opts) | submitting | Form, Field | Submit + validate | | onClear(e) | value | Form, Field | Clear to empty | | onReset(e) | value | Form, Field | Reset to default | | onAdd(e, val) | fields | Form, Field | Add a field | | onDel(e, path) | fields | Form, Field | Delete a field |

Usage

Submit
Clear
Reset
Add Hobby
Remove

onSubmit Handler

// Validate + trigger onSuccess/onError hooks
form.onSubmit(e); // prevents default, validates, fires hooks

// With options
form.onSubmit(e, { validate: true, execOnSubmitHook: true, execValidationHooks: true });

onAdd / onDel with Values

// Add with value
 form.$('members').onAdd(e, { firstname: 'Jane' })}>
  Add Member

// Delete specific path
 form.onDel(e, 'members[0]')}>
  Remove First Member

key Events

// In component

// With handlers (curried pattern gives access to both field and event)
const fields = {
  search: {
    handlers: {
      onKeyDown: (field) => (e) => {
        if (e.key === 'Enter') {
          console.log('Search:', field.value);
        }
      },
    },
  },
};

Event Hooks

Event hooks are callback functions executed after the store mutation, letting you react to changes.

Available Hooks

| Hook | Triggered By | Available On | |------|-------------|-------------| | onInit | Constructor | Form, Field | | onChange | onChange handler | Form, Field | | onToggle | onToggle handler | Field | | onFocus | onFocus handler | Field | | onBlur | onBlur handler | Field | | onDrop | onDrop handler | Field | | onKeyDown | onKeyDown handler | Field | | onKeyUp | onKeyUp handler | Field | | onSubmit | onSubmit handler | Form, Field | | onClear | onClear / clear() | Form, Field | | onReset | onReset / reset() | Form, Field | | onAdd | onAdd / add() | Form, Field | | onDel | onDel / del() | Form, Field |

Defining Hooks

On constructor (second argument)

const form = new Form({ fields }, {
  hooks: {
    onInit(form) {
      console.log('Form initialized', form.name);
    },
    onSubmit(form) {
      console.log('Form submitted');
    },
    onSuccess(form) {
      console.log('Validation passed', form.values());
    },
    onError(form) {
      console.log('Validation failed', form.errors());
    },
  },
});

In field definitions

const fields = {
  email: {
    hooks: {
      onInit(field) { console.log('Field created:', field.path); },
      onChange(field) { console.log('Email changed:', field.value); },
      onFocus(field) { console.log('Email focused'); },
      onBlur(field) { console.log('Email blurred, touched:', field.touched); },
    },
  },
};

Via extended class

class MyForm extends Form {
  hooks() {
    return {
      onInit(form) { /* ... */ },
      onSubmit(form) { /* ... */ },
    };
  }

  // Or individual methods:
  onSuccess(form) {
    console.log('Success!');
  }
  onError(form) {
    console.log('Error!');
  }
}

Field-level Hooks

const fields = {
  password: {
    hooks: {
      onChange(field) {
        // React to password changes
        const strength = field.value.length > 8 ? 'strong' : 'weak';
        field.state.form.$('passwordStrength').set(strength);
      },
    },
  },
  passwordStrength: {
    value: 'weak',
  },
};

Form-level onChange (auto-triggered)

The Form's onChange hook is automatically triggered whenever any field value changes:

const hooks = {
  onChange(form) {
    console.log('Something changed!', form.changed);
  },
};

Validation Hooks (onSuccess / onError)

These are special hooks triggered by submit() or validate():

const hooks = {
  async onSuccess(form) {
    await fetch('/api/submit', {
      method: 'POST',
      body: JSON.stringify(form.values()),
    });
  },
  onError(form) {
    toast.error('Please fix the errors');
  },
};

Per-Field Validation Hooks

const fields = {
  username: {
    hooks: {
      async onChange(field) {
        if (!field.isValid) return;
        const res = await fetch(`/api/check-username?q=${field.value}`);
        const data = await res.json();
        if (!data.available) {
          field.invalidate('Username taken');
        }
      },
      onBlur(field) {
        console.log('Username blurred, value:', field.value);
      },
    },
  },
};

Custom Event Handlers

Via constructor

new Form({ fields }, {
  handlers: {
    onSubmit(e) {
      e.preventDefault();
      console.log('Custom submit');
      // custom logic, then call default
    },
  },
});

Via extended class

class MyForm extends Form {
  handlers() {
    return {
      onSubmit(e) {
        e.preventDefault();
        // custom submit logic
      },
    };
  }
}

Hooks and Handlers Together

const hooks = {
  onInit(form) {
    console.log('Form ready');
  },
  onSubmit(form) {
    console.log('Submitting...');
  },
  onSuccess(form) {
    console.log('Success!', form.values());
  },
  onError(form) {
    console.log('Errors:', form.errors());
  },
};

new Form({ fields }, { hooks });
// + default handlers (onSubmit, onClear, onReset, onAdd, onDel)

Key Takeaways

1. Handlers mutate, hooks react — handlers change state, hooks fire after the change.
2. Validation hooks: onSuccess and onError are triggered by submit/validate.
3. Field-level hooks: Define per-field in the field definition.
4. Form-level hooks: Define in the constructor or extended class.
5. Auto-change detection: Form's onChange hook auto-fires when any field value changes.
6. Async hooks: Hooks can return Promises for async operations.

Related Skills

• [mobx-react-form-api](../mobx-react-form-api/SKILL.md) — Core API prerequisite
• [mobx-react-form-validation](../mobx-react-form-validation/SKILL.md) — Validation hooks
• [mobx-react-form-observers-interceptors](../mobx-react-form-observers-interceptors/SKILL.md) — MobX observe/intercept

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: foxhound87
• Source: foxhound87/skills
• License: MIT

Install and usage instructions live in the source repository linked above.