Skip to content

Forms & Inputs ​

Forms are where admin panels live or die. Every pattern here is built around one idea: the form must work before JavaScript arrives, and get better after it.


Field anatomy ​

html
<div class="av-field">
  <label class="av-field__label" for="email">
    Email address
    <span class="av-field__required" aria-hidden="true">*</span>
  </label>

  <div class="av-input-group">
    <span class="av-input-group__text">
      <svg class="av-icon" aria-hidden="true" viewBox="0 0 24 24"><rect x="3" y="5" width="18" height="14" rx="2"/><path d="M3 7l9 6 9-6"/></svg>
    </span>
    <input class="av-input"
           type="email"
           id="email"
           name="email"
           required
           autocomplete="email"
           inputmode="email"
           aria-describedby="email-help email-error"
           placeholder="name@company.com">
  </div>

  <p class="av-field__hint" id="email-help">We will only use this for account notifications.</p>
  <p class="av-field__error" id="email-error"></p>
</div>
ElementRequirement
<label for>Always. Never placeholder as a label.
requiredNative attribute, not just a red asterisk
autocompleteCorrect token — see the table below
inputmodeCorrect mobile keyboard
aria-describedbyLinks help text and error text to the input
.av-field__errorPresent in the DOM before validation, filled in on error

Why placeholder is not a label ​

  • It disappears when the user types, so they lose the context
  • Its contrast is intentionally low, which fails WCAG for most implementations
  • Screen readers treat it inconsistently
  • Autofill overwrites it and the field becomes unlabelled
  • Users with cognitive disabilities cannot re-check what the field wants

Use placeholder for format examples only: name@company.com, +353 1 234 5678.


Autocomplete tokens ​

Getting these right is free UX. Browsers and password managers fill forms correctly, which measurably reduces abandonment and errors.

Fieldautocompleteinputmodetype
Emailemailemailemail
Usernameusername—text
Current passwordcurrent-password—password
New passwordnew-password—password
One-time codeone-time-codenumerictext
First namegiven-name—text
Last namefamily-name—text
Full namename—text
Organisationorganization—text
Streetstreet-address—text
Cityaddress-level2—text
County / stateaddress-level1—text
Postcodepostal-code—text
Countrycountry-name—text
Phonetelteltel
Card numbercc-numbernumerictext
Card expirycc-expnumerictext
Card CVCcc-cscnumerictext
Searchoffsearchsearch

Important — type="number" is wrong for phone numbers, card numbers, postcodes, and IDs. It adds spinners, breaks leading zeros, and lets the mouse wheel change the value. Use type="text" inputmode="numeric" pattern="[0-9]*".


Validation ​

Native constraint validation first, enhanced with better messaging.

html
<form data-av-validate novalidate>
  <div class="av-field">
    <label class="av-field__label" for="pw">Password</label>
    <input class="av-input" type="password" id="pw" name="password"
           required minlength="12"
           autocomplete="new-password"
           aria-describedby="pw-help pw-error">
    <p class="av-field__hint" id="pw-help">At least 12 characters.</p>
    <p class="av-field__error" id="pw-error"></p>
  </div>

  <button class="av-btn av-btn--primary" type="submit">Create account</button>
</form>

novalidate disables the browser's own bubbles (which are unstyleable and disappear too quickly) while keeping the Constraint Validation API available.

What data-av-validate does:

  • Sets novalidate on the form, then validates every field on submit. Each invalid field gets is-invalid, aria-invalid="true" and a message in its .av-field__error; valid ones are cleared.
  • Messages: data-av-error on a field wins; otherwise a plain-English message per validity state (required, email, URL, min/max length, min/max value, step, and title for pattern).
  • Error summary: if the form contains [data-av-form-errors], it lists each invalid field as a link to it, its [data-av-form-errors-title] says how many problems there are, and it takes focus. Without one, focus moves to the first invalid field.
  • Announces "N fields need attention." assertively, and emits av:form:invalid with { form, errors } — or av:form:valid with { form } when the submit goes through.
  • On reset, clears every error and hides the summary.

Validation timing ​

EventBehaviourWhy
On blurValidate the fieldDo not shout at someone mid-typing
On input, if already invalidRe-validateGive immediate positive feedback once they are fixing it
On submitValidate everything, focus the first error

Validating on every keystroke from the start is the single most annoying form pattern in existence.

Server errors ​

