form.bindToInputs()

Quick Start (30 seconds)

const form = Forms.create(
  {
    email: '',
    password: '',
    remember: false
  },
  {
    email: (value) => !value.includes('@') ? 'Invalid email' : '',
    password: (value) => value.length < 8 ? 'Too short' : ''
  }
);

// Bind to all inputs in the form - one line!
form.bindToInputs('#loginForm input, #loginForm select, #loginForm textarea');

// That's it! All matching inputs are now connected to form state
// - Values update form automatically
// - Fields marked as touched on blur
// - Validation runs automatically

HTML:

<form id="loginForm">
  <input name="email" type="email" />
  <input name="password" type="password" />
  <input name="remember" type="checkbox" />
</form>

What just happened? bindToInputs() automatically found all inputs matching the selector and connected them to form state!

What is form.bindToInputs()?

form.bindToInputs() is a convenience method that automatically binds all DOM inputs matching a selector to form state.

Simply put, it's a one-line solution that replaces manually calling addEventListener on every input in your form.

Key characteristics:

• ✅ Accepts CSS selector for inputs
• ✅ Automatically adds input/change event listeners
• ✅ Automatically adds blur event listeners
• ✅ Matches inputs by name attribute to form fields
• ✅ Handles text inputs, checkboxes, selects, textareas
• ✅ Returns form instance for chaining
• ✅ Works with dynamic forms

Syntax

// Bind all inputs in a form
form.bindToInputs('#myForm input');

// Bind multiple element types
form.bindToInputs('#myForm input, #myForm select, #myForm textarea');

// Bind all form elements
form.bindToInputs('#myForm *');

// Bind by class
form.bindToInputs('.form-field');

// Bind all inputs on page
form.bindToInputs('input[name]');

// Chainable
form
  .bindToInputs('#myForm input')
  .bindToInputs('#myForm select');

Parameters:

• selector (string) - CSS selector to find input elements

Returns: form - The form instance (for chaining)

Requirements:

• Input elements must have a name attribute matching form fields
• Selector must match valid DOM elements

Why Does This Exist?

The Challenge: Manual Binding is Tedious

Without bindToInputs(), you need to manually bind every input element.

const form = Forms.create({
  firstName: '',
  lastName: '',
  email: '',
  phone: '',
  address: '',
  city: '',
  state: '',
  zip: '',
  country: '',
  newsletter: false
});

// ❌ Manual binding - extremely tedious!
const firstNameInput = document.querySelector('[name="firstName"]');
firstNameInput.addEventListener('input', form.handleChange);
firstNameInput.addEventListener('blur', form.handleBlur);

const lastNameInput = document.querySelector('[name="lastName"]');
lastNameInput.addEventListener('input', form.handleChange);
lastNameInput.addEventListener('blur', form.handleBlur);

const emailInput = document.querySelector('[name="email"]');
emailInput.addEventListener('input', form.handleChange);
emailInput.addEventListener('blur', form.handleBlur);

const phoneInput = document.querySelector('[name="phone"]');
phoneInput.addEventListener('input', form.handleChange);
phoneInput.addEventListener('blur', form.handleBlur);

// ... 6 more fields to go!
// 10 fields × 5 lines each = 50 lines of repetitive code!

Problems: ❌ Extremely repetitive - Same pattern for every single input ❌ Error-prone - Easy to miss an input or mistype selector ❌ Maintenance nightmare - Add/remove fields requires updating binding code ❌ Verbose - 50+ lines of boilerplate for a 10-field form ❌ Query overhead - Multiple querySelector calls

The Solution with bindToInputs()

const form = Forms.create({
  firstName: '',
  lastName: '',
  email: '',
  phone: '',
  address: '',
  city: '',
  state: '',
  zip: '',
  country: '',
  newsletter: false
});

// ✅ One line binds all inputs!
form.bindToInputs('#registrationForm input, #registrationForm select');

// Done! All 10 fields connected automatically

