Skip to content

Form Enhancements ​

Tom Select, IMask and the native date, time, colour and range pickers — all progressive enhancements over native controls.


Tom Select ​

27 KB · Apache-2.0 · lazy

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

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>
</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>

The endpoint receives ?q=<query> and returns an array (or { data: [...] }) of objects with the label and value fields. A query shorter than data-av-select-min-length (default 2) is not sent, and a new keystroke aborts the request in flight, so a slow response for "ma" can never overwrite the results for "mark". A multiple select gets a remove button on each tag.

AttributeDefault
data-av-select-placeholder—
data-av-select-createfalse
data-av-select-max-itemsunlimited (multiple only)
data-av-select-searchtrue; false removes the search input
data-av-select-url— (remote search)
data-av-select-min-length2
data-av-select-label-field / -value-fieldname / id

For custom option templates, reach the instance from av:select:ready ({ el, instance }).

Theming ​

scss
@layer plugins {
  .ts-wrapper {
    .ts-control {
      background: var(--bs-form-control-bg, var(--av-surface-raised));
      border: 1px solid var(--av-border-default);
      border-radius: var(--av-radius-md);
      padding: var(--av-space-2) var(--av-space-3);
      min-block-size: var(--av-size-control-md);
      font-size: var(--av-font-size-sm);
      color: var(--av-text-primary);
      box-shadow: none;
    }

    &.focus .ts-control {
      border-color: var(--av-border-focus);
      outline: var(--av-focus-width) solid var(--av-focus-color);
      outline-offset: -1px;
    }

    .ts-dropdown {
      background: var(--av-surface-overlay);
      border: 1px solid var(--av-border-subtle);
      border-radius: var(--av-radius-md);
      box-shadow: var(--av-shadow-lg);
      margin-block-start: var(--av-space-1);
      padding: var(--av-space-1);

      .option {
        border-radius: var(--av-radius-sm);
        padding: var(--av-space-2) var(--av-space-3);
        &.active   { background: var(--av-surface-sunken); }
        &.selected { background: var(--av-color-primary-subtle); color: var(--av-color-primary-text); }
      }
    }

    .item {
      background: var(--av-color-primary-subtle);
      color: var(--av-color-primary-text);
      border-radius: var(--av-radius-xs);
      padding: 1px var(--av-space-2);
    }
  }
}

Accessibility ​

Tom Select implements combobox semantics out of the box. It also moves label[for] onto its own generated control, which would leave the real <select> unnamed; the runtime gives the <select> an aria-labelledby pointing at the same label.


Native pickers — date, time, colour and range ​

Date, time, colour and range fields are the platform's own controls, enhanced by four hooks. There is no picker library: no supply chain, no bundle weight, and the native mobile pickers. The trade is that the appearance differs between browsers, and there is no inline calendar or drag-select range.

html
<!-- Date and time: styled native inputs -->
<input class="av-input" type="date" name="due" value="2026-09-30" data-av-datepicker>
<input class="av-input" type="time" name="at" value="09:30" data-av-timepicker>

<!-- Date range: each bound limits the other through min/max -->
<div class="av-daterange">
  <input class="av-input" type="date" data-av-datepicker data-av-mode="range"
         value="2026-08-01" aria-label="From date" name="from">
  <span class="av-daterange__sep">to</span>
  <input class="av-input" type="date" value="2026-08-31" aria-label="To date" name="to">
</div>

<!-- Colour: swatch plus a readable, pasteable hex field kept in sync -->
<div class="av-color-field">
  <input class="av-color" type="color" data-av-colorpicker value="#3b82f6"
         aria-label="Brand colour" name="brand">
  <input class="av-input av-color-field__value" type="text" value="#3B82F6"
         aria-label="Brand colour hex value" spellcheck="false" name="brand_hex">
</div>

<!-- Range: filled track and a live value label -->
<div class="av-range-field">
  <input class="av-range" type="range" data-av-slider min="0" max="100" value="35"
         data-av-slider-suffix="%" aria-label="Discount percentage" name="discount">
  <span class="av-range-field__value">35%</span>
</div>
  • Range pairing uses min/max rather than a validation message, so the browser's own picker greys out impossible dates.
  • Colour: an invalid hex in the text field reverts to the swatch's value rather than leaving the two halves disagreeing.
  • Range: the fill is computed from min/max, so a slider bounded 20–80 fills correctly. data-av-slider-currency="EUR" formats the value as money instead of using a suffix. There is one handle; for a min/max range, use two number fields.
  • data-av-timepicker has no behaviour of its own. It exists so a buyer who swaps a vendor in targets a selector rather than editing every time field.

