Fixing Form Markup Errors

What this guide covers, and what it does not

There are two quite different questions you can ask about a form. One is whether a person can understand and complete it: are the labels clear, are errors explained, can it be used by keyboard and screen reader? That is covered in fixing form labels. The other is whether the markup itself is valid HTML, which is what the HTML Checker reports and what this guide fixes.

The two overlap, because invalid markup often breaks accessibility. A label pointing at an id that does not exist, for instance, is both a validation error and an unlabelled field. But many form errors have nothing to do with labels: they are attributes that do not belong on a given input type, values the browser cannot interpret, or structure the HTML parser rewrites before your page even loads.

A note on the word "validation": HTML also has built-in constraint validation, the browser's own checking of required, pattern, min and type="email" fields before submission. Invalid markup is one of the main reasons that checking behaves oddly, so fixing the markup is also the first step when built-in form checking seems broken.

The validator messages for forms, and what each means

The exact wording varies slightly between validator versions, but the key phrase, such as "not allowed on element input" or "must refer to", stays the same and is what you should search for.

Structural errors: nested forms and misplaced controls

Fix these first, because the HTML parser changes the document when it meets them, and the other errors may be side effects.

A form inside a form

Forms cannot be nested. When the parser sees a second <form> start tag while one is open, it ignores it, and the inner form's action and method vanish. Its fields become part of the outer form. This usually happens when a page builder puts a newsletter or search widget inside a section that is already wrapped in a form, or when a checkout theme wraps the whole page in one form.

Move the inner form outside the outer one. If the controls must sit visually inside the outer form, place the second form elsewhere in the markup and link its controls to it with the form attribute:

<form id="checkout" action="/checkout" method="post">
  <label for="email">Email</label>
  <input type="email" id="email" name="email" autocomplete="email" required>

  <label for="voucher">Voucher code</label>
  <input type="text" id="voucher" name="code" form="voucher-form">
  <button type="submit" form="voucher-form">Apply</button>

  <button type="submit">Place order</button>
</form>

<form id="voucher-form" action="/voucher" method="post"></form>

Buttons inside links, and links inside buttons

Interactive elements cannot contain other interactive elements. A "Shop now" button wrapped in a link is really a navigation link, so use an <a> styled as a button. Something that submits, opens or toggles is a <button>. Choose one; never nest them.

Buttons without an explicit type

Inside a form, a <button> with no type is a submit button. A "show password" or "add another item" button without type="button" will submit the form when pressed. The validator does not always flag a missing type, but the HTML Checker's form checks do, and it is worth setting on every button: type="submit", type="button" or, rarely, type="reset".

Void elements and closing tags

input is a void element: it has no content and no closing tag. Delete any </input>. By contrast textarea, select and button must be closed; a missing </textarea> swallows the rest of the page into the text box.

Attributes that each input type allows

Most attribute errors come from treating every input as a text box. Each type accepts only the attributes that make sense for it, and anything else is ignored by the browser, which means the behaviour you expected never happens.

Limiting digits in a number field

Since maxlength does nothing on type="number", use min and max for a numeric range. For codes that are made of digits but are not quantities, such as a card security code, a one-time passcode or a phone extension, use a text input with inputmode="numeric", which shows a numeric keypad on phones, plus pattern and maxlength:

<label for="otp">6-digit code</label>
<input type="text" id="otp" name="otp" inputmode="numeric"
       pattern="[0-9]{6}" maxlength="6" autocomplete="one-time-code">

Phone numbers belong in type="tel", never type="number": a number field drops leading zeros in some cases, rejects spaces and plus signs, and adds spinner arrows.

Types that do not exist

type="datetime" was removed from HTML; use datetime-local for a date and time without a time zone. type="phone" and type="postcode" were never valid; use tel and text with a suitable autocomplete value.

Autocomplete, inputmode and boolean attributes

Valid autocomplete values

autocomplete takes a defined list of tokens. Common ones are name, given-name, family-name, email, tel, organization, street-address, address-line1, address-level2 (town or city), postal-code, country-name, username, current-password, new-password, one-time-code and the card tokens such as cc-number. You can prefix a section name and shipping or billing, as in autocomplete="shipping postal-code". Plain on and off are also valid.

Invented values such as nope, false, disabled or new-field are invalid. They became popular as tricks to stop autofill, and browsers handle them inconsistently. If a field genuinely should not be filled from saved data, off is the valid way to say so; for a password-change form, new-password tells password managers to suggest a new password rather than fill the old one.

inputmode values

inputmode only accepts none, text, decimal, numeric, tel, search, email and url. Values such as number or digits are invalid and ignored.

Boolean attributes

required, disabled, checked, selected, readonly, multiple, autofocus and novalidate are boolean: their presence means true. required="false" still makes the field required, and checked="false" still ticks the box. Valid forms are the bare attribute or the attribute name as its value, required="required". To make something not required, leave the attribute out. Template code that prints disabled="{{ is_disabled }}" is a frequent source of this bug.

Required selects need an empty first option

<label for="size">Size</label>
<select id="size" name="size" required>
  <option value="">Choose a size</option>
  <option value="s">Small</option>
  <option value="m">Medium</option>
</select>

Without the empty-value first option, the select always has a value, so required can never fail and visitors who never touch the field submit whatever the first option happens to be.

The fix, step by step

Where these errors come from on common platforms

• Form plugins and builders. WordPress form plugins, Shopify apps and hosted form embeds generate the markup for you. Most errors here come from settings rather than code: a field type chosen as "number" for a phone number, or a custom autocomplete value typed into an advanced field. Check the field settings before touching templates.
• Theme templates. Search, newsletter, login and product forms usually live in theme files. Nested forms often appear when a theme's product form and an app's widget are both inserted into the same section.
• Component libraries. A shared input component that accepts every attribute and passes it straight through will happily print maxlength on a number input. Filter props by type inside the component.
• Checkout pages on hosted platforms. Checkout markup on hosted e-commerce platforms is often not editable. If errors appear there, record them and move on to the forms you control.

The platform guides for WordPress and Shopify explain how to find and override the template that prints a form on each platform.