User guide

HolmesPortfolio Forms

Build a form, put it on a page, and deal with what people send in. Start with the quick start. Keep the rest as a reference for when a question comes up.

Overview #

A form is fields laid out over one or more pages. You build it in the visual editor and drop it onto any page or post with a shortcode or a block. When someone submits, the plugin emails the answers to whoever needs them, shows the person a message back, and, if you want, keeps a copy in Entries.

Out of the box, forms use the GOV.UK Design System. It’s made by the Government Digital Service (GDS), and the UK government uses it for its own online services. We recommend it, and people already know how it works from GOV.UK. GOV.UK says: “Using the GOV.UK Design System in a service does not immediately make that service accessible.” Test each published form. Making your forms accessible is your responsibility. Which questions follow GOV.UK shows what to check. Wherever a setting has a choice that matches GOV.UK’s guidance, that choice is the default and is marked recommended.

Most questions use GOV.UK Design System components, without the GOV.UK crown, header, footer or GDS Transport typeface, which only services on GOV.UK may use. Text is set in Helvetica or Arial instead. Your own site supplies the header, logo and colours around the form. If your forms are on a gov.uk address, your theme adds the GOV.UK header and font.

Prefer Bootstrap, a plain self-contained look, or nothing but your own theme? Switch it in Settings.

Pro and Casework are paid add-ons, and they’re coming soon. They aren’t for sale yet. Anything marked Pro, coming soon in this guide is part of them.

You also get 13 ready-made forms to learn from, in six groups. The setup wizard lets you pick the ones you want:

• Customer contact: Simple enquiry form and Feedback, compliment or complaint
• Complaints & reports: Make a complaint and Report a fault
• Bookings & appointments: Book an appointment or callback and Event or room booking
• Data & information requests: Freedom of Information request (for public bodies only) and Subject Access Request
• Council services: Report a problem, Book a council appointment and Council feedback, compliment or complaint
• Worked examples: Calculation examples and Costs and pay examples

Open them, take them apart, and copy what fits. Each one is an example, written in good faith. It is not legal advice. Check it and set your own before you publish. See The forms you start with.

Quick start #

Activating the plugin opens a short setup wizard. It asks a few site-wide questions:

• how forms look
• what’s stored, and for how long
• where email comes from
• spam
• which starter forms to add

You can change any answer later in Settings. Skipped the wizard, or want to check your choices? The Run the setup wizard button on Settings → Help & support brings it back. Pro adds its own steps to the same wizard for the licence key and your workflow. On the Casework plan it also asks about team access and team members.

When you finish, choose Build a form or Go to Forms. The Forms screen has a Form tutorial button with short walkthroughs for each part of the builder. On the Plugins list, the row has Forms and Settings links.

Put a form on a page #

Every form has a shortcode. Find it on the Forms list, or on the builder screen after the first save.

[holmesforms_form id="123"]

In the block editor you can instead add the HolmesPortfolio Form block and pick the form from a dropdown, with no id to copy. The form looks the same either way.

Want a page of its own for the form? Press Add to a new page, next to the shortcode on the Forms list or in the builder. It makes a draft page with the form already in it and opens that page in the editor. The page takes the form’s title, which you can change. Check it over, then publish. The button only shows for people who can edit pages.

Page caches and security plugins. Forms keep working when:

• a page cache sends the same page to many people
• a security plugin blocks part of WordPress for visitors.

A few things to know:

• The plugin tells caches not to store form pages or form replies. Besides WordPress’s standard no-cache signals, it tells LiteSpeed servers and the LiteSpeed Cache plugin directly. If your cache ignores all that, exclude those pages in its settings. The Site Health check tells you if form replies are being cached.
• If the connection drops at the moment of sending, the visitor is told the form may have gone through. They’re asked to check for a confirmation email before sending it again.

Cookies. The plugin sets no cookies of its own. Customers who sign in on the Pro Casework plan use WordPress’s own login cookie. If you turn on Turnstile or reCAPTCHA, Cloudflare or Google reads information from the visitor’s browser and can set cookies. UK cookie rules cover reading from a visitor’s browser as well as setting cookies.

Visitors without JavaScript. By default a form is hidden from anyone with JavaScript turned off. They see a short message asking them to turn JavaScript on and reload the page, or to contact you another way. You choose this under Visitors without JavaScript on Settings, General.

If you choose Let them fill it in without JavaScript, every page shows at once and the form is sent in one go. The thank-you page still shows the reference number. Here’s what stops working for those visitors:

• Pages with a show or hide rule are left out, so their questions are never asked.
• Questions and groups with a show or hide rule stay as they first load. Any that should appear after an answer never appear.
• A list that changes with an earlier answer shows every choice. If someone picks a choice that doesn’t match their earlier answer, they see an error asking them to pick another.
• Repeatable group Pro, coming soon: Add another does nothing, so people can fill in the group only once.
• Find address does nothing. People can still type their address into the boxes.
• A spam check (Turnstile or reCAPTCHA) can’t run. A form that uses one stays hidden, with the message asking them to turn JavaScript on.
• Map question Pro, coming soon: the map, its search box and Use my current location do nothing. People can only type into the latitude and longitude boxes.
• Signature Pro, coming soon: people can’t draw or type a signature. If the signature is required, they can’t send the form.

These still work without JavaScript: file uploads, sliders and star ratings, plus the Pro booking calendars, holiday stays and payments.

Once you let people in, a list appears under the setting. It shows each of your forms and what won’t work on it, with a pointer back to the option that hides the form.

The builder warns you too. When a saved form gains something that won’t work without JavaScript, the builder shows a warning. You see each kind of warning once per form. Admins also get a link to the setting.

Taking a form down. A form stops taking answers as soon as you unpublish it, switch it to draft or move it to the bin. That includes visitors who already had the page open.

Sent twice by mistake. If a visitor double-clicks the send button, the form is saved once. The second send tells them it was already sent.

The builder screen #

Describe your form #

Forms → Describe your form is a quick way to start:

• Tick the common questions you want: full name, email address, phone number, address, a message, a file upload, a date, a time or a rating.
• Add questions of your own, each with an answer type.
• Every question starts optional. Tick Required on your own questions, or change any question in the builder.
• Choose one page or several. With several, you can tick End with a Check your answers page. It gets its own last page, with the submit button and emails, so the visitor can check before sending.
• Start from a saved block if you like, and have the team email and a customer copy set up for you.
• The team email uses [all-fields], so it sends every answer. That includes questions you add later.