html
<div class="av-field">
  <label class="av-field__label" for="slug">URL slug</label>
  <input class="av-input is-invalid" id="slug" name="slug" value="my-product"
         aria-invalid="true" aria-describedby="slug-error">
  <p class="av-field__error" id="slug-error">This slug is already in use.</p>
</div>

Plus a summary at the top of the form, which is what screen-reader users find first:

html
<div class="av-alert av-alert--danger-soft av-form-errors" role="alert" tabindex="-1"
     data-av-form-errors>
  <svg class="av-icon av-alert__icon" aria-hidden="true" viewBox="0 0 24 24">
    <circle cx="12" cy="12" r="9"/><path d="M12 7.5v5.5M12 16.2v.3"/>
  </svg>
  <div class="av-alert__body">
    <h2 class="av-alert__title" data-av-form-errors-title>There are 2 problems with this form</h2>
    <ul>
      <li><a href="#slug">URL slug is already in use</a></li>
      <li><a href="#price">Price must be greater than 0</a></li>
    </ul>
  </div>
</div>

initValidate builds this summary itself on a failed submit, focuses it, and announces the count — give it data-av-form-errors and the hidden attribute and leave the <ul> empty. The markup above is what it produces, and is also what you render server-side when the page comes back with errors already known.

hidden works here because of one rule in @layer utilities. An author display declaration beats the UA [hidden] rule at any specificity, so hidden did nothing on this summary, the toast count, the Customizer, the empty state and a wizard's submit button until [hidden] { display: none } was declared in the utilities layer, where layer order dominates specificity. When you assert an element is hidden, read getComputedStyle(el).display — el.hidden is always whatever you set it to, which is exactly why this kept slipping through.


Enhanced select ​

html
<select class="av-select"
        id="country"
        name="country"
        data-av-select
        data-av-select-search="true"
        data-av-select-placeholder="Choose a country">
  <option value=""></option>
  <option value="ie">Ireland</option>
  <option value="gb">United Kingdom</option>
  <option value="de">Germany</option>
</select>

Progressive enhancement in action: without JS this is a working native <select> that submits correctly. With JS it gains search, keyboard navigation, and styling.

That is not a figure of speech here — the native <select> stays in the DOM and in the form, and it is still the element the browser validates and submits. If the bundle fails to load, or the vendor import 404s, you are left with a plainer control rather than a broken form.

Styled from tokens, not from the vendor's stylesheet. Tom Select's own CSS is deliberately not vendored: it hard-codes #d0d0d0 on the control border and #f8f8f8 on the active option, and a literal cannot follow every preset across light and dark. plugins/_tom-select.scss restyles its structural classes so the control matches .av-input exactly — an enhanced select beside a plain one in the same form is the most visible seam a template can have.

Two details are easy to miss and cost real bugs. The dropdown is anchored to <body>, because otherwise it is clipped inside .av-table-wrap and any scrolling card — the same problem .av-dropdown solves by promoting its menu to the top layer, since overflow does not consult z-index. And the vendor mirrors the control's value but not its validity, so initSelect copies is-invalid across; without that a required enhanced select stays visually valid while the summary at the top of the form already lists it.

Multi-select with tags ​

html
<select class="av-select" id="tags" name="tags[]" multiple
        data-av-select
        data-av-select-create="true"
        data-av-select-max-items="8">
  <option value="urgent" selected>Urgent</option>
  <option value="billing">Billing</option>
</select>
html
<select class="av-select" id="customer" name="customer_id"
        data-av-select
        data-av-select-url="/api/customers/search"
        data-av-select-min-length="2"
        data-av-select-label-field="name"
        data-av-select-value-field="id">
</select>
js
// The module handles debouncing, abort on new input, and error states
{
  load(query, callback) {
    this.abortController?.abort();
    this.abortController = new AbortController();
    fetch(`${url}?q=${encodeURIComponent(query)}`, { signal: this.abortController.signal })
      .then((r) => r.json())
      .then(callback)
      .catch((e) => { if (e.name !== 'AbortError') callback([]); });
  }
}

Full options: Form Enhancements.


Specialised inputs ​

OTP / verification code ​

html
<div class="av-otp" data-av-otp>
  <label class="av-field__label" for="otp-0">Verification code</label>
  <div class="av-otp__inputs">
    <input class="av-otp__input" id="otp-0" inputmode="numeric" maxlength="1"
           autocomplete="one-time-code" aria-label="Digit 1 of 6">
    <input class="av-otp__input" inputmode="numeric" maxlength="1" aria-label="Digit 2 of 6">
    <!-- … -->
  </div>
  <input type="hidden" name="code">
</div>

