Skip to content

Building Forms

This guide walks you through creating a form in the Hyvä CMS Liveview Editor and adding and configuring its fields.

Creating a Form

  1. In the admin panel, go to Content > Elements > Forms.
  2. Click Add New Form. The setup dialog opens, in two steps.
  3. Step 1, choose the type of form you want to build. Every registered form type is offered here with its own description, so pick the one that matches the form you have in mind.
  4. Step 2, fill in the details. Give the form a Title and an Identifier, switch Enable Form on when you want it live, and optionally enter a Recipient (To) and an Email Subject so the form has somewhere to send to, and a readable subject line, from the start. The Identifier field formats what you type to the allowed shape, lowercase letters, digits and underscores, with spaces and hyphens turned into underscores, so typing "Contact Inquiry" gives you contact_inquiry.

The Liveview Editor then opens with the form type you chose already in place, ready for fields. Everything else, including the rest of the submission settings, can be set later.

If the form settings fail validation when you save, the editor shows an error message and opens the Form Settings panel with the problem highlighted - a save never fails silently.

The Forms grid under Content > Elements

The grid lists every form with its identifier and status, alongside whether CAPTCHA is on. Switch on Recipient (To), Email Subject and Webhook URL from the Columns control when you want to see how forms are configured at a glance. None of those four columns can be edited in the grid, so change the values in Form Settings > Submission. Use the Select menu on any row to Edit, Duplicate, or Delete a form. Duplicate asks for confirmation, then creates a disabled copy titled "… (Copy)" with the identifier suffixed _copy (_copy_2 if that is already taken) and opens the copy for editing.

Choosing a Form Type

Every form is the same Form root, holding your fields inside one or more Form Sections. The type you pick in the setup dialog seeds that root and sets its Layout, which decides how the sections render. The layouts included today:

  • Single page: every section renders stacked on one page, with one Send button at the end. Best for contact and inquiry forms.
  • Multi-step: one section at a time, with a progress bar, a step indicator and Back and Next navigation, showing "Step N of M". Add two or more Form Section containers, one per step, and put fields in each.

A form document holds exactly one form: the setup dialog seeds its root when you create the form, and the editor never offers a way to add a second one at the top level. The Form root sits at the top of the canvas as a fixed header, its icon, its label and a pencil, rather than a component you can drag or delete. Click the pencil to open its property panel, and on the Content tab, Layout switches the form between Single page and Multi-step at any time without losing your fields, saved and restored through version history like any other content change.

The form root's own property panel carries the customer-facing settings: the submit button label, the success message and redirect, the reply-to field and conditional recipient routing. The operational settings, recipients, subject and webhook, live in Form Settings > Submission instead. See Sending and Recipients.

Form roots carry no color settings of their own. Colors belong to the content the form sits in: the Hyvä CMS Form component you embed a form with has Background Color and Text Color on its Design tab. See Embedding a Form.

The form, each of its sections and each row also has a CSS Classes field on its Advanced tab, so utility classes can be added without a custom template.

More form types can be added

Single page and Multi-step are the layouts included with the Form Builder. A module can add its own layout, or a form root with a structure of its own entirely, for example a survey-style root with a progress bar, and either appears in the setup dialog automatically. See Add a Form Layout and Create a Custom Form Root.

Building a form in the Liveview Editor

Adding Fields to a Form

The Form Builder includes these field types, which you add from a section's Add button once a form root is in place:

Field Use it for
Text Field A short, single-line answer - a name or subject line.
Textarea Field A longer message - comments or a description.
Email Field An email address, checked as a valid address in the browser and again on the server.
Phone Field A telephone number (shows the dial pad on mobile).
URL Field A full web address starting with http:// or https://.
Number Field A number, with optional minimum, maximum and decimal places.
Date Field A date, date-and-time, or time.
Single-Choice Field Pick one option from a list you define, shown as a dropdown or radio buttons.
Multi-Choice Field Pick several options from a list, with optional minimum and maximum selections.
Checkbox Field A single checkbox, ideal for a consent prompt.
Hidden Field A value captured silently - a campaign ID or source page.

More field types can be added

These are the field types included with the Form Builder. Developers and solution integrators can add custom field types that behave like the built-in ones. See Create a Custom Field.

Rich Content Inside a Form

A form does not have to be a bare list of fields. Drop a Form Content container into any Form Section and you can compose regular CMS components around your fields: text, images, columns, cards, and HTML, the same components you use on pages and blocks.