Build a draft opens the result in the builder. Nothing is saved until you press Save. If you pick the Customer contact block, the name, email and phone ticks are skipped, so the same question never appears twice.

Naming, grouping and copying forms #

Above the builder sits the Form title, which you and your visitors see. Next to it is an optional Group box for tagging related forms, like Contact forms, Highways or Licensing.

• Start typing and it offers groups you already have.
• The Forms list then has a Group column and a group filter beside the search box, which helps on a site with dozens of forms.
• A group is only a label. Adding or removing one never changes how a form behaves.
• A group with no forms left in it drops out of the filter by itself.

Duplicate, on a form’s row in the Forms list, copies the form and opens the copy in the builder. The copy has the original’s title with “(copy)” on the end, so give it a new one.

• It keeps the pages, questions, emails and group.
• It keeps the Setup tab settings too, such as variables and the case view. Only the front-end debugger starts switched off.
• It keeps this form’s own Settings choices for storing entries and for blocked words.
• It starts with no entries. Its version history starts with a note saying which form it was copied from.
• It keeps the original’s reference prefix. Give it its own on the Setup tab, so you can tell the two forms’ entries apart.
• It has its own shortcode, so it isn’t on any page until you add it.

Open one of the starter forms and the builder shows a note. Restore starter content can reset a starter form to its built-in version. So if you plan to make one your own, rename it first. A restore then leaves your renamed copy alone and adds a fresh copy of the original. A duplicate has its own title, so a restore leaves that alone too.

Saved blocks #

Tick the fields you want and press Save selected as a block to keep them as a named saved block for other forms.

• Tick a group to save it with everything inside it. Tick one question inside a group to save just that question.
• You can also right-click a group and choose Save as a block. The group’s title is filled in as the block’s name, and you can change it.
• A Repeatable group Pro, coming soon keeps its settings, such as the fewest and most entries and the Add another button text.
• When you insert a block, any question name the form already uses gets a number on the end, such as email_2. No two questions share a name.

• To use one, type or pick its name in Find a block under the field list, then press Insert.
• Lock / Unlock, beside Insert, stops a block being deleted or overwritten by mistake.
• Delete only shows once a block is unlocked. For a built-in block, it hides it from the picker instead of erasing it.

To bring the three built-in blocks (Privacy notice, Terms and conditions, Customer contact) back, or to download them as a backup file, use Settings → General → Restore starter content. Restoring never touches a block you have locked. If you have an unlocked block of your own with one of those names, it lists it and asks you to confirm before replacing it.

Saved blocks travel between sites, locks included, in a backup. Blocks are matched by name. Importing adds any block with a new name. If the site already has a block with that name, the site’s own block is kept, unless you tick Replace… and confirm.

Right-click any field in the field list for a menu: Edit, Move up, Move down, Duplicate, Copy field, Cut field, Paste field after and Delete. On a group, the menu also has Save as a block.

Copy and Cut move a single field. The clipboard holds one field (a group brings its contents) and survives opening a different form, so you can copy a field from one form and paste it into another. A pasted field gets a fresh data name if its own would clash.

The ? help dots #

Every field and every setting in the builder carries a small ?. Click it for a plain-English line, and a Read more in the guide link that jumps this page to exactly that setting. The one-liner shows even with no internet. Only the link needs a connection.

The Form tutorial button on the Forms screen takes you into a practice form with a list of hands-on topics. They include your first form, kinds of question, groups, labels and hints, lists of choices, dates and times, addresses and files, show and hide rules, pages, calculations, hidden fields, emails, thank-you messages, HTML and tokens, publishing, entries, settings, backups and saved blocks.

Two topics walk through every calculation on a starter form: Every calculation, step by step uses the Calculation examples form, and Costs, pay and dates, step by step uses the Costs and pay examples form. If the form isn’t on your site yet, you’re asked first. You can add it, and it stays after the tutorial until you delete it. Or you can look through a practice copy, which isn’t saved unless you press Save.

• Each topic runs on the practice form or on the real screen. Nothing on the practice form is saved unless you press Save, which asks you first. Anything you save on a real screen is saved for real.
• Finish or skip and you’re back at the list, with a tick beside the topics you’ve done.
• With Pro, a Pro tutorials button beside it (and at the top of Settings) does the same for the Pro features.

Fields #

Every field shares the options in Every field's common options. The tables below cover only the settings specific to each type.

Text input #

A single-line box. Use the input mode to collect an email, phone number, web address, number or amount of money.

Text area #

A multi-line box for longer answers.

Radio buttons #

Pick one from a short list. The list is a group, so the Label becomes its legend. Always fill it in.

Checkboxes #

With no options, it's a single yes/no tick (good for “I agree”). Add options and it becomes a “choose any” list.

Dropdown #

Pick one from a longer list. Options work the same as radio buttons, including Pre-select from the query string. Set a field width to stop a long list stretching the box.

Slider #

A number chosen on a track. The current value shows beside it, and arrow keys move it exactly, so it works without a mouse. A slider always has a value, so “required” does nothing for it.

Star rating #

A row of stars for a quick score. The visitor picks a whole number of stars. There are no half stars. It’s a normal radio group underneath, so arrow keys work. Each star is named for screen readers, such as “5 stars out of 5”. The answer is stored as the number and shown as “3 out of 5 stars” on the summary, in emails and in the spreadsheet export.

Date #

Three boxes in the order day, month, year, following the GOV.UK date input component. Answers are written DD-MM-YYYY on the summary, in emails and in the spreadsheet export. There is no month-first option.

Time #

A short box for a time of day, like 09:30. GOV.UK had no time component when we checked in October 2026, so this follows its guidance for an answer of a known length: a text box sized to fit (five characters wide for 24-hour times), with the number keypad on a phone when no letters are needed. The visitor can always type the time.

What people may type: 09:30, 9:30, 09.30, 0930 and 930 for 24-hour, and 9:30am, 9.30 pm, 9am and 9:30 a.m. for 12-hour. Whatever they type, the answer is stored as 24-hour HH:MM, so exports and comparisons see one shape. The error messages you can reword are left empty, wrong type, outside the range and not later than the other time.