Benefits: ✅ One line of code - Binds unlimited inputs ✅ Automatic discovery - Finds all matching inputs ✅ Less error-prone - Can't forget to bind an input ✅ Easy maintenance - Add HTML field, it auto-binds ✅ Cleaner code - 50 lines reduced to 1 ✅ Better performance - Single query + iteration

Mental Model

Think of bindToInputs() as a form auto-wiring system - point it at your inputs and it connects them all automatically.

Visual Flow

form.bindToInputs('#myForm input')
         ↓
Query selector finds all inputs
         ↓
┌─────────────────────────────┐
│ Found Inputs:               │
│ - <input name="email" />    │
│ - <input name="password" /> │
│ - <input name="remember" /> │
└─────────────────────────────┘
         ↓
For each input:
  1. Read name attribute
  2. Add 'input' event → form.handleChange
  3. Add 'blur' event → form.handleBlur
         ↓
All inputs connected!
         ↓
User types → Form updates automatically

Real-World Analogy

Without bindToInputs (Manual Wiring):

You buy a home theater system
You manually connect each cable:
- TV to receiver (HDMI cable)
- Receiver to speakers (speaker wires)
- Receiver to DVD player (RCA cables)
- Receiver to gaming console (HDMI cable)
- Subwoofer to receiver (subwoofer cable)

Takes hours, easy to mess up

With bindToInputs (Plug-and-Play):

You buy a wireless home theater system
You press one "Auto-Sync" button
System automatically finds and connects all devices

Takes 30 seconds, everything works

How Does It Work?

Internal Process

// When you call:
form.bindToInputs('#myForm input');

// Here's what happens internally:
function bindToInputs(selector) {
  1️⃣ Query all matching elements
     const inputs = document.querySelectorAll(selector);
     // NodeList of all matching inputs

  2️⃣ Loop through each input
     inputs.forEach(input => {

       3️⃣ Check if input has name attribute
          const name = input.getAttribute('name');
          if (!name) return; // Skip inputs without name

       4️⃣ Check if field exists in form
          if (!(name in form.values)) return; // Skip unknown fields

       5️⃣ Bind change event
          if (input.type === 'checkbox' || input.type === 'radio') {
            input.addEventListener('change', form.handleChange);
          } else {
            input.addEventListener('input', form.handleChange);
          }

       6️⃣ Bind blur event
          input.addEventListener('blur', form.handleBlur);

       7️⃣ Set initial value from form
          if (input.type === 'checkbox') {
            input.checked = form.values[name];
          } else {
            input.value = form.values[name];
          }
     });

  8️⃣ Return form instance for chaining
     return form;
}

Reactivity Flow Diagram

bindToInputs(selector)
         ↓
Find all matching inputs
         ↓
For each input:
         ↓
┌────────────────────────┐
│ Bind Event Handlers    │
│ - input → handleChange │
│ - blur → handleBlur    │
└────────────────────────┘
         ↓
Set initial value
         ↓
┌────────────────────────┐
│ User Interaction       │
│ Types in input         │
└────────────────────────┘
         ↓
handleChange fires
         ↓
form.values updates
         ↓
Reactivity triggers
         ↓
UI updates elsewhere

Basic Usage

Example 1: Simple Form Binding

const form = Forms.create({
  username: '',
  email: '',
  password: ''
});

// Bind all inputs in the form
form.bindToInputs('#registrationForm input');

// Display values reactively
effect(() => {
  console.log('Form values:', form.values);
  // Updates as user types in ANY bound input
});

HTML:

<form id="registrationForm">
  <input name="username" type="text" placeholder="Username" />
  <input name="email" type="email" placeholder="Email" />
  <input name="password" type="password" placeholder="Password" />
  <button type="submit">Register</button>
</form>

Example 2: Multiple Element Types

const form = Forms.create({
  name: '',
  email: '',
  country: '',
  bio: '',
  newsletter: false
});

// Bind all form elements at once
form.bindToInputs('#profileForm input, #profileForm select, #profileForm textarea');

// Show form state
effect(() => {
  formStateDisplay.textContent = JSON.stringify(form.values, null, 2);
});

HTML:

