Skip to content

InputFieldMapper

X-05 · Composites · App components

All elements · InputFieldMapper on the Composites page

Last checked 2026-10-22 · Awaiting approval · Accessibility tests

Copies the bun run a11y:approve command for InputFieldMapper.

InputFieldMapper

X-05WCAG 2.2 AA · Passed #449

Dispatches a FieldType to the right control. Visually it adds only the property-type icon in the label; filter mode lays Fields out in a compact wrapping row, and click-to-edit mode uses Field's rest state.

The specimens below are copied from mapper.html, which shows them inside the app shell, by bun scripts/design-pages/build-composite-pages.mjs — edit that file, not this one; --check fails when they drift.

Axis Values
FieldType String · Date · DateTime · Boolean · Numeric · Currency · User · UserMultiple · Classification · Hierarchy · ListOfValues · LinkedObject · RichText · File …
.qf-field__type-icon · .qf-filter-row label icon / filter-mode layout
One Field per type
jd
Finance › Invoices
CS-2041
Attach
Filter mode

Guidance

When to use

  • Use it wherever a property's FieldType decides which control edits it, such as String, Date, User, ListOfValues or LinkedObject.
  • Use it in forms and object property grids so every property of a type gets the same control.
  • Use filter mode to lay out property filters in a compact wrapping row above or beside results.
  • Use click-to-edit mode when values are read most of the time and edited occasionally.

When to consider something else

  • Use a plain Field with a known control when the type is fixed at design time. See Field.
  • Use the Form composite for the sections, grid, error summary and actions around the mapped fields. See Form.
  • Use ObjectDisplay to show an object's properties read-only with click-to-edit. See ObjectDisplay.
  • Use the Search filter rail when filters need a full panel rather than one row. See Search.

Usability

Do
  • Show the property-type icon (.qf-field__type-icon) before the label so users can tell types apart.
  • Keep the visible label as the property's name; the icon adds type, not meaning.
  • Map each FieldType to one control consistently across the app.
  • Use .qf-filter-row for filter mode so fields wrap instead of overflowing.
  • Right-align Numeric and Currency values (data-align="end").
Don’t
  • Do not rely on the type icon to convey the type; it is decorative.
  • Do not use placeholder text as the label in filter mode.
  • Do not invent a new control for a FieldType the mapper already handles.

Accessibility

Keyboard

InputFieldMapper keyboard
Keys Action
Tab Moves to the next mapped control in DOM order.
Control keys Each mapped control keeps its own keyboard model: text fields edit, Select opens with Arrow Down, toggles switch with Space, date fields open their picker.
Enter In click-to-edit mode, the binding must turn the focused value into its Field; Escape must cancel and restore the value.

Roles and names

  • Every control is labeled by a <label for> that points at its id.
  • The type icon is inside the label with aria-hidden="true" on its SVG, so the accessible name is the property name only.
  • Boolean maps to a switch-appearance .qf-toggle; its inner label gives the state text, and the field label must not double the name.
  • File maps to a compact .qf-dropzone; its field label has no for in the reference, so the binding must associate the label with the dropzone's file input or button.
  • LinkedObject and User values render as .qf-labeled chips with the text label, not the icon, carrying the name.

Focus

  • Focus order follows the visual order of the fields, including in the wrapping filter row.
  • When click-to-edit turns a value into a Field, focus moves into the control and returns to the value when editing ends.

Other requirements

  • Each control inherits its own component guidance; the mapper adds only the label icon and layout.
  • Filter-mode fields are data-size="sm"; confirm controls meet 24 by 24 CSS pixels (2.5.8).
  • Labels and required or invalid states must be in text, not icon or color alone (1.3.1, 1.4.1, 3.3.2).

Test your implementation too. This guidance covers the element as specified here. How a screen composes it (labels, order, announcements) still needs its own keyboard and screen reader check.

Accessibility tests

WCAG 2.2 AA · Passed

Passed the gate (run 358b316 on 2026-10-22): no finding in any theme. Awaiting a person’s approval of the checklist below.

InputFieldMapper test checklist
Area Automated A person checks
General Passed Color is never the only cue, text alternatives say the same thing as the graphic, and the element reads the same in the light and the dark theme.
Zoom Passed At 200% zoom, at 320 CSS pixels wide and with the WCAG text-spacing overrides, nothing is lost, clipped or overlapping.
Keyboard Passed Every row of the Keyboard table works, focus is always visible and never trapped, and the tab order follows the reading order. (3 rows)
Screen reader Passed With NVDA or JAWS on Windows and VoiceOver on macOS, names, roles and states are announced as Roles and names says, and changes are announced once. (5 items)

Approving. When the checklist passes on the checked run, record it with bun run a11y:approve -- mapper --by "Your name" and commit a11y/approvals.json with the rebuilt pages. All test status

Package

Consumers link one stylesheet, css/classic/index.css, which includes every element. The files below are where this element is defined.

InputFieldMapper package
Source No stylesheet of its own
Specimens also use Avatar · Box · Button · Card · Chip · Control · Dropzone · Field · Icon · ObjectDisplay · Select · Table · Text · Toggle · Toolbar
Sprites sprites/icons.svg
React Not yet available: the React binding has not started.

Latest updates

No recorded changes yet.

All release notes