GrFormField

The container of the error always lives in the DOM and changes only its text, and the aria-describedby of the control always contains its id. The reason: some AT do not re-read the description after the attribute itself has changed — an error added together with a new aria-describedby could stay unread. An empty container goes into sr-only, so no empty line appears in the markup of the field.

error accepts both a string and an array: one field sometimes has several complaints (the server’s answer, the validation of a file). Inside a form the error is taken from GrForm by name, and an explicit prop overrides it.

showMessage: false leaves the field invalid for the control and for AT but does not show the text — for dense forms where the errors are explained by a summary above.

focusout also bubbles when the focus moves inside the field: from an input to its own clear button, between the checkboxes of a group. The field is validated only if the focus has left the bounds of the root (relatedTarget outside the field or null) — otherwise it turned red before the user had finished filling it in.

<label for> points at the id from the context, and it is the control itself that hangs that id on itself (useGrFormFieldContext()). If there is no such element inside the field, in dev mode the component warns in the console: otherwise a click on the label silently does nothing, and for a screen reader there is no link at all.

Widgets with an ARIA role (GrCheckbox, GrRadioGroup, GrCheckboxGroup) do not support <label for> — they take their name through aria-labelledby on field.labelId.

aria-describedby, aria-labelledby and aria-errormessage set on the control go to the element with the role or to the input itself — not to the wrapper, where they mean nothing — and are combined with the id of the field’s hint and error, separated by spaces, without duplicates. So an explanatory line under a checkbox outside GrFormField is announced, and inside a field it is announced together with the field’s hint:

<template>
  <GrCheckbox v-model="consent" aria-describedby="consent-terms-note">
    I agree
  </GrCheckbox>
  <p id="consent-terms-note">
    The terms can be withdrawn in your profile.
  </p>
</template>

The * marker in the label is marked aria-hidden: for a screen reader it does not exist at all, and the only source of requiredness is the control itself. It takes required from the context through useGrFormFieldContext() and turns it into aria-required.

The direct path is not open to every role. aria-required and aria-readonly are allowed by textbox, radiogroup, checkbox, combobox and their neighbours, but not by role="group": axe fails that as a critical aria-allowed-attr. A group control therefore declares both states on its focusable descendants rather than on itself. A working example is GrCheckboxGroup: the required of the group reaches the aria-required of every checkbox.

aria-invalid, on the contrary, stays on the group itself. Duplicated on every item, it would make the narrator repeat “invalid entry” as many times as there are checkboxes in the group; on an error the items only change colour.

That concerns your widget too: a role with a restricted set of attributes is not a reason to leave a field without a declared requiredness, but a reason to push it down to the descendants.

labelPosition="start" puts the label on the left, and labelWidth sets the width of its column — otherwise the columns of controls in a form drift apart by the length of the labels. The hint and the error stay beside the control: they are about it, not about the label. With the label to the side both stand below the control, and the label is as tall as a single-line control of its size and centred, that is, on the line of the text in the field. Above the control the hint would pull the label away from the field: rows with a hint and without one would drift apart. The order of the descriptions for AT is set by aria-describedby (the hint, then the error), not by the DOM.

size (xs…lg) scales the label, the hint, the error and the vertical rhythm; it is taken from GrConfigProvider unless it is set locally.

The error is rendered in the flow below the control: a submit with three empty fields adds three lines, and a form in a dialog, a sliding panel or a fixed-height block jumps or gets clipped. reserveMessage holds space for the message line while there is no error — the appearance of the text does not change the height of the field:

<template>
  <GrFormField label="IBAN" :error="ibanError" reserve-message>
    <GrInput v-model="iban" />
  </GrFormField>
</template>

Not set on the field — it is taken from GrForm (reserveMessage for the whole form), then from GrConfigProvider (componentDefaults.GrFormField.reserveMessage). The field’s own prop is stronger: :reserve-message="false" removes the reserve from one field in a reserving form. One line is reserved: several errors (error: string[]) and a long text that has wrapped onto a second line still grow below it. showMessage: false holds no reserve — there will be no text.

#label, #hint, #error (which receives errors: string[]) and the default one — the control itself.

validateStatus (validating/success): GrForm has no channel for the state of an asynchronous rule, and the prop would be purely manual — the status is needed on the side of the form first.