Measurement #

A height, distance, weight, volume, area or temperature that people can give in their own units. When you allow more than one unit, a Unit dropdown shows. Feet and inches, and stone and pounds, show two boxes.

Emails, entries and the summary show what the visitor typed and the converted value, like 5 ft 10 in (177.8 cm). In a formula, [height] is the converted number, so a body mass index (BMI) from answers in any units is [weight] / ([height] / 100 * [height] / 100) with height in centimetres and weight in kilograms.

Address #

Line 1, town and postcode, plus an optional line 2, and county and country you can switch on.

• Line 1, town and postcode are required once anything is typed. The postcode is checked against the UK format.
• Line 2 is always optional.
• County and country follow the field’s own Required setting. On a required address, they’re required too: the label drops “(optional)” and each gets its own error-message box.
• Once it’s filled in, the visitor can press Save address to fold it into a read-only summary. A Change address button opens it again.

Find address: postcode lookup

Turn this on at Settings → Connections and a Find address box appears above every address field. The visitor types their postcode and presses the button, and the town, county and country fill in.

• It’s free. It uses the free postcodes.io service, so there’s nothing to sign up for.
• That service has no service guarantee and may limit or block heavy use. For a busy site, run your own copy of postcodes.io, which is open source. Or use a paid service that sends addresses back in the same format. Then put its address in Postcode service address on the same tab. It must start with https://. On a local or development site, http:// works too.
• HolmesPortfolio doesn’t supply or pay for postcodes.io or any service you put there.
• The visitor’s postcode is sent there when they press the button, so mention that in your privacy notice.
• The data comes from Ordnance Survey, Royal Mail, National Statistics and National Records of Scotland. Add this credit to your site, for example on your privacy or terms page: “Contains Ordnance Survey data © Crown copyright and database right. Contains Royal Mail data © Royal Mail copyright and database right. Contains National Statistics data © Crown copyright and database right. Contains NRS data © Crown copyright and database right.”
• Northern Ireland postcodes (starting BT) are free for non-commercial use only. Commercial use needs a licence from Land & Property Services in Northern Ireland. See the postcodes.io data licences (opens in new tab).
• With JavaScript off, or if the lookup can’t be reached, the plain boxes are still there to type into.

A form can have as many address fields as it needs. Each one gets its own Find address box and fills only its own boxes.

• That includes address fields on later pages. It also includes a Pro repeatable group, where every “Add another” entry gets its own box.
• Each box is named after its address field for screen readers.
• Each lookup is one small request to the postcode service. Your site keeps each answer for 30 days, so repeated postcodes don’t make extra requests. If a postcode isn’t found, that answer is kept for an hour.

That gets you the postcode area, not the exact house. For a proper “pick your address from a list” with house and flat numbers, you need the Pro add-on and an address provider. You sign up to a provider yourself. HolmesPortfolio doesn’t supply one, and the provider may charge. Then connect it on the same Settings tab:

1. Choose getAddress.io, Ideal Postcodes or Ordnance Survey Places, or a custom endpoint.
2. Paste your API key.
3. Press Test a postcode to check it.

File attachments #

Drag-and-drop or browse for files. Files are attached to the email. They aren’t kept in Entries. The site holds them only until their emails have gone, then deletes them. The first time you add this field, the builder shows a short note about handling uploads safely. Once you’ve read it, tick Don’t show this again on this computer.

Showing an uploaded image in the email. By default the email lists only the file name and size. To show the picture in the message, put [img:data-name] in the email body. For example, use [img:photo] for a field whose Data Name is photo. The Insert bar in the email editor has a “… image” button for each upload field that adds this for you.

• In an HTML email it becomes a small thumbnail, about 500 px on its longest edge, so the message stays small.
• In a plain-text email it stays as the file name.
• A few email plugins can’t place pictures inside the message. The file name shows instead, so the email still says which file was sent.
• A very large image (over about 12 MB or 30 megapixels) isn’t made into a thumbnail. It shows as its file name and travels only as an attachment.
• The full-size file is still attached if the email action has Attach files uploaded through the form ticked.
• The Pro PDF of the answers adds uploaded images the same way, automatically.

Handling uploads safely

An accepted file type isn’t the same as safe contents. A genuine PDF or image can still carry something harmful. Checking and handling what people send is your responsibility as the site owner. To help with that:

• Any email that carries uploads ends with a short line reminding whoever gets it to scan the files, and only open ones they were expecting.
• Each email action has Attach files uploaded through the form on by default. Turn it off on emails whose recipient doesn’t need the files.
• Route form mail through a gateway that scans attachments (Microsoft 365 and Google Workspace both do), and keep readers patched.

Content & controls #

Alert / notice #

A block of text on the page: guidance, a warning, or something to agree to. It’s part of the page, so screen readers reach it along with the fields. In the text you can use:

• basic HTML
• tokens, where [data-name] is replaced with an earlier answer
• <if key>…</if>, which shows part of the notice only when that field has a value. That’s handy for a message that reacts to what the visitor picked on an earlier page.

Built-in blocks

Three blocks come with the plugin. They start locked, so they can’t be deleted. Unlock one from the field-list bar to hide it or clear it out.

• Privacy notice and Terms and conditions. Each is one alert with its “confirm you have read this” checkbox turned on, so the visitor can’t send the form until they tick it. Both carry placeholder wording you must replace. The builder shows a red reminder on the alert, and the words “replace before publishing” appear in the text. Change the text and the example.com link before the form goes live. A privacy notice doesn’t need a tick box, and a tick isn’t consent. Remove the privacy notice’s tick box unless you have a reason for it.
• Customer contact: a group titled Customer details asking for a name, email and phone number. Each question has a short hint. You can change the hints and the title like any other question.

Pick one in the Find a block box under the field list and press Insert.

• Each built-in block starts locked. Unlock it there to hide it from the picker.
• Anything hidden or unlocked comes straight back from Settings → General → Restore starter content. The starter blocks are built into the plugin, so there’s nothing to back up.
• A confirmed alert shows as Yes in the answers summary, emails and the spreadsheet export.

Hidden field #

A value the visitor never sees. It’s included in the entry and the emails. It’s left out of the answers summary, unless you type its [data-name] token there yourself. Use it to record where an enquiry came from, to copy an answer, or to calculate something.

A hidden field that records something about the signed-in user, or a value from the page address, gets a note in Form check. People can’t see what it collects, so say in your privacy notice what it records and why.

Button #

One button that does a different job depending on Does: Go to next page, which shows as Continue, or Submit the form. A new button starts on Go to next page. A Back button appears by itself whenever there’s a previous page, and on any page a visitor opens from Check your answers. Back keeps what was typed on the page without checking it. Only Continue checks a page and saves its answers. Leave the label blank to use the usual wording for the button’s job.

A Submit the form button also has a Hide the Back button on this page tick box. It’s useful on the automatic Check your answers page, where each answer already has its own Change button. An Answers summary has a Go to button for each page instead.

What staff see as the Answers section on an entry is set per form, by the Case view box on the Setup tab.

Email action #

Sends an email when the form is submitted. Add as many as you need.

• An email action sends unless it sits on a page a rule hid, or inside a group whose show/hide rule hid it. To send an email only in certain cases, put the action in a conditional group.
• Mail goes out through WordPress’s wp_mail(). How much gets delivered depends on your host and mail setup, not the plugin. See Emails for more.

Submit message #

What the visitor sees after a successful submit, in place of the form. It can be HTML or plain text.

• It takes the same tokens as an email, including [case-reference]. See the full list of built-in tokens.
• If you add more than one, the form shows the last one that isn’t on a hidden page or in a hidden group.
• Like an email action, a submit message inside a group that a rule hid is skipped. So you can show a different thank-you depending on what the visitor chose.

Answers summary #

Let people check their answers before they send the form. Adding an Answers summary replaces the automatic “Check your answers” page.

It starts with the answers already written out as HTML you can edit:

• a section for each page, with the page title as a heading
• a heading for each group that has a title
• one line for each answer, such as <dt>Your name</dt><dd>[your_name]</dd>
• a button such as Go to Your details for each page, if the form has more than one page

The answer lines sit in a list (<dl>), which keeps each answer with its question in the page’s code. You can edit, move or delete any line. The All fields button under the editor puts the full list back in.

A question you add to the form later doesn’t appear in the summary until it has a line. The editor names any missing question under Not in this summary. Add its line yourself, or press Update from the form to rebuild the whole summary. That replaces your edits, so you press it twice to be sure.

When the summary shows on the form:

• pages and questions that a rule hides are left out
• a question left blank says Not answered
• the Go to buttons take the form’s button style
• a form with only one page shows no Go to buttons

You can type [all-fields] instead, as a shortcut. It shows the full list, but you can’t edit its lines.

Answers show in words people can read:

• A confirm alert shows Yes or No.
• A multi-select checkbox shows the options the visitor ticked. With [all-fields], it lists every option with Yes or No.
• A radio or dropdown shows the chosen option’s label, not its stored value.
• A file upload shows the name and size of each file.

The Pro PDF groups answers the same way. So does [all-fields] in an email. The summary’s editor offers the same built-in tokens as an email action, so [page-title] and [case-reference] work here too.

The plugin builds the summary on the server, from the same answers the emails use. File names are the one exception. The visitor’s browser fills those in.

Visitors can’t change answers in the summary itself. The Go to button takes them back to that page, with their answers still filled in. The summary doesn’t save anything, so it doesn’t need a Data Name.

A page opened this way has a Back button, even if it’s the first page. Back returns the visitor to the summary and drops any edit on the page. The answers they had already confirmed stand. Continue saves the edit and returns them to the summary, without taking them through every page again.

• If the change reveals a new question on a later page, the visitor answers it first, then comes back to the summary.
• If the change affects nothing else, they come straight back to the summary.
• If the change hides a question that had an answer, that answer is dropped.

A declaration tick box such as “I confirm my answers are true” can be set to clear when another answer changes, so the visitor ticks it again for the answers they now have.

The button at the bottom of the summary sends the answers it showed. If they’ve changed in the meantime, for example in another browser tab, the summary shows again with the message “Your answers have changed since this page was last shown. Check them, then use the button below.” If the server refuses a send because an answer needs fixing, the visitor goes to that page. From there, Continue moves to the next page with a problem, or back to the summary once there are none left.

The automatic Check your answers page works the same way. It has a Change button for each answer, where the summary has a Go to button for each page.

Groups (containers) #

A group (container) is a box you drag questions into. You don’t have to use one. Questions work the same in or out of a group.

What a group adds is a name. Give it a Title and that becomes a heading over its questions. The heading shows on the form, the check-your-answers page, the emails and the PDF. Leave the title blank and the group adds no heading. The heading levels around it still run in order, with none skipped.

The first time a page has a question outside a group, the builder shows a tip. Group them puts those questions in a group for you. Don’t show again hides the tip. Either button hides it for good, for you only.

Under Layouts in the component palette there are three kinds:

• Group: a plain box. Give it a title to put a heading over related questions.
• Conditional group: a box with a show/hide rule. Everything inside appears or disappears together. It reacts straight away to an answer on the same page, and it can use answers from earlier pages too. When it's hidden, the fields leave the page completely and their answers are cleared from the entry and the emails.
• Repeatable group Pro, coming soon: people can fill in the group more than once. The entries are stacked, with an “Add another” button after them, and each entry has its own × to remove it. Without Pro, it shows in the palette with a padlock.

To move a question into a group or out of one, pick from the Group list in the question’s settings. You don’t need to drag it.

A repeatable group needs the Pro add-on. It has a few rules worth knowing:

• Only plain question fields repeat: text, text area, radio, checkboxes, dropdown, slider, star rating, date, time and address, plus a Pro Booking calendar. A File attachments field cannot go in a repeatable group, and it is not offered as a child. Keep one attachments field outside the group instead, with its own file count. That keeps the total upload size for a submission predictable.
• Give the entries a name in Name for each entry. Use one short word, such as Child or Item, up to 40 characters. Each entry then gets its own heading: Child 1, Child 2 and so on. Leave it blank and the headings read Entry 1, Entry 2. The same headings show in the “Check your answers” step, the emails and the stored entry.
• Each box with a problem gets its own error message under it. The error summary at the top names the entry too, for example “Child 2: Enter age.” Each line links straight to the box that needs fixing. Too few or too many entries still shows as one message for the whole group.
• Fewest entries and Most entries are numbers from 0 to 100.
  • Leave Fewest at 0 (or blank) to make the group optional. Set it to 1 or more to require that many filled-in entries.
  • A completely blank entry never counts. Visitors can add spare ones and fill them in any order, and the blank ones are ignored when the form is sent.
• Optional fields in an entry can be left blank. Add another will not make the next entry while an existing one is missing a required field, including any part of a required date or address. It says so under the button and moves focus to the box that needs filling in. This applies to every entry in turn: entry 2 has to be complete before entry 3.
• Leave Most at 0 for no limit of your own. The Add another button hides once that many are on the page.

Each container takes an optional Title. A titled group is a real <fieldset>, with a heading at the right level in the page outline. The title and its questions stay together in the “Check your answers” step, the emails and the Pro PDF. Leave the title blank for an invisible wrapper.

Every field's common options #

Confirm a field #

The Must match another field setting on a Text input field blocks submit unless it’s typed exactly the same as another field. Spaces at the end are ignored. It works for any pair, such as a reference number typed twice, not only email.

Pre-fill choices from the query string #

Turn on Pre-select from the query string on a radio, checkbox or dropdown field, and each option gets a small query string match box.

• When the form loads, it looks through the query string (everything after the ?).
• If an option’s match text appears there as a whole word, in any capitals, that option is picked. yes matches ?member=yes but not ?from=yesterday.
• A blank match box looks for the option’s stored value instead.
• The form keeps the query string, so this still works after moving to a later page.
• An answer the visitor picks always wins.

Multi-page & conditional pages #

Add pages with the + tab. Each gets a Continue button automatically, and a Back button whenever there is a previous page. Give every page a title. It becomes the page heading, which screen readers can announce, and it names the step in the progress text.

The title on the browser tab changes with each step, too. It reads the page heading, the step and then the page’s usual title, such as “The fault – Step 1 of 3 – Report a repair – Example Housing Ltd”.

Back shows the previous page as the visitor last saw it. Anything typed on the page they leave is kept, and it’s there again when they return. Nothing on it is checked. Only Continue checks a page and saves its answers. The browser’s own Back and Forward buttons work the same way as the form’s Back for the page being left.

A page can have its own show/hide rule, set on the Setup tab. Choose whether the page is shown only when or is hidden when the condition passes, whichever reads more naturally. A page that ends up hidden is skipped entirely:

• its fields aren’t shown or required
• its email actions don’t send
• the step count adjusts, so a visitor who skips a page sees “Step 2 of 3”, not “of 4”

Base a page’s rule on a question from an earlier page. The rule is checked when the visitor reaches the page, so an answer on that page or a later one isn’t known yet. Going forward the page is skipped, and it only appears if they come back to it. The Setup tab warns you when a page rule uses a question like that.

Show / hide rules on a field or group #

Any field, and any group, can carry the same rule:

1. Press Add show/hide rules… under Where it shows in the field’s panel.
2. Pick is shown only when or is hidden when.
3. Build the condition. Each row has a subject (another answer or a variable), a test (is / is not / contains / greater than / empty…) and a value. When the subject is a multiple-choice field, you pick the value from that field’s own options instead of typing it.

A plain-English line under the rule shows how it reads. A few things to know:

• A field that’s hidden when the form is sent never has its answer saved, emailed or sent to a webhook.
• Tick Clear this field's answer when it is hidden if you also want its box emptied while the visitor is still filling in the form.
• Some rules only test a dropdown, radio button or checkbox answer on the same page, using is, is not, contains or is empty. With those, the field, group or notice appears or goes as soon as the visitor answers. A notice with an answer token in its text waits for the server instead.
• Rules that use typed answers, bigger or smaller numbers, dates, calculations or answers from earlier pages are checked by the server. They take a moment to show or hide. Every rule is checked again when the form is sent.
• A hidden field or group is hidden so nobody can see it or reach it with the keyboard or a screen reader. Anything typed into a field that goes and comes back is kept, unless Clear this field's answer when it is hidden is ticked. A hidden group always clears what’s inside it.
• When an answer makes something appear or go, the form tells screen readers, for example “Now showing: Dog breed.” or “Now showing: Email address. Now hidden: Phone number.” A group is named as well as its questions. A notice is named by its own words, so an error notice that comes or goes is read out once, in that news.
• When a radio button or checkbox option shows another question or group, the option carries a short note for screen readers, such as “Choosing this shows: Email address.” If it shows an alert, the note says “Choosing this shows a note.” and leaves out the alert’s internal label. If it shows both, the note says “Choosing this shows: Phone number, and a note.”
• While that question is on the page, the option is also linked to it in the page’s code (aria-controls), as in GOV.UK’s version. Unlike GOV.UK, the question appears after the whole group, not under the option. Both come from your show/hide rules, so there’s nothing extra to set up.

Relational fields: one dropdown filtered by another #

A dropdown, radio or checkbox can have its choices narrowed by another choice field on the same page.

1. In the dependent field’s settings, set Filter these options by another answer to the controlling field. Its options become groups.
2. In Edit options, each row now has a Group column. Tag each option with the group it belongs to.

On the form, choosing a value in the controlling field shows only the options tagged with that group. Options left as “Any” always show. Until the controlling field is answered, every option shows.

• Chaining works. The filtered field can itself filter a third (Region → Office → Team).
• Changing the first answer clears the second, so a required one has to be picked again against the new list.
• Pairs with Pre-select from the query string: a “report a pothole” link can point at ?category=roads&problem_type=pothole and land on the form with both dropdowns already set and filtered. The bundled Report a problem and Report a fault forms are built this way.

Variables & calculations #

Both a computed variable (on the Setup tab) and a hidden field set to “a calculation” work from other answers. They never appear on the form by themselves. Use them in rules, text and emails. Reach for a variable when you want the value in more than one place. A hidden field’s calculation is a one-off.

Each variable is a titled card. It has a Name and an optional Note for you and your team. Its Key is suggested from the name, and you can change it. Change the key and leave the box, and the builder updates every place in this form that used the old one. It works the same as renaming a Data Name. Write the key in square brackets, like [key], in formulas, text, emails and default values. Formulas also accept {key}. The formula box checks the names as you type. It warns if one names nothing on the form, or if a [ or ] is missing.

What to use one for

The formula box #

Type a calculation as you would on a calculator: multiply and divide happen before add and subtract, and brackets go first. Build it from the buttons below the box, or type it in. The buttons are grouped by what they do: Maths (add, subtract, multiply, divide, brackets), Text (join), Dates (days, weeks, months, working days), Functions, Answers and Other variables. They write answers and variables in square brackets. How the formula works under the box spells out the rules.

[quantity] * [price] + 5
"Ref " & [order_no]
[start_date] + 7 workdays

Functions works out a number from dates or times. Choose what to Work out:

• Days between two dates: pick a From and a To. The lists show your Date questions, your date variables and Today.
• Age in whole years from a date: pick one Date, such as a date of birth. The list shows your Date questions and date variables.
• Hours between two times: pick a From and a To from your Time questions.

Press Insert to add it to the formula. The formula names each answer in square brackets, so you can change it by typing.

Open Try it with sample values under the box to check the formula: type a value for each answer or variable it uses and press Preview. The result is worked out by the same engine the live form uses, so what you see is what a submission would get.

Round the result to picks the decimal places: Whole number, or 1, 2 or 3 decimal places. Show before the number and Show after the number add a unit wherever the value is shown, such as £, cm, kg, % or kg/m². So 22.857 rounded to 1 decimal place with kg/m² after it shows as 22.9 kg/m², and the Money shortcut shows 37.5 as £37.50. Rules compare the rounded number without the unit.

For anything that needs a condition, such as “add 2 only when urgency is high”, use the step list under Advanced. Each step has an operator (set to, add, append text, add working days to the date…), a value, and an optional only when condition.

Operators, conditions

Three worked examples #

A formula does three kinds of work: sums with numbers, joining text together, and moving a date. Here’s one example of each. The date example is further down, in Working with dates. Check any of them with Try it with sample values under the formula box.

Working with dates #

The date maths in a formula, a date default, and the check against another date all read the same shapes: a date field's answer, today, a date like 10-06-2026, or an expression like today + 20 workdays. Write dates day-month-year. Results come back as DD-MM-YYYY, which is what a token such as [date_due] prints. A month-first date like 12/25/2026 is not read as a date.

Tokens #

Tokens are placeholders in square brackets that are replaced with real values. They work in:

• email subjects and bodies
• the submit message and alert text
• formulas and default values
• a field’s own label, hint and error messages, filled in live on the page from what’s been answered so far

For example, a hint of “We'll use [pet_name] throughout this form” reads back the name from an earlier question. A token for an answer not given yet shows nothing.

Built-in tokens and your own field names #

A handful of tokens are always available on every form, with nothing to switch on. Most have a distinctive two-part name, so you can still give a field or variable a plain Data Name like title.

A few names belong to built-in tokens, so a field or variable can’t use them:

• reference, case-reference and page-title
• working-days-note and cancel-link
• all-fields, all_fields, all-data and all_data
• group-inbox

Type one of these as a Data Name and the builder adds a number, such as reference_2, and tells you. That way your answer doesn’t clash with the built-in value. The same happens when you save: a reserved Data Name, or one already used by another question, gets a number on the end. Form check warns you first, and a notice after saving says which names changed. Imported forms are checked the same way. Then update any rule, email or message that used the old name.

Turn on the front-end debugger for a form and these built-in tokens are listed on the published page too, under System variables. They sit alongside your fields and computed variables, so you can see what’s on offer while you check a form works.

The Insert bar above each editor (email body, submit message, alert text, Case view) has a button for:

• every field, showing its Data Name next to its label so you can see which token it adds
• every hidden field, marked “(hidden)”
• every computed variable, shown with its [name]

Pressing one adds an editable line like <if email><dt>Email</dt><dd>[email]</dd></if>. The lines sit in a list (<dl>), which keeps each answer with its question in the page’s code. A line you add outside a list gets its own <dl>. The <if> wrapper takes the whole line out when the answer is blank. Delete the two <if> parts to always show it.

Below the editor, All fields adds an <if>-wrapped line for every field, hidden field and computed variable, all inside one <dl>. It’s the same block a new email action starts with, ready to trim. Each line only shows when its value is set.

Editable lines let you choose which answers go in, and in what order. But a question you add to the form later isn’t added to them by itself. The builder helps you catch it:

• When you add a question, its settings show a reminder that it isn’t in the email yet. Press Add to email (or Add to emails) to add its line, or Not now to leave it. Get the label right first, because the line copies the label when you add it.
• In the email action, a note under the editor names any question that’s missing. Press Add the missing answers to add their lines. Your own text stays as it is.
• Form check adds a note when an email lists its answers one by one and leaves a question out.

This only applies to an email with three or more answer lines, the kind the buttons above add. An email that mentions answers in its sentences is left alone, however many it mentions. An example is “Dear [name], we’ll call on [preferred_date]”. If you’d rather not keep track, use [all-fields]. It always sends every answer, including questions added later.

A small Find in this text box above the editor searches only that editor. Press Enter, or ‹ / ›, to step through the matches. Tick Aa to match capitals.

key is any field's Data Name or a variable name. The blocks can be nested, and any [token] inside is still filled in. This works in email bodies, the submit message and alert text.

In the HTML email and on the check-your-answers page, an answer from a field in Email or Telephone mode becomes a link people can click to email or phone.

Emails #

Use one Email action per recipient group. A common pattern is one email to the visitor and one to your team.

On Settings → Email, the Email appearance section lets you add a block of CSS, a header and a footer. They wrap every email the plugin sends, for example a logo at the top and an address or unsubscribe note at the bottom. Leave the CSS box empty and a plain built-in style is used.

• Links you write in the email template work as normal.
• Many email clients ignore external CSS. For a reliable look, put inline style attributes in the header and footer HTML.

The same screen has a Default from address. Set it to a no-reply address on your own domain, so the WordPress admin address (often a personal inbox) isn’t shown as the sender.

• It’s the “from” on every email the plugin sends. A single email action can use its own From address instead.
• It only changes who the email appears to be from, not who it goes to.
• Replies go to a form’s Group inbox when one is set (on the form’s Setup tab). Set one on any form that uses a no-reply address.
• The address must be one your site is allowed to send as. Your domain’s Sender Policy Framework (SPF) and DomainKeys Identified Mail (DKIM) records decide this. That usually means your own domain.

