Layout Fields

Organize your forms with non-input fields like section breaks, headings and hidden fields for better structure and data capture.

Overview

Layout fields help structure your forms and capture metadata without requiring user input. Polyform provides three layout field types: section_break for dividing forms into logical sections, heading for organizing related fields and hidden for storing values not visible to users.

Section Break

Use the addSectionBreak() method to divide your form into distinct sections. Section breaks display a title and optional description, helping users understand the form's structure.

app/Actions/CreateSurveyForm.php

Multi-Step Forms

For multi-step forms, use the addStep() method instead of section breaks. Section breaks are for visual organization within a single step or page.

Heading

The addHeading() method creates a heading to group related fields together. Headings provide visual hierarchy without the extra spacing of section breaks.

app/Actions/CreateApplicationForm.php

Hidden Field

Use addHidden() to include data in form submissions that users don't see or edit. Perfect for tracking metadata, IDs or source information.

app/Actions/CreateTrackedForm.php

Security Note

Hidden fields are not truly hidden from technically savvy users who can inspect and modify the HTML. Never use hidden fields for sensitive data or values that must be trusted. Always validate and sanitize hidden field values on the server side.

Combining Layout Fields

Layout fields work together to create well-organized, professional forms.

app/Actions/CreateRegistrationForm.php

Available Settings

Setting	Type	Field Type	Default	Description
`description`	string	section_break	null	Optional descriptive text displayed below the section break title.
`default_value`	mixed	hidden	null	The value to store for the hidden field. Can be any scalar value or array.

Validation

Layout fields have minimal validation requirements:

Section Break & Heading: No validation (display-only fields)
Hidden Field: Value is included in submission data as-is; can be validated like any other field if needed

Common Use Cases

Section Breaks

Dividing long forms into logical sections (Personal Info, Address, Payment)
Providing context before a group of related questions
Creating visual breathing room in dense forms

Headings

Grouping fields within a section
Creating subsections without the visual weight of section breaks
Organizing repeater field groups

Hidden Fields

Tracking UTM parameters and marketing sources
Storing referrer URLs
Including form version or variant IDs
Passing through entity IDs (e.g., event_id, product_id)
Recording timestamps or session data

Best Practices

Use section breaks for major divisions in your form (3-4 sections maximum). Use headings for minor groupings within sections. Use hidden fields sparingly and only for non-sensitive tracking data.

Repeater Fluent API