IMask ​

12 KB · MIT · lazy

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

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

<!-- Card -->
<input class="av-input" inputmode="numeric" autocomplete="cc-number"
       data-av-mask data-av-mask-type="card">

<!-- IBAN -->
<input class="av-input"
       data-av-mask data-av-mask-pattern="aa00 0000 0000 0000 0000 00"
       data-av-mask-uppercase="true">

<!-- Percentage -->
<input class="av-input" inputmode="decimal"
       data-av-mask data-av-mask-type="percent" data-av-mask-max="100">
js
const MASK_TYPES = {
  currency: (o) => ({
    mask: Number, scale: 2, thousandsSeparator: separatorFor(o.locale),
    radix: radixFor(o.locale), padFractionalZeros: true, normalizeZeros: true,
    min: o.min ?? 0, max: o.max ?? Number.MAX_SAFE_INTEGER
  }),
  card: () => ({
    mask: [
      { mask: '0000 000000 00000', regex: '^3[47]\\d{0,13}' },        // Amex
      { mask: '0000 0000 0000 0000', regex: '^(?:4|5[1-5]|6)\\d{0,15}' }
    ],
    dispatch: (appended, dynamicMasked) => {
      const number = (dynamicMasked.value + appended).replace(/\D/g, '');
      return dynamicMasked.compiledMasks.find((m) => number.match(m.regex))
          ?? dynamicMasked.compiledMasks[1];
    }
  }),
  percent: (o) => ({ mask: Number, scale: 2, min: 0, max: o.max ?? 100 })
};

Masks must be forgiving of paste. IMask reformats pasted input rather than rejecting it, which is why it was chosen over Cleave.js.

Always send the unmasked value:

js
mask.on('accept', () => { hidden.value = mask.unmaskedValue; });

Other enhancements ​

Auto-growing textarea ​

html
<textarea class="av-input" data-av-autosize data-av-autosize-max="320"></textarea>

The textarea grows with its content. data-av-autosize-max is a ceiling in pixels: past it, the field stops growing and scrolls, rather than pushing the submit button off the screen. Browsers with field-sizing: content use that instead.

Character counter ​

html
<input class="av-input" id="title" maxlength="60"
       data-av-counter data-av-counter-target="#title-count"
       aria-describedby="title-count">
<p class="av-field__hint"><span class="av-counter"><span id="title-count">0</span> / 60</span></p>

The count is written into the element named by data-av-counter-target, and .av-counter gets is-over past maxlength. Do not make the count a live region: it changes on every keystroke.

OTP input ​

html
<div data-av-otp data-av-otp-target="#code">
  <input class="av-otp__input" inputmode="numeric" maxlength="1"
         autocomplete="one-time-code" aria-label="Digit 1 of 6">
  <!-- ×6 -->
</div>
<input type="hidden" name="code" id="code">

Handles auto-advance, backspace-to-previous, arrow navigation, and paste distribution.

Password toggle ​

html
<button class="av-field-line__toggle" type="button"
        data-av-password-toggle="#pw"
        aria-label="Show password" aria-pressed="false">
  <!-- eye and eye-off icons -->
</button>

The runtime flips the input's type, aria-pressed, and the label between "Show password" and "Hide password".


Progressive enhancement, restated ​

Every enhancement on this page wraps a native control:

EnhancementNative fallback
Tom Select<select> — works, submits, is accessible
Native pickersThe same <input> with no enhancement
IMask<input> — accepts the value unmasked
Autosize<textarea> at its default height
OTPSix inputs, or one text input

Disable JavaScript on any AdminVora form and it still submits correctly. That is the test.


Checklist ​

  • [ ] Every enhancement wraps a real, named form control
  • [ ] Option templates escape all interpolated data
  • [ ] Remote searches are debounced and aborted
  • [ ] <input type="date"> used where it is sufficient
  • [ ] Masked fields submit the unmasked value
  • [ ] Range inputs have a label and a visible value
  • [ ] Counters are not live regions
  • [ ] All plugins re-theme on av:theme:change
  • [ ] All plugins call destroy() on unmount
  • [ ] Form works with JavaScript disabled

Read next: Notifications.

Documentation for @creativeigniter/adminvora