An email leaves out any question with no answer, so the body only ever shows what was filled in. The check-your-answers page is the opposite: it keeps blank questions so the visitor can see what they skipped.

When a question’s label appears as the label of an answer, its closing question mark is dropped. “What is your name?” shows as “What is your name” above the answer. That happens in emails, on the check-your-answers page, in the entry view and in the PDF. The question on the form itself keeps its question mark.

Add as many email actions as you need. There’s no limit in the plugin, and every one on a page that’s shown sends when the form is sent. Delivery, though, depends on your site’s mail setup, not the plugin. Mail is sent with WordPress’s own wp_mail(). On its own, that uses the web server’s mail program. Its mail often lands in spam, because the sending domain isn’t properly authenticated.

When an email fails. A send that fails is tried 3 times, a few minutes apart. If it still hasn’t gone, it’s stuck, and it joins the Issues tab under Entries. Admins see a red banner on every admin page with the count and an Open Issues button. Staff who can view entries but aren’t admins are asked to tell a site admin instead. The tab’s Sending issues section shows what failed and why. That’s where you try again or remove a send. The banner stays until every stuck send has gone or been removed.

You can also ask internal recipients to add the site's From address to their safe-senders list. That helps their inbox, but it does nothing for the person who filled in the form, and it cannot rescue mail a receiving server rejects outright.

Version history & edit lock #

Every time you save a form, the builder keeps a copy. It keeps the last 30, each with who saved it, when, and the note you gave. The History button on the save bar opens the list. From there you can:

• Restore an earlier version. The current one goes into the history first.
• Delete a version.
• Tick two and Compare them, to see exactly what changed.

While a form is open in the builder, it’s locked to one editor. Anyone else who opens it sees “This form is being edited by …”, with the time and a Take over editing button. Taking over removes the first person from the builder, and any changes they hadn’t saved are lost. Only the person holding the lock can save.

Catch problems as you build: Form check #

Form check, at the bottom of the builder, shows a running count of problems in the form. It checks how the form is built. It isn’t an accessibility audit. Click it for the list, grouped as Errors, Warnings and Notes. It’s about one form as you build it. Problems with the whole site, such as emails that won’t send, go on the Issues tab under Entries instead. The two have different names so you can tell them apart.

• Each finding says where it is, what’s wrong, why it matters and how to fix it, with a Go to field link.
• The badge is red for errors and amber for warnings. It’s a plain blue count when only notes remain. Notes are suggestions, not things you have to fix.
• The same count shows against each form on the Forms list. Clicking it opens that form with this panel already up.

It reads the structure only: labels, legends, choices, keys, error messages, autofill purposes, and a field set narrower than its answer needs.

• One note it raises is a field still on the Data Name the builder gave it (text_1, radio_2). It works, but it reads badly in the stored entry, the spreadsheet export and the emails. The builder’s Find a field panel lists the same fields under Fields never named.
• Another note flags a hidden field that records something about the signed-in user or from the page address. It reminds you to mention it in your privacy notice.
• An email action that lists its answers one by one gets a note when it leaves a question out. This usually means the question was added after the email was written. The note names the missing questions. Open the email and press Add the missing answers. Or use [all-fields] instead of the answer lines. It sends every answer, including questions added later. It only looks at an email with three or more answer lines. An email that mentions answers in its sentences, such as a letter to the visitor, is left alone.
• An Answers summary gets a note when it doesn’t show a question, usually one added or renamed after the summary was made. Open the summary and press Update from the form, or add the line yourself.
• It’s a starting point, not a full audit. Colour contrast, text zoom, reading age, focus visibility and whether the wording makes sense still need a person. The panel lists what it can’t check, and links to the World Wide Web Consortium (W3C) guide to accessible forms (opens in new tab).
• Its errors, warnings and notes never stop you saving. Leftovers from things you removed are different. See below.

Tidy up after you remove something #

When you remove a question, a computed variable, a notice or a page, other parts of the form can still point to it. These are leftovers. They include:

• an answer token such as [name] in an email, a notice or a label
• a show or hide rule or a calculation step that checks the removed question
• a setting on one question that picks another question
• the entry title and the answers summary

Form check lists each leftover under Leftovers from things you removed, and the badge counts them. You can’t save the form until they’re all fixed. Fix each one by hand, or press Remove all leftovers.

The button takes out every leftover apart from those in formulas. A show or hide condition that checks a removed question goes too. So does a calculation step that checks one. Formulas are left for you to fix.

Which questions follow GOV.UK #

This section shows how each kind of question is built, so you know what to check before you publish. Making your forms accessible is your responsibility, as the site owner. The plugin is there to help, and it doesn’t guarantee that any form is accessible.

• Most public bodies must meet the Public Sector Bodies (Websites and Mobile Applications) (No. 2) Accessibility Regulations 2018 and publish an accessibility statement.
• Any organisation that serves the public must make reasonable adjustments under the Equality Act 2010.
• This is guidance, not legal advice.

The questions fall into three groups:

• GOV.UK pattern: the question follows a named GOV.UK Design System component or pattern. Each one links to it.
• Our own design: GOV.UK had nothing for it when we checked in October 2026, or we built our own version. Each row says what it’s built on.
• Has known limits: some people can’t use it, or part of it is run by someone else. Each row says what you can do about it.

Any question can still cause problems if it’s set up badly, whichever group it’s in. A vague label or a missing hint makes a question harder for everyone.

We tested our own test forms with NVDA 2026.2, a free screen reader, in Chrome for Testing on Windows 11 in October 2026. Where this guide quotes what a screen reader says, it’s what NVDA said in those tests. Other screen readers and browsers can say it differently. We haven’t tested with other screen readers, such as JAWS, VoiceOver or TalkBack. These results are for the setup we tested, not your site. Your forms, theme and settings can give different results.

GOV.UK pattern #

These follow a GOV.UK Design System component or pattern. Where ours differs, the row says how. Two differences apply to all of them: required questions are also marked as required in the page’s code, and a group of radio buttons is also marked as a radio group.

Our own design #

When we checked in October 2026, GOV.UK had nothing for these, or we built our own version. Each row says what it’s built on.

Has known limits #