<form id="profileForm">
  <input name="name" type="text" />
  <input name="email" type="email" />
  <select name="country">
    <option value="us">United States</option>
    <option value="uk">United Kingdom</option>
  </select>
  <textarea name="bio"></textarea>
  <input name="newsletter" type="checkbox" />
</form>

Example 3: With Validation

const form = Forms.create(
  {
    email: '',
    password: '',
    confirmPassword: ''
  },
  {
    email: (value) => !value.includes('@') ? 'Invalid email' : '',
    password: (value) => value.length < 8 ? 'Password too short' : '',
    confirmPassword: (value, allValues) =>
      value !== allValues.password ? 'Passwords must match' : ''
  }
);

// Bind inputs - validation runs automatically
form.bindToInputs('#loginForm input');

// Show errors reactively
['email', 'password', 'confirmPassword'].forEach(field => {
  effect(() => {
    const errorElement = document.querySelector(`[data-error="${field}"]`);
    if (form.shouldShowError(field)) {
      errorElement.textContent = form.getError(field);
      errorElement.style.display = 'block';
    } else {
      errorElement.style.display = 'none';
    }
  });
});

Example 4: Chaining Multiple Selectors

const form = Forms.create({
  // Section 1
  firstName: '',
  lastName: '',

  // Section 2
  email: '',
  phone: '',

  // Section 3
  address: '',
  city: ''
});

// Bind different sections separately
form
  .bindToInputs('#section1 input')
  .bindToInputs('#section2 input')
  .bindToInputs('#section3 input');

// Track completion per section
effect(() => {
  const section1Complete = form.values.firstName && form.values.lastName;
  const section2Complete = form.values.email && form.values.phone;
  const section3Complete = form.values.address && form.values.city;

  updateProgressBar([section1Complete, section2Complete, section3Complete]);
});

Example 5: Dynamic Form

const form = Forms.create({
  field1: '',
  field2: '',
  field3: ''
});

// Initial binding
form.bindToInputs('.dynamic-form input');

// Add new field dynamically
addFieldButton.addEventListener('click', () => {
  const fieldName = `field${Date.now()}`;
  form.values[fieldName] = '';

  const input = document.createElement('input');
  input.name = fieldName;
  input.className = 'dynamic-form';
  formContainer.appendChild(input);

  // Re-bind to catch new inputs
  form.bindToInputs('.dynamic-form input');
});

Advanced Patterns

Pattern 1: Conditional Field Binding

const form = Forms.create({
  accountType: 'personal',
  businessName: '',
  taxId: ''
});

// Initial bind
form.bindToInputs('#accountForm input, #accountForm select');

// Conditionally show/hide business fields
effect(() => {
  const businessFields = document.querySelector('#businessFields');

  if (form.values.accountType === 'business') {
    businessFields.style.display = 'block';
    // Rebind to ensure business fields are connected
    form.bindToInputs('#businessFields input');
  } else {
    businessFields.style.display = 'none';
    // Clear business field values
    form.setValue('businessName', '');
    form.setValue('taxId', '');
  }
});

Pattern 2: Scoped Binding with Multiple Forms

const loginForm = Forms.create({
  loginEmail: '',
  loginPassword: ''
});

const registerForm = Forms.create({
  registerEmail: '',
  registerPassword: '',
  registerName: ''
});

// Bind to specific forms
loginForm.bindToInputs('#loginForm input');
registerForm.bindToInputs('#registerForm input');

// Each form manages its own inputs independently

Pattern 3: Auto-Save on Bind

const form = Forms.create({
  title: '',
  content: '',
  tags: ''
});

// Bind inputs
form.bindToInputs('#editorForm input, #editorForm textarea');

// Auto-save when any field changes
let saveTimeout;
effect(() => {
  // Trigger on any form value change
  JSON.stringify(form.values);

  clearTimeout(saveTimeout);
  saveTimeout = setTimeout(async () => {
    await saveToLocalStorage(form.values);
    showNotification('Draft saved');
  }, 2000);
});

Pattern 4: Field-Specific Initialization

const form = Forms.create({
  email: '',
  phone: '',
  date: ''
});

// Bind all inputs
form.bindToInputs('#myForm input');

