Building and editing

Learn how to start building your first form.

Your form's name and URL
Starting pages
Previewing your pages
Adding pages
Moving pages
Editing pages
Deleting pages
Choosing the type of page
Choosing which question format to use
Presenting users with a long list of options
Asking users to submit a file
Making a question optional
Validating user answers
Formatting content with markdown

Your form's name and URL

When you create a new form, you need to give it a name.

This name is:

• what your form will be listed as in the MoJ Forms editor
• the title that will appear on your form to users
• used in your form's URL - for example, a name of Apply for a dog licence will produce a form URL of https://apply-for-a-dog-licence.form.service.gov.uk

The title can contain lowercase and uppercase letters, hyphens and apostrophes. No other special characters are allowed. The name cannot start with a number but you could write it out - for example, 'two' instead of '2'.

We are making some changes in this area and it is not currently possible to change your form's name in the editor. Contact us whenever you want to change the name.

The starting pages

When you create a new form, you are taken to your form's 'pages flow' or flow view. This shows how all the pages link together and is where you will build and edit your form. Most actions, such as adding and deleting pages, editing pages and creating branching, are launched from the flow view.

You are given some default pages to help you structure your form:

• start page
• check answers page
• confirmation page

The start page is your form's home page and cannot be deleted. To find out more about what should go on your start page, read the Design System guidance.

All your form's question pages should come after the start page and before the check answers page.

Check answers and confirmation pages

For your form to successfully submit the user data it collects, it must have a check answers page and a confirmation page. In addition:

• a form can only have one check answers page and one confirmation page
• a form cannot be published to Live without both these pages

Previewing your form

The flow view includes a 'Preview' button in the top right-hand corner.

Previewing your form is a quick way to check how the form will look and work without needing to publish it. Most things in preview will behave identically to the final published form but there are a few limitations:

• a form in preview mode will not save any information entered into it or send any emails
• preview links cannot be shared and will work only for you

You can also preview individual pages without needing to go through the whole form page-by-page. To do this, hover over the page thumbnail to reveal the page menu (...) and select 'Preview page'.

Adding pages

You can add pages to your form using the connection menu (+) that sits on each arrow.

This menu enables you to select a new page from the range of available templates. See Choosing the type of page for details.

When you add a new page, you need to give it a name. This will be the page's URL slug so should be in lower case with no spaces or special characters. Separate words with hyphens. For example, in the following URL, the page name is 'your-details':

https://apply-for-a-dog-licence.form.service.gov.uk/your-details

Some names are reserved for global pages and you won't be able to use them:

• metrics
• ping
• health
• accessibility
• cookies
• privacy
• maintenance
• reserved
• dashboard
• admin

It is not currently possible to change the name of a page once you have created it.

Moving pages

To move a page:

• hover over the page thumbnail to reveal the page menu (3 dots in a circle) and select 'move page'
• in the modal that appears, select another page from the drop-down list - your page will be moved to directly after this selected page

You can move most pages in this way, including pages that have become unconnected. Branching points, check answers and confirmation pages can't be moved. In these cases, the move page option is not shown in the menu.

Undoing a page move

When you move a page, an undo button will appear alongside the preview button. Clicking this button will reverse the page move.

If you undo the page move, a redo button will appear allowing you to repeat the original page move.

If you perform any other action on your form, the button will disappear and you will no longer be able to undo or redo the page move.

Editing pages

You can open a page to edit in 2 ways:

• clicking directly on the page thumbnail
• hovering over the page thumbnail to reveal the page menu (3 dots in a circle) and selecting 'edit page'

Most text on a page can be edited. Just click on the text you want to change and start typing.

Some fields are required, like the page title, and others are optional. If a text area says it is optional, you don't have to delete it. The default text that appears in square brackets will be hidden in preview mode and when published.

Most text areas are set to a specific format, such as headings and hints. Text in content areas can be formatted using markdown.

Some text areas cannot be edited at the moment, including the buttons.

Deleting pages

You can delete a page from the form flow view by hovering over the page thumbnail to reveal the page menu (3 dots in a circle) and selecting 'delete page'. This cannot be undone.

If you want to remove a page from your form without deleting it, you can move it to the unconnected pages section using the 'change next page' option.

Choosing the type of page

When adding pages, you can choose from the following templates:

Table: MoJ Forms page templates

Type of page	What it's for
Single question page	Allows only one question per page. All question types are available.
Multiple question page	Allows any number of questions on a page. Most question types are available.
Content page	Use to provide users with information without asking any questions, such as advice about the application process or the task they are trying to accomplish. Allows text and markdown formatting but no questions.
Exit page	Use to tell users they do not need to continue with the form, for example if they are ineligible for your service. Allows text and markdown formatting but no questions. There is no continue button. Inserting an exit page will break the flow to any following pages and move them to the unconnected pages section.
Check answers page	A page that allows users to check their answers before they submit them. You will only see this option if you deleted your starting check answers page. A form can have only one check answers page.
Confirmation page	The final page of a form which lets the user know they have finished. You will only see this option if you deleted your starting confirmation page. A form can have only one confirmation page.