Some people can’t use these, or part of them is run by someone else. Each row says what the limit is and what you can do.

The forms you start with #

There are 13 starter forms in six groups: Customer contact, Complaints & reports, Bookings & appointments, Data & information requests, Council services and Worked examples. Council services holds three forms with council choices, such as council tax and housing. Worked examples holds the two calculation forms.

The setup wizard’s Starter forms step shows them as a tick-list by group. Each form says who it suits. Tick as many or as few as you want, or none. Each form you pick is tagged with its group under the same Form group used on the Forms list, so they show up together there too.

• Each form’s team email starts off going to the site admin address. Change it on each form.
• Each team email lists every answer on its own line. You can edit, move or delete any line. A line with no answer is left out of the email.
• Worked-out values, such as a response deadline, get their own lines too.
• A question you add later isn’t added to the email by itself. The builder offers to add it for you.
• You can edit or delete any of them. Check each form’s wording and settings against how your organisation works before you publish it.
• To bring a deleted one back, use Settings → General → Restore starter content. It lists each form with its status. Tick the ones you want back. Tick one that’s already here to reset it to its built-in version. You confirm first, and a backup is saved before anything changes.

Notes on the request forms #

The starter wording in these forms is an example, written in good faith. It is not legal advice. Check it and set your own before you publish. We wrote it to the best of our knowledge of UK law on 4 October 2026. It may be wrong, or go out of date when the law changes. Check it with whoever advises you.

The regulator

From 30 September 2026 the Information Commission replaces the Information Commissioner as the regulator. It’s still called the ICO, short for the Information Commission’s Office. Its website is ico.org.uk.

Freedom of Information

• The acknowledgement email is written for the Freedom of Information Act 2000. That covers public bodies in England, Wales and Northern Ireland, and UK-wide bodies.
• A Scottish public authority works under the Freedom of Information (Scotland) Act 2002. That Act gives no extra time to weigh up the public interest. Appeals go to the Scottish Information Commissioner. In the form’s Acknowledge to the requester email, replace the two paragraphs that start “If we need to ask” and “If you are unhappy” with this wording:
  Wording for a Scottish public authority

  If we need to ask what information you want, the time starts again when you reply.

  If you are unhappy with our response, you can ask us to review it. If you are still unhappy after our review, you can appeal to the Scottish Information Commissioner at foi.scot.

  Then set Bank holidays for working days on the form’s Setup tab to Scotland.
• Requests for environmental information come under the Environmental Information Regulations 2004, or the Scottish version. The limit is still 20 working days, and it still starts again when someone answers your question about what they want. If a request is both complex and large, you can take up to 40 working days, but you must tell the person, with your reasons, within the first 20. You can’t take extra time for the public interest, so the acknowledgement email’s line about that doesn’t apply. Check what you tell people who make these requests.

Subject Access Requests

• The deadline is one month. If you ask for proof of identity, the month starts when you get it. If you need more detail to find what the person wants, the clock stops from when you ask until they answer.
• If a request is complex, or the person has sent several, you can take up to two more months. Tell them before the first month ends, and say why.
• You must make a reasonable and proportionate search. You don’t need to say this in the acknowledgement.
• Your reply, not the acknowledgement, must tell the person they can complain to you and to the ICO.

Data protection complaints

• Since 19 June 2026, people can complain to you about how you use their personal information. The law says you must make this easy, for example with a form people can fill in online. You must acknowledge each complaint within 30 days, and tell the person the outcome without undue delay.
• People can use the Make a complaint form for these. It has a choice called How we use your personal information.
• The Subject Access Request acknowledgement email says people can complain to you. Add how they can do that, such as a link to your complaints form or an email address.
• People can still go straight to the ICO. The ICO usually asks them to complain to you first.

Complaints to an ombudsman

The Make a complaint form doesn’t name an ombudsman. Which one applies depends on the kind of organisation you are and where you work. Many public bodies must tell people about their ombudsman. That usually goes in your final response, with the time limit for going to the ombudsman. The acknowledgement email doesn’t need it.

• Scotland. Most public bodies follow a model complaints procedure from the Scottish Public Services Ombudsman (SPSO). That includes councils, the NHS, housing associations, colleges and universities. Its first stage gives a response within 5 working days. Its investigation stage gives an acknowledgement within 3 working days and a response within 20 working days. Your final response must tell people they can ask the SPSO to look at their complaint, and give the time limit.
• Wales. Public bodies come under the Public Services Ombudsman for Wales, at ombudsman.wales.
• Northern Ireland. Public bodies come under the Northern Ireland Public Services Ombudsman (NIPSO), at nipso.org.uk.
• England. Councils come under the Local Government and Social Care Ombudsman, at lgo.org.uk. Its code has a shorter first stage: acknowledge within 5 working days and respond within 10. Housing associations and council landlords come under the Housing Ombudsman. The NHS and UK government departments come under the Parliamentary and Health Service Ombudsman.
• Personal information. Complaints about how you use personal information can go to the ICO, in every part of the UK.
• Businesses and charities. Your sector may have its own ombudsman or regulator. Check which one applies to you.

The form’s Acknowledge by and Full response by variables are examples, set to 3 and 20 working days. Change them on the form’s Setup tab to match your own procedure.

The Pro add-on #

HolmesPortfolio Forms Pro is a paid add-on for when your forms need to do more. It installs next to the free plugin and adds to it. Pro is coming soon, in two plans.

With the Pro plan you can:

• take payments by Stripe payment link, PayPal button or bank transfer
• collect signatures
• send a PDF of the answers
• let people save a long form and come back to it later
• add repeatable groups, so people can add another child, vehicle or item
• offer booking calendars for appointments, rooms, tables and holiday stays
• run polls
• ask map questions, so people can show you exactly where something is
• track each entry with statuses and internal notes, and email the person who sent the form
• send each entry to your other systems with webhooks, and add people to Mailchimp or Brevo
• see where people give up, with form analytics

The Casework plan has everything in Pro, plus a case system for your teams:

• staff pick up cases and see them through to the end
• teams can hand cases to each other
• response time targets come with reminders when a case runs late
• customers can reply through a one-time link, or sign in to see their own cases
• a map shows where reports were made
• there’s no fee per member of staff

Keep an eye on holmesportfolio.co.uk for news.