Skip to content

[6.x] Forms 2: Generate field handles from labels - #15203

Merged
jasonvarga merged 2 commits into
forms-2from
forms-2-field-handles
Aug 17, 2026
Merged

[6.x] Forms 2: Generate field handles from labels#15203
jasonvarga merged 2 commits into
forms-2from
forms-2-field-handles

Conversation

@duncanmcclean

@duncanmcclean duncanmcclean commented Aug 17, 2026

Copy link
Copy Markdown
Member

This pull request changes how field handles work in the form builder. Previously, when you added a field, Statamic would generate a random ID for its handle, rather than "slugifying" the label like the blueprint builder does.

The motivation for random IDs was that changing a field's label later wouldn't leave it with a stale, mismatched handle — with Forms 2.0, we really want people to use the {{ fields }} loop to dynamically render fields, rather than hard coding fields, which isn't practical when clients might be editing forms. However, over time, the random handles have become a little awkward:

  • When you're looking at a submission's YAML file, it's really difficult to identify fields.
  • When we send webhooks, the keys in the payload are a bunch of gibberish with no way to know which field is which.
  • When integrating with Google Sheets, we use the handle as the column name (to avoid creating a new column when a label changes), but again, the column names are all gibberish.
  • If you wanted to match up a handle to a label, you'd need to dig into the form's fields array, since handles aren't exposed anywhere in the UI.

This PR fixes it by generating handles from labels, like the blueprint builder:

  • When you add a field, a "Handle" setting is shown in the field inspector, auto-generated from the label as you type.
  • Once the form has been saved, the handle can no longer be changed (to avoid breaking references in submissions and logic), and the handle setting is hidden.
  • Handles are validated when saving the form: they're required, must be unique, and can't use reserved words — including the forms-specific ones (date, message and messages), as per the docs.
  • To prevent handle collisions when adding multiple fields of the same type without renaming them, default labels are made unique ("Toggle", "Toggle 2").

Warning

Forms created before this PR will have randomly generated handles. Any handle starting with a digit will now fail validation when saving the form, so you may need to fix up or recreate fields on existing forms.

duncanmcclean and others added 2 commits August 17, 2026 15:32
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@jasonvarga
jasonvarga merged commit 25266cc into forms-2 Aug 17, 2026
118 of 122 checks passed
@jasonvarga
jasonvarga deleted the forms-2-field-handles branch August 17, 2026 18:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants