Using Ant Design Form.List to Add and Remove Repeatable Form Fields

Problem and takeaway

When a form needs a variable number of similar entries—for example, a list of phone numbers, addresses, or team members—manually handling array state, validation, and key management becomes error‑prone. Ant Design’s Form.List component solves this by providing a declarative way to render repeatable fields while keeping each item’s validation state and submitted values in sync with the parent form.

How it works: a worked example

The following snippet shows a form that lets users add and remove email addresses. Each email field is validated as a required email address. The Form.List receives a name that points to the array path in the form’s values.

import { Form, Input, Button, Space } from 'antd';
import { PlusOutlined, MinusOutlined } from '@ant-design/icons';

const EmailListForm = () => {
  const onFinish = (values) => {
    console.log('Submitted values:', values);
  };

  return (
    
      
        {({ fields, add, remove }) => (
          <>
            {fields.map((field) => (
              
                
                  
                
                }
                  onClick={() => remove(field.key)}
                  disabled={fields.length === 1}
                />
              
            ))}
            
              } onClick={() => add()}>
                Add email
              
            
          
        )}
      
      
        
          Submit
        
      
    
  );
};
export default EmailListForm;

Explanation of the key parts:

• Form.List name="emails" tells Ant Design to treat the wrapped content as a repeatable group stored under values.emails.
• The render prop receives fields (an array of field objects each with a unique key), and the helper functions add and remove.
• Each iteration renders a Form.Item whose name is an array [field.name, 'email'], which maps to values.emails[index].email.
• The key prop on the outer wrapper (Space) is set to field.key; this satisfies React’s list‑rendering requirement and prevents warnings about missing keys.
• The remove button is disabled when only one item remains, avoiding a state where validation rules that depend on a non‑empty array could be violated.

Limits and common mistakes

Performance with large lists

Every item in a Form.List mounts a full subtree of form components. If the list grows to hundreds of items, re‑rendering can become noticeably slow. Mitigation strategies include:

• Virtualizing the list (e.g., using react-window) and only rendering visible items.
• Moving heavy validation or expensive calculations out of the form fields and into a separate processing step on submit.

Missing or duplicate keys

If you omit the key prop on the element returned from the fields.map callback, React will warn about missing keys and may lose internal state when items are reordered or removed. Always use the field.key provided by Form.List.

Mutating field values directly

Attempting to change a field’s value by assigning to field.value or by calling setFieldsValue with a mutated array bypasses Ant Design’s internal tracking. Use the add and remove helpers, or call form.setFieldsValue with a completely new array.

Hydration mismatches in SSR

When rendering the form on the server (e.g., Next.js) and hydrating on the client, the initial length of the emails array must match between server and client. A mismatch leads to React hydration errors. Ensure that any server‑side data fetching returns the same initial array length as the client expects.

Validation dependence on list length

If a validation rule (e.g., min: 1) depends on the array having at least one element, removing the last item will trigger a validation error immediately. This is usually desired, but be aware that the form will be in an invalid state until the user adds a new item or adjusts the rule.

Checking that it works

After integrating the component, you can verify correct behavior with these steps:

1. Render the form in a browser.
2. Click “Add email” several times; each new input should appear with its own remove button.
3. Fill in some values, leave others blank, and submit.
4. Open the browser console; you should see a logged object like { emails: [ { email: '[contact removed]' }, { email: '[contact removed]' } ] } with exactly as many entries as you added.
5. Confirm that no warnings about missing keys or duplicate names appear in the console.
6. Remove items using the minus button and submit again; the array should shrink accordingly.

If any of the above checks fail, review the key usage and ensure you are not mutating the field array directly.