// Add field-specific enhancements after binding
document.querySelector('[name="phone"]').addEventListener('input', (e) => {
  // Format phone number
  e.target.value = formatPhoneNumber(e.target.value);
});

document.querySelector('[name="date"]').addEventListener('focus', (e) => {
  // Show date picker
  showDatePicker(e.target);
});

Pattern 5: Binding with Initial Data

async function initializeForm() {
  // Fetch initial data
  const userData = await fetch('/api/user').then(r => r.json());

  // Create form with fetched data
  const form = Forms.create(userData);

  // Bind inputs
  form.bindToInputs('#profileForm input, #profileForm select');

  // Inputs will show fetched data immediately
  return form;
}

initializeForm();

Pattern 6: Two-Way Binding with Display

const form = Forms.create({
  amount: 0,
  quantity: 1,
  tax: 0
});

// Bind form inputs
form.bindToInputs('#calculatorForm input');

// Auto-calculate and display total
effect(() => {
  const subtotal = form.values.amount * form.values.quantity;
  const total = subtotal + form.values.tax;

  totalDisplay.textContent = `Total: $${total.toFixed(2)}`;
});

Pattern 7: Binding with Custom Events

const form = Forms.create({
  color: '#000000',
  fontSize: 16
});

// Bind standard inputs
form.bindToInputs('#stylerForm input');

// Custom event for color picker
document.querySelector('[name="color"]').addEventListener('change', (e) => {
  form.setValue('color', e.target.value);

  // Emit custom event
  document.dispatchEvent(new CustomEvent('styleChanged', {
    detail: { color: e.target.value }
  }));
});

Pattern 8: Binding with Validation Display

const form = Forms.create(
  {
    email: '',
    password: ''
  },
  {
    email: (value) => !value.includes('@') ? 'Invalid email' : '',
    password: (value) => value.length < 8 ? 'Too short' : ''
  }
);

// Bind inputs
form.bindToInputs('#loginForm input');

// Automatically add validation classes
document.querySelectorAll('#loginForm input').forEach(input => {
  effect(() => {
    const fieldName = input.name;

    if (form.shouldShowError(fieldName)) {
      input.classList.add('is-invalid');
      input.classList.remove('is-valid');
    } else if (form.values[fieldName] && form.isTouched(fieldName)) {
      input.classList.add('is-valid');
      input.classList.remove('is-invalid');
    } else {
      input.classList.remove('is-valid', 'is-invalid');
    }
  });
});

Pattern 9: Binding with Debouncing

const form = Forms.create({
  search: ''
});

// Bind input
form.bindToInputs('#searchForm input');

// Debounced search
let searchTimeout;
effect(() => {
  const query = form.values.search;

  clearTimeout(searchTimeout);
  searchTimeout = setTimeout(async () => {
    if (query.length >= 3) {
      const results = await searchAPI(query);
      displayResults(results);
    }
  }, 500);
});

Pattern 10: Multi-Step Form with Conditional Binding

const form = Forms.create({
  // Step 1
  email: '',
  password: '',

  // Step 2
  firstName: '',
  lastName: '',

  // Step 3
  address: '',
  city: ''
});

let currentStep = 1;

function showStep(step) {
  currentStep = step;

  // Hide all steps
  document.querySelectorAll('.form-step').forEach(el => {
    el.style.display = 'none';
  });

  // Show current step
  document.querySelector(`#step${step}`).style.display = 'block';

  // Bind inputs for current step
  form.bindToInputs(`#step${step} input`);
}

nextButton.addEventListener('click', () => {
  // Validate current step
  const stepFields = {
    1: ['email', 'password'],
    2: ['firstName', 'lastName'],
    3: ['address', 'city']
  };

  const fieldsValid = stepFields[currentStep].every(field =>
    !form.hasError(field) && form.values[field]
  );

  if (fieldsValid) {
    showStep(currentStep + 1);
  }
});

// Initialize
showStep(1);

Common Pitfalls

Pitfall 1: Missing name Attribute

const form = Forms.create({ email: '' });

form.bindToInputs('#myForm input');