The module handles: auto-advance, backspace-to-previous, paste distribution across all inputs, arrow navigation, and populating the hidden field. autocomplete="one-time-code" lets iOS and Android autofill the SMS code.

Password strength ​

html
<div class="av-field">
  <label class="av-field__label" for="pw">Password</label>
  <div class="av-input-group">
    <input class="av-input" type="password" id="pw" name="password"
           autocomplete="new-password"
           data-av-password-strength
           data-av-password-strength-meter="#pw-meter"
           aria-describedby="pw-meter-text">
    <button class="av-btn av-btn--outline" type="button"
            data-av-password-toggle="#pw" aria-label="Show password" aria-pressed="false">
      <svg class="av-icon" aria-hidden="true" viewBox="0 0 24 24"><path d="M2 12s3.5-6 10-6 10 6 10 6-3.5 6-10 6S2 12 2 12z"/><circle cx="12" cy="12" r="3"/></svg>
    </button>
  </div>

  <div class="av-strength" id="pw-meter" data-av-score="0" aria-hidden="true">
    <span></span><span></span><span></span><span></span>
  </div>
  <p class="av-field__hint" id="pw-meter-text" aria-live="polite">Enter a password</p>
</div>

The meter bars are aria-hidden; the text is the accessible output, in a polite live region. A colour-only strength indicator is meaningless to a colour-blind or screen-reader user.

Warning — never enforce composition rules ("must contain an uppercase letter and a symbol"). NIST SP 800-63B explicitly recommends against them: they produce predictable passwords. Enforce length (≥ 12) and check against a breached-password list instead.

Input masking ​

html
<input class="av-input" data-av-mask data-av-mask-pattern="+000 00 000 0000"
       type="tel" autocomplete="tel" inputmode="tel">

<input class="av-input" data-av-mask data-av-mask-type="currency"
       data-av-mask-currency="EUR" inputmode="decimal">

<input class="av-input" data-av-mask data-av-mask-pattern="IE00 AAAA 0000 0000 0000 00"
       data-av-mask-uppercase="true">

Masks must be forgiving of paste. If a user pastes +353 1 234 5678 into a mask expecting digits only, strip and re-apply rather than rejecting. IMask does this correctly.


Form wizard ​

html
<div data-av-wizard data-av-wizard-validate="true">

  <ol class="av-steps" data-av-wizard-steps aria-label="Progress">
    <li class="av-steps__item" data-av-state="done">
      <span class="av-steps__marker" aria-hidden="true">
        <svg class="av-icon" aria-hidden="true" viewBox="0 0 24 24"><path d="M4 12.5l5 5 11-11"/></svg>
      </span>
      <span class="av-steps__label">Account</span>
    </li>
    <li class="av-steps__item" data-av-state="current" aria-current="step">
      <span class="av-steps__marker" aria-hidden="true">2</span>
      <span class="av-steps__label">Company</span>
    </li>
    <li class="av-steps__item" data-av-state="todo">
      <span class="av-steps__marker" aria-hidden="true">3</span>
      <span class="av-steps__label">Billing</span>
    </li>
  </ol>

  <form>
    <fieldset class="av-wizard__panel" data-step="1" hidden>
      <legend class="av-visually-hidden">Account details</legend>
      …
    </fieldset>

    <fieldset class="av-wizard__panel" data-step="2">
      <legend class="av-visually-hidden">Company details</legend>
      …
    </fieldset>

    <div class="av-wizard__actions">
      <button class="av-btn av-btn--outline" type="button" data-av-wizard-prev>Back</button>
      <button class="av-btn av-btn--primary" type="button" data-av-wizard-next>Continue</button>
      <button class="av-btn av-btn--primary" type="submit" hidden data-av-wizard-submit>Create account</button>
    </div>
  </form>
</div>
RequirementImplementation
Each step is a <fieldset> with a <legend>Groups fields semantically
Current step marked aria-current="step"Announced
Step change announced"Step 2 of 3: Company details." through the runtime's live region
Focus moves to the new panel's first fieldOtherwise keyboard users are lost
Validation runs before advancingOn by default; data-av-wizard-validate="false" turns it off
Data preserved when going backHidden panels stay in the DOM, never destroyed
Deep-linkable#step-2 in the URL restores position

Layout ​

html
<form class="av-stack-4">
  <fieldset>
    <legend class="av-fieldset__legend">Personal details</legend>
    <div class="av-field-row">
      <div class="av-field">…</div>
      <div class="av-field">…</div>
    </div>
    <div class="av-field">…</div>
  </fieldset>

  <fieldset>
    <legend class="av-fieldset__legend">Address</legend>
    …
  </fieldset>

  <div class="av-form-actions av-form-actions--sticky">
    <button class="av-btn av-btn--outline" type="button">Cancel</button>
    <button class="av-btn av-btn--primary" type="submit" data-av-loading data-av-loading-text="Saving…">
      Save changes
    </button>
  </div>
</form>

.av-field and .av-field-row space themselves, and they space each other. The rhythm is one rule naming both block types, so a stack mixing them is even — field → field, field → row, row → field and row → row all get the same gap. It named only .av-field once, and every boundary involving a row measured 0px while the pairs either side of it got 16. It shipped that way on the checkout's shipping address and no gate could see it: lint:css reads the SCSS and the SCSS was valid, and the visual suite is blind below roughly 34×34px and had recorded its baseline from the cramped markup, so it agreed with itself. Do not add a margin to a row on the page to work around this — the rule owns it.

Rules:

  • Labels above inputs, always (works at every width, in RTL, and with long translations)
  • Maximum two columns of inputs
  • Related short fields pair; long fields are full width
  • Group with <fieldset> + <legend>, not <div> + <h3>
  • Primary action rightmost (LTR), sticky on long forms

Prompt composer ​

A form for sending one message to an assistant: suggested prompts, a field that grows, a model picker and a send button. Enter sends and Shift+Enter starts a new line. The send button is aria-disabled while the field is empty.

html
<form class="av-prompt" data-av-prompt>
  <div class="av-prompt__suggestions">
    <button class="av-btn av-btn--outline av-btn--sm" type="button" data-av-prompt-fill="Summarise this month's revenue.">Summarise revenue</button>
  </div>
  <textarea class="av-prompt__field" rows="1" name="text" placeholder="Ask about your data…"
            aria-label="Message" data-av-autosize></textarea>
  <div class="av-prompt__bar">
    <p class="av-prompt__hint">Enter to send, Shift plus Enter for a new line.</p>
    <select class="av-select av-prompt__model" aria-label="Model" data-av-prompt-model>
      <option value="fast">Fast</option>
      <option value="balanced" selected>Balanced</option>
    </select>
    <button class="av-btn av-btn--outline av-btn--sm av-prompt__stop" type="button" data-av-prompt-stop>Stop</button>
    <button class="av-btn av-btn--primary av-prompt__send" type="submit" data-av-prompt-send>Send</button>
  </div>
</form>

The runtime does not answer the message. It raises av:prompt:submit with the form, the text and the model's value, and you answer it. While you are answering, set data-av-state="busy" on the form: the stop button replaces the send button and further sends are held. The stop button raises av:prompt:stop.

js
AdminVora.on('av:prompt:submit', async ({ form, text, model }) => {
  form.dataset.avState = 'busy';
  try {
    const reply = await fetch('/api/assistant', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ text, model })
    }).then((response) => response.text());
    document.querySelector('#reply').textContent = reply;
  } finally {
    delete form.dataset.avState;
  }
});

Write a reply with textContent, never innerHTML: the runtime has no sanitiser. Add .av-prompt--docked to sit the composer at the foot of a conversation, clear of its edges. The AI assistant page (/apps/assistant.html) shows the composer with a streamed reply; the stream on that page is demo behaviour.

Unsaved-changes guard ​

data-av-dirty-guard on a form marks it dirty on the first edit. While it is dirty, leaving the page asks first: the browser's own prompt on unload, and an AdminVora.confirm dialog on a link click. Submitting or resetting the form clears it.

Put a [data-av-save-bar] inside the form and the guard also shows it while there are unsaved changes. It is a sticky bar at the bottom of the viewport, so Save and Discard stay in reach while the reader scrolls a long form. Its buttons are the form's own submit and reset, so they work with no script between them; the runtime only shows and hides the bar.

html
<form data-av-validate data-av-dirty-guard novalidate>
  <!-- fields -->
  <div class="av-save-bar" data-av-save-bar hidden>
    <p class="av-save-bar__text">You have unsaved changes</p>
    <div class="av-save-bar__actions">
      <button class="av-btn av-btn--ghost av-btn--sm" type="reset">Discard</button>
      <button class="av-btn av-btn--primary av-btn--sm" type="submit">Save changes</button>
    </div>
  </div>
</form>

The bar announces itself once, politely, when it first appears, and never again while the form stays dirty, so typing does not repeat it.


Search-engine preview ​

