Mobx React Form Converters

Skill: mobx-react-form-converters

Mission

Guide the user through using value converters in mobx-react-form to transform field values between the UI and the store.

Use this skill when the user needs to:

• Convert user input before storing (e.g., string → number)
• Convert stored values before displaying (e.g., number → formatted string)
• Apply input converter on init, set, or update
• Use converters in unified or separated mode

Concept

Converters are functions that transform field values at two points:

Input:  User types "5"  →  input("5")  →  store receives 5 (number)
Output: store has 5     →  output(5)  →  form.$('field').value returns "5" (string)

| Function | Direction | Purpose | |----------|-----------|---------| | input | Input → Store | Convert user input before storing | | output | Store → Output | Convert stored value when reading | | converter | Both | Alias for input/output | | converters | Both | Array of converter functions |

Per-Field Converters

Input converter

Converts user input before it reaches the store:

const fields = {
  age: {
    value: 25,
    input: (value) => Number(value),    // string → number
  },
};

form.$('age').value; // 25 (number)
form.$('age').set('30'); // store receives 30 (number)

Output converter

Converts stored value when reading it:

const fields = {
  price: {
    value: 1299.5,
    output: (value) => `€ ${value.toFixed(2)}`, // number → formatted string
  },
};

form.$('price').value; // "€ 1299.50" (string)
form.$('price').get('value'); // 1299.5 (number) — output not applied in get()

Both input & output

const fields = {
  devSkills: {
    value: 5,
    input: (value) => Number(value),        // string → number
    output: (value) => `${value}/10`,       // number → display string
  },
};

Alias: converter

const fields = {
  score: {
    value: 85,
    converter: (value) => Number(value), // same as input
  },
};

Array of converters

const fields = {
  phone: {
    value: '1234567890',
    converters: [
      (val) => val.replace(/\D/g, ''),      // strip non-digits
      (val) => val.length > 10 ? val.slice(0, 10) : val, // max 10 digits
    ],
  },
};

Separated Mode Converters

const fields = ['age', 'price', 'devSkills'];

const values = {
  age: 25,
  price: 1299.5,
  devSkills: 5,
};

const input = {
  age: (value) => Number(value),
  devSkills: (value) => Number(value),
};

const output = {
  price: (value) => `€ ${value.toFixed(2)}`,
  devSkills: (value) => `${value}/10`,
};

const converters = {
  // Array of converters per field
};

new Form({ fields, values, input, output, converters });

Apply Options

Control when the input converter is applied:

const options = {
  applyInputConverterOnInit: true,  // Apply input converter on field creation (default: true)
  applyInputConverterOnSet: true,   // Apply input converter on set() (default: true)
  applyInputConverterOnUpdate: true, // Apply input converter on update() (default: true)
};

Disable input converter in specific scenarios

const options = {
  applyInputConverterOnInit: true,   // create with conversion
  applyInputConverterOnSet: false,   // allow raw values via set()
  applyInputConverterOnUpdate: false, // allow raw values via update()
};

Real-World Examples

Number input

const fields = {
  quantity: {
    type: 'number',
    value: 1,
    input: (val) => {
      const num = Number(val);
      return isNaN(num) ? 0 : Math.max(0, Math.floor(num));
    },
    output: (val) => Number(val),
  },
};

Date formatting

const fields = {
  birthDate: {
    value: new Date('1990-01-15'),
    input: (val) => {
      if (val instanceof Date) return val;
      const d = new Date(val);
      return isNaN(d.getTime()) ? null : d;
    },
    output: (val) => {
      if (!val) return '';
      return val.toISOString().split('T')[0]; // "1990-01-15"
    },
  },
};

Currency formatting

const fields = {
  amount: {
    value: 0,
    input: (val) => {
      const cleaned = String(val).replace(/[^0-9.,]/g, '');
      return parseFloat(cleaned.replace(',', '.')) || 0;
    },
    output: (val) => {
      return new Intl.NumberFormat('en-US', {
        style: 'currency',
        currency: 'USD',
      }).format(val);
    },
  },
};

How get() interacts with converters

get('value') applies the output converter, while field.value returns the raw output-converted value:

const fields = {
  price: {
    value: 99.99,
    output: (v) => `$${v}`,
  },
};

form.$('price').value;         // "$99.99" (output applied)
form.$('price').get('value');  // "$99.99" (output applied via parseCheckOutput)

For the raw stored value, access $value directly:

form.$('price').$value; // 99.99 (raw stored value, no output conversion)

Key Takeaways

1. Two directions: input converts user input → store, output converts store → display.
2. Per-field or separated: Define in field definitions or in separated input/output objects.
3. Apply options: Control when input converter runs (init, set, update).
4. Array converters: Multiple converters run in sequence.
5. Raw access: Use $value to bypass output converter when needed.
6. Type-safe: Ensure converter input/output types match expected field type.

Related Skills

• [mobx-react-form-api](../mobx-react-form-api/SKILL.md) — Core API prerequisite
• [mobx-react-form-flat](../mobx-react-form-flat/SKILL.md) — Field definitions with converters

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.