Single question or multiple question page?

GOV.UK forms and services are built around the principle of one thing per page. In general, this is the easiest approach for users and it helps you get the highest quality responses. When you plan out your form, start with one question per page using single question page templates and only combine them on multiple question pages when it makes sense to do so. For example, you might decide to ask for a user's contact details on one page which could include an email address and telephone number.

Questions cannot currently be re-ordered on multiple question pages so it will save you time to plan out the page and make sure you are happy with the order of questions in advance.

The autocomplete and file upload question types are only available as single question pages.

Choosing which question format to use

MoJ Forms has a wide range of question types. Picking the right format for your question will help ensure you get the highest quality responses from your users.

Text

Use the text question type when you want the user to enter a small amount of text such as a name or phone number. If the user might want to enter more than one line of text, use the textarea question type instead.

This question type allows you to set a minimum and maximum number of characters or words for answers.

Textarea

Use the textarea question type when the user might want to enter more than one line of text. Be clear and specific with your question and hint text so the user knows what is expected of them.

Don't use a textarea if there is a more structured way to collect the desired information using several questions.

This question type allows you to set a minimum and maximum number of characters or words for answers. With a maximum answer length, it shows a counter as the user approaches and passes the limit.

Email address

Use the email address question type to ask users for an email address. You must be clear why you are asking for it and how it will be used. (This should also be reflected in your privacy notice.) You must use this question type if you plan on sending users a confirmation email.

This question type automatically checks that the answer looks like an email address (e.g. it contains an @ symbol).

Number

Use the number question type to ask users for a number.

This question type automatically checks that the answer contains only numbers and decimal points. Letters, spaces and other characters are not permitted. For this reason, don't use this question type to ask for telephone numbers as users might use brackets, spaces and so on. Use a text question for telephone numbers instead.

This question type allows you to set a minimum and maximum value for answers. For example, only numbers up to 100 or numbers above 500.

Date

Use the date question type to ask users for a date that they are likely to know, such as their date of birth. If the user is unlikely to know the exact date there are better options, such as radio buttons offering users a choice or a text question allowing them to write in an answer.

This question type automatically checks that the days and months are valid possibilities. For example, a day can be up to 31 when the month is 1 but only 30 when the month is 9.

This question type allows you to set an earliest date and a latest date for answers. For example, only dates before 1 January 2000 or dates after 31 December 2001.

Radio buttons

Use the radio buttons question type to ask a user to select a single answer from a list. If the user can select multiple options, use checkboxes instead.

If there are a lot of options, think about how they are ordered so a user can skim them easily and find the option that best fits.

If you want to offer an 'other' option, place this last. If you want the user to describe this other option, you can either:

• have an optional text or text area question beneath the radio buttons (using a multiple question page)
• use branching to take those users to another page where you can ask more about the other option

Checkboxes

Use the checkboxes question type to allow users to select multiple answers from a list. If the user must select only a single option, use radio buttons instead.

If there are a lot of options, think about how they are ordered so a user can skim them easily and find the option that best fits.

If you want to offer an 'other' option, place this last. If you want the user to describe this other option, you can either:

• have an optional text or text area question beneath the radio buttons (using a multiple question page)
• use branching to take those users to another page where you can ask more about the other option

Autocomplete

Use the autocomplete question type to help users select a single answer from a long list of options. The user can scroll through the list to select their answer or start typing to filter the options.

See the section on presenting users with a long list of options to learn more about how this question type works.

File upload

Use the file upload question type to ask a user to attach a file to their form. A user can attach one file per page up to 7MB in size.

See the section on asking users to submit a file to learn more about how this question type works.

Presenting users with a long list of options

The autocomplete question type allows you to specify a large range of options for the user to choose from, such as a list of courts or locations. It looks like a text field with a black triangle, indicating a dropdown. When the user clicks into it the list of options appears. The user can scroll through the list to select their answer or start typing to filter the options. The form will only accept answers from the options specified.

This format is best when there are a lot of options to choose from. Smaller numbers of options are better presented using radio buttons.

Formatting your autocomplete options

Your autocomplete options must be uploaded to MoJ Forms in a comma-separated values (CSV) file. This is a plain text format that many applications use for exporting data.

The easiest way to create your autocomplete options is with a spreadsheet such as Microsoft Excel or Google Sheets. List your options in a column with a heading of 'Text', like this:

Text
Glasgow
London Gatwick
London Heathrow

You can also include a second column of information with a heading of 'Value'. For example, you might want to associate a code or number with each option. This won't be shown in the question but will be shown instead of the text in the PDF and CSV submitted at the end. (If you don't provide values, the PDF and CSV will contain the text.) For example:

Text	Value
Glasgow	GLA
London Gatwick	LGW
London Heathrow	LHR

When entering your options, ensure that:

• you have either one or 2 columns of information
• the headings are exactly as shown here
• the options are ordered alphabetically
• there are no blank cells

