How to write form instructions

Good form instructions are short, specific and placed where the person is looking at the moment they need them. Anything that decides whether an answer will be accepted, like a character limit, a date format or a unit, goes in the label. A one line hint that helps most people goes directly under the field. Rules that govern a whole section go in a short paragraph above that section. What to have ready and how long it takes goes before the first question. Placeholder text inside the box carries nothing important, because it disappears the moment someone starts typing.

The rest of this article is about the details: where help text is actually read, what each place is good for, how long an instruction should be, and how a missed instruction turns into an error message.

Where help text is actually read

People read labels. Everything else is skimmed, and some of it is skipped entirely.

For screen reader users the gap is wider. W3C’s forms tutorial notes that screen readers often switch to a forms mode inside a form, where they usually read only the form elements themselves, such as inputs, labels and legends. WebAIM makes the same point from the keyboard: labels are announced as each field receives focus, but other text between the controls is usually skipped. W3C adds that instructions placed outside labels allow more flexible design but can be missed.

That gives a simple order of reliability. The label is read by everyone. A hint directly under the field is read by most. A paragraph above a section is read by people who are reading carefully. And the start of the form is the one place W3C specifically recommends for overall instructions: how required fields are marked, expected formats and time limits.

The community grant application form from Otway Shire Council uses that order well. Its welcome screen says four steps, about 25 minutes, in one sitting, and tells applicants to read the guidelines first. The assessment weights sit in a paragraph above the questions they score. The word limit for each written answer sits in the label itself, such as “Project summary (100 words)”.

Label, hint, placeholder or paragraph

Each place has one job.

The label names the question and carries any rule that decides whether the answer is accepted. The abstract submission form labels its sections “Background, up to 700 characters” and “Results, up to 900 characters”, so nobody has to hunt for the limit. When a limit is set on a field, the published form does not display a counter or stop the typing, so the label is the only place the respondent learns it before sending.

The hint helps most people with one short sentence. GOV.UK suggests hint text for things like how the information will be used or where to find it, kept to a single short sentence with no links. On a classic form the sub-label box does this job, printing a short line under short text, long text, number, dropdown, date, time, radio, checkbox, full name and address fields.

The placeholder is for nothing essential. GOV.UK lists three problems: it vanishes when someone starts typing, not all screen readers read it out, and its default browser styling often fails WCAG 2.2 success criterion 1.4.3 on contrast. Nielsen Norman Group adds that people cannot check their answers once it is gone and sometimes mistake it for text already filled in. The grant form’s placeholders name the criterion each question is scored against, but that is safe only because the same weights are printed in the paragraph above.

The paragraph holds a rule that applies to several questions, or a reason worth reading. The expense claim form puts its sixty day rule above the line items table and its definition of a receipt above the upload, so each rule appears at the moment it applies. On a classic form this matters more than it looks: the description box on most fields is not shown to the respondent, so a paragraph component is where longer help has to go.

The exception is uploads. File upload and photo descriptions are shown on a classic form, which is why the expense claim explains how to photograph a receipt right there: flat on a dark surface with the whole docket in frame.

Length: one idea per instruction

W3C’s understanding document for success criterion 3.3.2 puts it plainly: too much information or instruction can be just as harmful as too little. The goal is enough to finish the task without confusion.

Two rules keep instructions short. First, one idea per instruction. “Enter the amount you paid and attach the receipt” is two instructions pretending to be one, the same fault that makes a double barrelled question impossible to answer. Second, rule first and reason second, and include the reason only when it changes what people do. The background check consent form explains above its address table that a police check runs against every address from the last five years and that a gap is the most common reason one stalls. That reason earns its sentence, because it gets people to fill in the gap.

GOV.UK sets the hint ceiling at one short, simple sentence, since a screen reader reads the whole hint every time the field is reached. Anything longer is a paragraph, and anything longer than a paragraph is probably a separate page.

Good and bad instructions, side by side

Weak instructions are vague about the thing that goes wrong. Strong ones name it.

“Upload your documents” tells nobody what counts. The expense form’s upload says up to ten files, PDF or photo, 10 MB each, and how to photograph a receipt so the total is not cropped.

“Keep it brief” is not a limit. “Up to 700 characters” is a limit, and it matches how the builder counts: minimum and maximum length on a text field are measured in characters, not words. If you print a word count in the label, as the grant form does, set the character limit generously enough to cover it.

“Provide details” invites a paragraph. “Name, relationship and phone” gets three answers in the right order.

“Please read carefully before continuing” adds nothing. The rule itself, printed where it applies, is what people read.

Errors are instructions that arrived late

Every error message is an instruction the person did not see in time. The best fix is usually an earlier instruction, not a better error.

On a published classic form, a missing required field is named when the person presses Submit, or Next on a paginated form, with a short message built from the label: “Project title is required”. A conversational form says “Please answer:” followed by the label. There is no separate error text to write, so the label is the error message. A label that reads badly in that sentence, such as a long question ending in a question mark, will read badly in the error too.

Length limits and number ranges are checked when the whole form is sent, and a breach comes back as a failed submission rather than a note beside the field. That is the strongest reason to put every limit in the label. The companion article on form error messages covers the wording of the messages themselves.

Where each instruction goes

The table at the end of this article lists thirteen common situations, from time needed to consent wording, and the place on a published form where each instruction belongs. Most of the rows follow from two facts covered above: labels are read by everyone, and a classic form shows the description box only on file upload and photo fields.

Common mistakes

Help in the placeholder. It disappears, fails contrast by default and is not reliably read aloud.

Help in a classic field’s description box. It is not shown on the published form, except on uploads.

A wall of instructions at the top. People start answering and never scroll back. Put each rule beside the question it governs.

Limits nobody can see. A maximum length set in the builder but not written in the label only shows up as a failed submission.

Instructions that repeat the label. “Enter your email address” under a field labelled Email address costs a line and says nothing.

Build it

Every place described here exists in the builder. Of the 41 component types, the ones that carry instructions are the label and sub-label on each field, the paragraph, heading and subheading components for text between questions, the description box on file upload and photo fields, and the welcome and thank-you screens. A classic form shows the description box only on uploads; a conversational form shows it under every question, which suits step by step help.

The form field types page lists every component and which builder offers it, and the form builder components guide covers the settings each one has, including sub-labels, placeholders and the paragraph block. For an application form where the instructions carry legal weight, the article on job application form questions shows where a privacy statement has to sit on a classic form.