customize Form in Frappe Framework (v15): Complete Guide
1. What is Customize Form?
The “Customize Form” feature in Frappe allows administrators to modify existing DocType forms without altering the underlying code or metadata JSON. It provides an easy UI to add, remove, reorder fields; change labels, hide fields, and tweak form layout. This feature is available in Frappe v15 and used widely in ERPNext customization.
2. Why use Customize Form?
- Rapid adaptation: Quickly reflect business changes without developer intervention.
- Safe upgrades: Since customization is stored separately, updates to core apps are easier.
- Flexibility: Change form layout, field behaviour, help text, default values, mandatory status.
- User-centred: Optimize form layout for end-users, minimize confusion, improve data quality.
3. Accessing Customize Form
Go to: Desk → Settings → Customize Form
Select the DocType you wish to customize, then use the UI to change properties such as label, fieldname, fieldtype, hidden, mandatory, default, etc.
4. Key Customization Options
| Property | Description |
| Label | The visible field name shown on the form. |
| Fieldname | Internal identifier – must remain unique. |
| Fieldtype | Data type (Data, Link, Table, Select, etc.). See official list of Field Types. |
| Mandatory | Marks field as required before save. |
| Hidden | Hide field from form view or list view. |
| Default | Default value when a new record is created. |
| Read Only | Make field non-editable on form. |
| Depends On | Use a condition to show/hide field dynamically (e.g., eval: doc.status===’Approved’). |
| In List View | Show field in list of records. |
| In Report | Make field available for reports. |
5. Implementation Details in Frappe v15
- Customizations are stored in the Customize Form Doctype rather than core Doctype JSON.
- On form load, Frappe merges the original Doctype definition with customization metadata.
- This design ensures core apps can be upgraded without overwriting customizations.
- Developers should still version-control heavy customizations or port them to custom apps.
6. When to Use Customize Form vs. Write Code
Use Customize Form if you need:
- To change only form layout or field properties
- A quick modification without new features
- End-user friendly changes
Write Code if you need:
- New validation logic in Python
- Client-side scripting in JS
- New DocType definition or customizing beyond UI
7. Best Practices & Tips
- Keep track of customizations—document changes in README.
- Avoid modifying fieldnames of core DocTypes unless absolutely needed.
- Use “Depends On” with simple conditions for performance.
- Backup customizations before heavy upgrades.
- Use Custom Apps for major features; use Customize Form for minor tweaks.
8. Troubleshooting Common Issues
| Issue | Cause | Fix |
| Changes not showing | Cache not cleared | Go to Clear Cache or run bench clear-cache |
| Field disappears after upgrade | Fieldname changed in core | Remap customization or port to custom app |
| Performance slowdown | Many heavy depends-on conditions | Simplify conditions or use JS form script |
| Data loss in hidden fields | Hidden field still stores old data but not visible | Export data or unhide field temporarily to verify |
9. Real-World Example
Suppose a company uses ERPNext and wants to add a new field “Project Code” to the Sales Invoice form:
- Open Customize Form → select “Sales Invoice”.
- Add a new field with Label=“Project Code”, Fieldname=project_code, Field type=Data.
- Set Default to blank, Hidden=0, In List View=1.
- Save & Reload. Now users see the new field without developer code changes. This new field is stored in Customize Form and persists across upgrades to ERPNext/ Frappe.
