Mobx React Form Flat

Skill: mobx-react-form-flat

Mission

Guide the user through defining flat (non-nested) form fields in mobx-react-form using unified, separated, or mixed definition modes.

Use this skill when the user needs to:

• Define flat fields with all properties in one object (Unified)
• Define fields using split property objects (Separated)
• Mix both modes in the same form
• Understand field property options
• Use common field patterns (related fields, per-field options, custom bindings)

Quick Decision Guide

| Use Case | Recommended Mode | |----------|-----------------| | Simple forms, few fields, quick prototyping | Unified — all props in one place | | Complex forms, many fields, reusable configs | Separated — props decoupled from structure | | Server-provided values (e.g. DB query) | Separated — pass values directly | | TypeScript autocomplete | Unified with Record |

Available Field Properties

| Prop | Type | Description | |------|------|-------------| | value | any | Initial value | | label | string | Field label | | placeholder | string | Placeholder text | | rules | string | DVR validation rules (e.g. 'required\|email') | | validators | array | VJF validation functions | | type | string | Field type, default "text" | | disabled | boolean | Disabled state | | deleted | boolean | Soft-deleted state (needs softDelete option) | | related | string[] | Related field paths to validate together | | default | any | Default value (used on reset) | | initial | any | Initial value (fallback for value) | | bindings | string | Binding template/rewriter key | | options | object | Field-level options | | extra | any | Extra metadata (useful for select options) | | hooks | object | Event hooks | | handlers | object | Event handlers | | input | function | Input converter: value => stored | | output | function | Output converter: stored => output | | converter | function | Value converter alias | | converters | function[] | Array of converter functions | | computed | function | Computed value function ({ form, field }) => value | | validatedWith | string | Field prop to validate instead of value | | autoFocus | boolean | Auto-focus on init | | inputMode | string | Mobile keyboard mode (none, text, decimal, numeric, tel, search, email, url) | | ref | any | React ref | | nullable | boolean | Allow null values | | autoComplete | string | HTML autocomplete attribute | | class | any | Custom Field class (unified only) | | observers | array | MobX observers | | interceptors | array | MobX interceptors |

Flat: Unified Mode

Each field is defined as an object property with all its props:

const fields = {
  username: {
    label: 'Username',
    value: 'SteveJobs',
    placeholder: 'Enter username',
    rules: 'required|string|between:5,15',
    type: 'text',
    disabled: false,
  },
  email: {
    label: 'Email',
    value: 's.jobs@apple.com',
    rules: 'required|email',
  },
  password: {
    label: 'Password',
    type: 'password',
    rules: 'required|string|min:6',
  },
};

const form = new Form({ fields }, { plugins, hooks });

TypeScript tip:

import { FieldDefinition } from 'mobx-react-form';
const fields: Record = {
  username: { label: 'Username', value: 'SteveJobs' },
};

Array syntax (unified):

const fields = [
  { name: 'email', label: 'Email', value: 's.jobs@apple.com', rules: 'required|email' },
  { name: 'password', label: 'Password', type: 'password', rules: 'required|min:6' },
];

const form = new Form({ fields });

> The name property is required when using array syntax.

Flat: Separated Mode

Define field names as a string array, then provide props in parallel objects:

const fields = ['username', 'email', 'password'];

const values = {
  username: 'SteveJobs',
  email: 's.jobs@apple.com',
};

const labels = {
  username: 'Username',
  email: 'Email',
  password: 'Password',
};

const rules = {
  username: 'required|string|between:5,15',
  email: 'required|email',
  password: 'required|string|min:6',
};

const form = new Form({ fields, values, labels, rules }, { plugins });

Auto-create from values (no fields array needed):

new Form({ values: { username: 'SteveJobs' } }); // field auto-created

Validation in separated mode:

// DVR rules
const rules = {
  email: 'required|email',
  password: 'required|string|min:6',
};

// VJF functions
const validators = {
  email: isEmail,
  emailConfirm: [isEmail, shouldBeEqualTo('email')],
};

new Form({ fields, rules, validators });

Separated property objects available: values, labels, placeholders, defaults, initials, disabled, deleted, types, related, rules, validators, bindings, extra, options, hooks, handlers, validatedWith, observers, interceptors, input, output, converters, computed, autoFocus, inputMode, refs, classes, nullable, autoComplete

Mixed Mode (Unified + Separated)

You can mix both modes. Unified props take precedence over separated ones:

new Form({
  // Separated mode props
  values: { username: 'SteveJobs' },
  labels: { username: 'Username' },
  rules: { username: 'required|string' },

  // Unified mode overrides
  fields: {
    username: {
      type: 'email',    // overrides default 'text'
      disabled: false,
    },
  },
});

Common Patterns

Fields with Default & Initial Values

const fields = {
  newsletter: {
    label: 'Subscribe',
    type: 'checkbox',
    value: true,    // initial value on mount
    default: false, // value after reset
  },
};

Fields with Per-Field Options

const fields = {
  email: {
    label: 'Email',
    rules: 'required|email',
    options: {
      validateOnChange: true,    // validate on every keystroke
      validateOnBlur: false,     // skip blur validation
      showErrorsOnChange: true,  // show errors immediately
    },
  },
};

Fields with Custom Bindings

const fields = {
  username: {
    label: 'Username',
    bindings: 'MaterialTextField', // use a registered binding
  },
};

Fields with Related Validation

const fields = {
  password: {
    label: 'Password',
    rules: 'required|min:6',
  },
  passwordConfirm: {
    label: 'Confirm Password',
    rules: 'required|same:password',
    related: ['password'], // re-validate password when this changes
  },
};

Rendering Fields

import { observer } from 'mobx-react';

const MyForm = observer(({ form }) => (
  
    
      {form.$('email').label}
      
      {form.$('email').error}
    

    
      {form.$('password').label}
      
      {form.$('password').error}
    

    Submit
    Clear
    Reset

    {form.error}
  
));

Field Selector Methods

form.$('username');              // flat field by key
form.select('username');         // same, with strict checking
form.$('email').bind();          // get bindings for input spreading
form.$('email').value;           // get current value
form.$('email').error;           // get current error
form.$('email').isValid;         // check validity
form.$('email').isDirty;         // check if changed
form.$('email').isPristine;      // check if unchanged
form.$('email').onChange;        // event handler

Key Takeaways

1. Unified mode: All field props in one object — compact, self-contained, TypeScript-friendly.
2. Separated mode: Props split across objects — flexible, decoupled, easy to generate dynamically.
3. Mixed mode: Both can be combined; unified takes precedence.
4. No fields array?: Providing values alone auto-creates fields.
5. Per-field power: Each field can override form-level options, bindings, hooks, and handlers.

Related Skills

• [mobx-react-form-api](../mobx-react-form-api/SKILL.md) — Core API prerequisite
• [mobx-react-form-nested](../mobx-react-form-nested/SKILL.md) — Nested and array fields
• [mobx-react-form-validation](../mobx-react-form-validation/SKILL.md) — Validation setup

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.