Remember to save your options as CSV when you are ready to upload them to your form. (If your application gives you a choice of CSV types, use the standard “Comma-separated Values (.csv)” option.) There is a maximum file size of 1Mb.

Uploading your autocomplete options

To upload your options, open your autocomplete page in edit mode. Click in the question title to show the component menu (...) and select 'Autocomplete options'.

The page includes a blue warning message to indicate whether any options have been uploaded. After uploading, you won't be able to see your options on the page. You will need to save your changes and test them either in preview mode or after publishing to Test.

It's not currently possible to edit your options once they have been uploaded. To change the options, you will need to upload a new file.

Asking users to submit a file

The file upload question type allows you to ask users to attach a file to their form. It supports the following file formats up to 7MB in size:

• portable document format (.pdf)
• comma-separated values (.csv)
• images (.jpg, .jpeg, .png)
• MS Excel (.xls, xlsx)
• MS Word (.doc, .docx)
• Open Office (.odt, .ods)
• plain text (.txt)
• rich text (.rtf)

The component allows users to upload only one file per page. To collect additional files, you will need to add extra file upload pages.

MoJ Forms may alter files names during the upload process to:

• remove any unsupported special characters such as ? and *
• remove any part of a file name that comes before a \ - for example, report\version1.doc would be renamed to version1.doc
• differentiate any identically named files with a number - for example, instead of several documents all named document.xls, you would receive document.xls, document-(1).xls, document-(2).xls and so on

Making a question optional

When a question is required, the form will check that the user has provided an answer before moving to the next page. If they haven't, it will show an error message and prompt the user to complete the question.

All questions are required by default but you can switch this setting off to make a question optional. This can be done with both single question pages and individual questions on multi-question pages.

To make a question optional, first click in the question title as if you are going to edit it. This highlights the component settings button (3 dots in a circle). Clicking on the button will open the menu.

Click on the 'Required' setting to open the options, where you can set it to either 'yes' (required) or 'no'.

MoJ Forms automatically adds '(optional)' onto the end of the title of any question that isn't required.

Validating user answers

You can set validation criteria for a range of question types, allowing you to specify things like the length or limits of an answer. When validation is present, the form will check the user's answers before moving to the next page and show an appropriate error if required.

The full range of options available are shown in this table:

Table: validation options

Validation	Available with	What it does
Minimum answer length	Text Text area	Sets the minimum number of characters (or words with text area) that will be accepted
Maximum answer length	Text Text area	Sets the maximum number of characters (or words with text area) that will be accepted
Minimum answer value	Number	Sets the lowest number that will be accepted
Maximum answer value	Number	Sets the highest number that will be accepted
Earliest date	Date	Sets the earliest date that will be accepted
Latest date	Date	Sets the latest data that will be accepted

To set validation, click in the question title to highlight the component settings button (3 dots in a circle) and click to open the menu. Validation options are listed in the menu.

Formatting content with markdown

In most cases, you won't have to worry about formatting. The page templates include fields for headings, labels and hint text and all you have to do is add your own words.

Content areas allow you to use markdown to add your own formatting. These are on every content page and can be added to some other page templates as required.

Markdown is a way of adding formatting to plain text using basic symbols and patterns. With markdown, you can add headings, links, lists, tables and more. For example, to create a bulleted list, you start each item with an asterisk (*). Here is a selection of the most common markdown elements:

Table: markdown formatting

Formatting	Markdown	Example
Headings	Put 2, 3 or 4 hashtags at the beginning of your header, depending on the level of heading you need.	## Level 2 heading ### Level 3 heading #### Level 4 heading
Bold	Put the words you want to make bold inside double asterisks.	make **these words** bold
Italic	Put the words you want in italics inside single asterisks.	make *these words* italic
Bullets	Put an asterisk (or a hyphen) at the start of each item in your list and leave blank lines at the beginning and end of the list.	Bulleted lists look like this: * list item 1 * list item 2 * list item 3
Numbering	Put a number with a full stop and space at the start of each item and leave blank lines at the beginning and end of the list.	Numbered lists look like this: 1. list item 1 2. list item 2 3. list item 3
Web links	Put the link text in square brackets followed immediately by the link url in round brackets.	[link to GOV.UK](https://www.gov.uk/)
Email links	Put 'less than' and 'greater than' signs around the email address.	<email@address.com>
Tables	Use dividers (or 'pipes') to split your content into columns and start each row on a new line. Make sure each row has the same number of columns. Put hyphens in the second row to make the first row a header row. Leave blank lines at the beginning and end of the table.	2 columns: | Header 1 | Header 2 | | -------- | -------- | | Cell | Cell | | Cell | Cell | 3 columns: | Header 1 | Header 2 | Header 3 | | -------- | -------- | -------- | | Cell | Cell | Cell | | Cell | Cell | Cell |
Call to action	Put $CTA on the lines before and after the text you want in the box	$CTA This markdown creates a tinted box. You can use it to highlight important links and information. $CTA

For the full range of markdown options available, see this markdown guide.