How it finds your fields

If your fields have proper labels, the form guide finds them.

Which fields get an icon#

• <input>, <select> and <textarea> fields. Inputs of type hidden, submit, button, reset, image and file are left out.
• A group of radio buttons (radio buttons sharing a name) gets one icon for the whole group.
• If a slider (type="range") shares its label with a text box in the same row, only the text box gets an icon.
• The field must have a label. If the guide can't find one, the field gets no icon.

The icon goes inside the field's <label> when there is one. Otherwise it goes just after the field. Fields added to the page later (for example, the next step of a multi-step form) get icons automatically. A field never gets two icons.

How it finds the label#

It tries these in order and uses the first one it finds:

1. data-formguide-field-label="..." on the field.
2. For radio groups: a label or short text near the group, then the <fieldset>'s <legend>, then the heading above it.
3. A <label for="field-id">.
4. A <label> wrapped around the field.
5. aria-label on the field.
6. aria-labelledby on the field.
7. A nearby <label> or element with class label, up to three levels up.
8. A heading right above the field.
9. Short text (<p> or <span>) before the field in its row.
10. Any heading above the field, inside the form.
11. The field's placeholder.
12. The field's name, made readable (date_of_birth becomes "date of birth").

Attributes you can add to your fields#

A date of birth split into three boxes, with one icon for the whole question:

<span class="label">Date of birth</span>
<input name="dob_day"   aria-label="Day"   data-formguide-field-label="Date of birth">
<input name="dob_month" aria-label="Month" data-formguide="skip">
<input name="dob_year"  aria-label="Year"  data-formguide="skip">

Help text#

If a field has help text, the agent is told about it. The guide finds it here:

• the element named by the field's aria-describedby, or
• a <small>, or an element with class help-text or form-text, right after the field.

<label for="occupation">Your job</label>
<input id="occupation" name="occupation" aria-describedby="occupation-help">
<p id="occupation-help">As you'd describe it to a friend.</p>

Questions made of buttons#

Some forms show a question as a row of buttons (Yes/No, cards to choose from, tick lists) with no input behind them. Mark the element around the buttons with data-formguide-field and a short key:

<div data-formguide-field="cover_reason" data-formguide-field-label="What is the cover for?">
  <button type="button">Mortgage</button>
  <button type="button">Family</button>
  <button type="button">Income</button>
</div>

The question comes from data-formguide-field-label. Without it, the guide uses a <label> or .label element inside the group, or else the nearest heading above the group. A group with none of these gets no icon.

<div data-formguide-field="cover_reason">
  <div class="label">What is the cover for?</div>
  <button type="button">Mortgage</button>
  <button type="button">Family</button>
</div>

The icon goes in that <label> or .label element, else in a heading just above the group, else at the start of the group.

The text on the buttons is sent to the agent as the choices. If the agent fills in the answer, it clicks the matching buttons, so your own click handlers record the answer as usual.

Choosing which fields get help#

There are four ways to leave fields out, and you can combine them:

1. data-formguide="skip" on the field itself.
2. exclude (or data-exclude): a CSS selector. Matching fields are left out.
3. fieldRules (or data-field-rules): a list of rules. See below.
4. With attach(), only fields inside container are included.

Field rules#

fieldRules: {
  mode: 'blocklist',  // or 'allowlist'
  entries: [
    { type: 'field_name',   pattern: 'email' },     // matches name="email" or id="email"
    { type: 'css_selector', pattern: '.no-help' }   // matches any CSS selector
  ]
}

An empty entries list does nothing.