Appearance
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
Basic select with search
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>Remote search
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.
| Attribute | Default |
|---|---|
data-av-select-placeholder | — |
data-av-select-create | false |
data-av-select-max-items | unlimited (multiple only) |
data-av-select-search | true; false removes the search input |
data-av-select-url | — (remote search) |
data-av-select-min-length | 2 |
data-av-select-label-field / -value-field | name / 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/maxrather 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-timepickerhas 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:
| Enhancement | Native fallback |
|---|---|
| Tom Select | <select> — works, submits, is accessible |
| Native pickers | The same <input> with no enhancement |
| IMask | <input> — accepts the value unmasked |
| Autosize | <textarea> at its default height |
| OTP | Six 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.