data-av-seo mirrors three fields into a mock search result as they are typed. The source attributes end in -from and the bare names belong to the elements the module writes into:

html
<div class="av-seo-preview" data-av-seo data-av-seo-noun="post"
     data-av-seo-title-from="#metaTitle"
     data-av-seo-desc-from="#metaDescription"
     data-av-seo-slug-from="#slug">
  <p class="av-seo-preview__url" data-av-seo-url
     data-av-seo-base="example.com › blog › ">example.com › blog › …</p>
  <p class="av-seo-preview__title" data-av-seo-title>Untitled post</p>
  <p class="av-seo-preview__desc" data-av-seo-desc>No description yet.</p>
</div>

Two things here are decisions rather than syntax.

A source attribute and a target attribute must never share a name. These used to: the root carried data-av-seo-title="#metaTitle" and the paragraph carried data-av-seo-title, one name doing both jobs. Nothing inside the module could see it, because querySelector never matches the element it is called on — what saw it was everything outside. Any selector reaching for the preview's title got the whole preview.

data-av-seo-noun decides the empty-title fallback, which reads Untitled <noun> and defaults to product. It is a noun attribute for the same reason data-av-grid-noun is one: a module with no opinion about what it is previewing should not have one caller's word compiled into it.


Publish readiness ​

data-av-publish turns a checklist into the single writer for whether a form is finished. One pass over the rows writes each row's tick, its badge, the meter, the summary sentence and the primary button's state — so the panel cannot say "ready" over a list showing a gap.

html
<section class="av-card" data-av-publish>
  <p data-av-publish-summary>—</p>
  <span data-av-publish-count>—</span>
  <div class="av-progress" role="progressbar" data-av-publish-progress>
    <div class="av-progress__bar"></div>
  </div>

  <ol class="av-checklist">
    <li class="av-checklist__item"
        data-av-publish-check="slug" data-av-publish-field="#slug">
      <span class="av-checklist__marker" aria-hidden="true"></span>
      <span class="av-checklist__body">
        <h3 class="av-checklist__title">An address</h3>
      </span>
      <span class="av-badge av-checklist__action" data-av-publish-badge>—</span>
    </li>
    <li class="av-checklist__item" data-av-publish-level="advisory"
        data-av-publish-check="excerpt" data-av-publish-field="#excerpt"
        data-av-publish-max="160">
      …
    </li>
  </ol>

  <button class="av-btn av-btn--primary" type="submit" data-av-publish-action>Publish</button>
</section>
AttributeOnMeans
data-av-publishthe panelThe root. Fields are looked up inside the enclosing <form>
data-av-publish-checka rowThe requirement's name, used in events
data-av-publish-fielda rowSelector for the field it reads
data-av-publish-levela rowadvisory never blocks; anything else is required
data-av-publish-mina rowMinimum trimmed length, default 1
data-av-publish-maxa rowLength above which the row reads Too long
data-av-publish-badgea rowWhere the word goes: Done / Required / Recommended / Too long
data-av-publish-count, -progress, -summarythe panelThe meter, the bar and the sentence
data-av-publish-actiona buttonThe control the panel guards

Exceeding a maximum never blocks. Nothing is missing — the field is simply longer than what survives a search result, which is advice about presentation. A gate that refuses to publish over a style preference is a gate somebody routes around within a week.

The button is guarded, not just dimmed. It carries aria-disabled, never the disabled property, and initActions enforces it from a capture-phase listener on the document — which also reads out whatever aria-describedby points at, so the button is described by the summary sentence rather than by a tooltip nobody hears. Read buttons and actions for why a bare aria-disabled with nothing enforcing it is worse than no state at all.


Accessibility checklist ​

  • [ ] Every input has a <label for> — no placeholder-only labels
  • [ ] required is a real attribute, not just a visual asterisk
  • [ ] Correct autocomplete and inputmode on every field
  • [ ] aria-describedby links both help and error text
  • [ ] aria-invalid set on invalid fields
  • [ ] Errors are in text, not colour alone
  • [ ] Error summary at the top with in-page links, focused after a failed submit
  • [ ] Field groups use <fieldset> + <legend>
  • [ ] Focus moves to the first error on submit
  • [ ] Form works with JavaScript disabled
  • [ ] No type="number" for phone/card/postcode/ID
  • [ ] Password fields allow paste (never onpaste="return false")
  • [ ] Submit button disabled during submission to prevent double-posting
  • [ ] CSRF token present on every POST

Read next: Tables & Data Grids.

Documentation for @creativeigniter/adminvora