// ❌ Input without name attribute won't bind
<input type="email" />

// ✅ Include name attribute
<input name="email" type="email" />

Pitfall 2: Name Doesn't Match Form Field

const form = Forms.create({
  userEmail: ''
});

form.bindToInputs('#myForm input');

// ❌ Name doesn't match form field
<input name="email" /> <!-- Should be "userEmail" -->

// ✅ Match form field name exactly
<input name="userEmail" />

Pitfall 3: Binding Before DOM Ready

const form = Forms.create({ email: '' });

// ❌ Binding before inputs exist in DOM
form.bindToInputs('#myForm input'); // Returns empty NodeList

// Later...
document.body.innerHTML = '<form id="myForm">...</form>';

// ✅ Bind after DOM is ready
document.addEventListener('DOMContentLoaded', () => {
  form.bindToInputs('#myForm input');
});

Pitfall 4: Not Re-binding After Adding Inputs

const form = Forms.create({ email: '' });

// Initial binding
form.bindToInputs('#myForm input');

// ❌ Add new input, forget to rebind
const newInput = document.createElement('input');
newInput.name = 'phone';
formElement.appendChild(newInput);
// newInput is not bound to form!

// ✅ Re-bind after adding inputs
form.bindToInputs('#myForm input');
// Or use delegated event handling pattern

Pitfall 5: Overlapping Selectors

const form = Forms.create({ email: '' });

// ❌ Overlapping selectors bind same input twice
form.bindToInputs('#myForm input');
form.bindToInputs('#myForm input[type="email"]');
// Email input now has duplicate event listeners!

// ✅ Use specific, non-overlapping selectors
form.bindToInputs('#myForm input');
// This is sufficient

Summary

Key Takeaways

1. bindToInputs() automates input binding - one line replaces manual event listeners.

2. Uses CSS selectors - flexible targeting of input elements.

3. Automatic field matching - matches inputs by name attribute to form fields.

4. Binds both events - adds input/change and blur listeners automatically.

5. Chainable - returns form instance for method chaining.

6. Works with all input types - text, checkbox, select, textarea, etc.

When to Use bindToInputs()

✅ Use bindToInputs() for:

• Binding multiple inputs at once
• Reducing boilerplate code
• Forms with many fields
• Standard HTML forms
• Quick form setup

❌ Don't use bindToInputs() when:

• Need highly custom event handlers per field
• Working with non-standard inputs
• Need fine-grained control over binding
• Inputs don't have name attributes

Comparison: Manual vs bindToInputs()

Aspect	Manual Binding	bindToInputs()
Code for 10 fields	50+ lines	1 line
Queries	10 individual	1 querySelectorAll
Maintenance	Update each field	Update selector
Error risk	High	Low
Flexibility	Full control	Convention-based
Performance	Multiple queries	Single query
Scalability	Poor	Excellent

Typical Usage Pattern

// 1. Create form
const form = Forms.create(
  { email: '', password: '' },
  {
    email: (value) => !value.includes('@') ? 'Invalid' : '',
    password: (value) => value.length < 8 ? 'Too short' : ''
  }
);

// 2. Bind all inputs in one line
form.bindToInputs('#loginForm input');

// 3. Display errors reactively
effect(() => {
  if (form.shouldShowError('email')) {
    emailError.textContent = form.getError('email');
  }
});

// 4. Handle submission
form.submit(async (values) => {
  return await loginAPI(values);
});

What Gets Bound

For each matching input, bindToInputs() adds:

• Change/Input event → form.handleChange
• Blur event → form.handleBlur
• Initial value → Set from form.values[name]

Related Methods

• handleChange(event) - Manual change handler
• handleBlur(event) - Manual blur handler
• getFieldProps(field) - Get props for individual field
• setValue(field, value) - Manual value updates

One-Line Rule

form.bindToInputs(selector) automatically finds all DOM inputs matching the selector and connects them to form state by adding change and blur event listeners, eliminating the need for manual input binding.

What's Next?

• Explore dynamic form patterns
• Master event delegation techniques
• Build complex multi-step forms