Typical uses:

  • An introduction - a heading and a short paragraph above the fields explaining what the form is for and what happens after submitting.
  • Side-by-side layouts - place a Grid or Columns component inside the container to put content next to fields, such as contact details or opening hours beside an inquiry form.
  • Rich content between fields - imagery, legal text, or a card that breaks a longer form into visually distinct groups. Fields can sit inside the container too, so a group of fields and the content that belongs with it stay together.

The container's property panel controls how the group sits in the form: Width (%) and Max Width (px) decide how much of the form width it takes, and alignment and spacing settings position it. Leave the width empty to fill the form.

Two placement rules apply: a Form Content container cannot be nested inside another one, and a complete form cannot be dropped inside a container.

Configuring a Field's Properties

Click any field in the form canvas to open its property panel on the right. Every Form Builder field has a Label (shown to the customer) and a Field Name (the machine-readable name used in the notification email - leave it blank and one is derived from the label).

Common properties include:

  • Required - the customer must fill it in before submitting. Every required field shows a red asterisk next to its label, grouped fields included: a Multi-Choice Field shown as a checkbox group, a switch group or a multi-select dropdown, and a Single-Choice Field shown as a dropdown or as radio buttons. A required Multi-Choice Field needs at least one option ticked.
  • Placeholder and Help text - guidance shown in and below the field.
  • Default value - pre-fills the field. A Single-Choice Field or Multi-Choice Field has no separate default value, tick Default on an option row in its Options list instead. A Single-Choice Field takes one default, ticking another row moves it. A Multi-Choice Field takes any number.

Field-Specific Limits in the Property Panel

Some Form Builder fields add their own options, and the storefront enforces every one of them:

  • Single-Choice Field and Multi-Choice Field let you edit the list of choices and tick which of them start selected. A Multi-Choice Field also takes Minimum Selections and Maximum Selections, and a Display As choice of checkbox group, switch group or multi-select dropdown.
  • Number Field takes a Minimum Value and Maximum Value, and Decimal Places, the most digits allowed after the decimal point. Set Decimal Places to zero to accept whole numbers only.
  • Text Field, Textarea Field and Email Field accept a Maximum Length you set.

Every text-like field also has a built-in upper limit on length, even when you leave Maximum Length empty, so nobody can use your form to send arbitrarily large content to your inbox. Your own Maximum Length can be lower than the built-in limit, never higher.

Validation Patterns and Browser-Assist Options on the Advanced Tab

The property panel's Advanced tab holds validation and browser-assist options:

  • Validation Pattern (regex) and Pattern Error Message - on the Text Field, Phone Field and URL Field, a regular expression the value must match, and the message shown when it doesn't. The whole answer has to match the pattern, not just part of it, so \d+ accepts 123 and rejects abc1. Your Pattern Error Message is exactly what the customer sees when the check fails. On a URL Field the pattern applies on top of the built-in http:// or https:// check, not instead of it, so it starts empty and only needs a value when you want to restrict the address further, to one domain for example.
  • Autocomplete - on the Text Field, hints the browser which saved value to autofill into the field. Choose from On, Off, Full name, Given name, Family name, Email address, Telephone number, Organization, Street address, Postal code or Country name. The default, None, adds no autocomplete hint. The Phone, URL and Email fields set their autocomplete tokens automatically.

A validation pattern is checked in the browser as the customer fills in the form, and again on the server when the form is sent. The server has the final say. Browsers and servers read regular expressions slightly differently, so a pattern the browser can't read is left to the server rather than blocking the customer.

Field Settings Checked When You Publish a Form

Publishing a form checks your field settings and refuses to publish while any of these problems remain, naming the field to fix:

  • Duplicate field names - two fields can't share the same field name.
  • Invalid validation patterns - a Validation Pattern (regex) that isn't a valid regular expression. Without this check, a broken pattern would reject every submission on the storefront.
  • Default values that match no option - a Single-Choice Field or Multi-Choice Field default that matches none of the configured option values. Only forms imported or saved before defaults moved onto the option rows can hit this. The message names the value too.

Saving a draft skips these checks, so you can work through a form in stages and fix everything before you publish.

What Your Customer Sees When a Form Has Mistakes

When your customer presses Send on a Form Builder form with mistakes in it, every field with a problem is flagged at once, inline beneath the field, in one consistent style. The page scrolls to the first problem and puts the cursor in it, so a mistake further down the page is never missed.

Messages clear as your customer fixes each field. In a required Multi-Choice Field, ticking an option clears the message, and unticking every option brings it back.

On a Multi-step form, Next won't move past a step that has a problem. If a problem is still waiting on an earlier step when your customer presses Send on the last step, the form goes back to that step.

Every message the form shows, validation errors included, is translatable through Magento like the rest of your storefront text.