InputField

The InputField component has been designed with accessibility in mind, providing features that enhance the experience for users of assistive technologies.

The following props are available to improve the accessibility of your InputField component:

The InputField component automatically handles several important ARIA attributes:

• aria-invalid: When the error prop is provided, the input is automatically marked as invalid (aria-invalid="true"). This helps screen readers announce to users that the input contains an error.

• aria-describedby: This attribute is automatically managed to associate error or help text with the input field:

  • When the component is not inside an InputGroup and has error or help text, a unique ID is generated (based on the input’s ID) and is combined with the ariaDescribedby prop to ensure all descriptions are announced by screen readers.
  • When the component is inside an InputGroup, the InputGroup completely overrides any ariaDescribedby value that was set on the InputField. The InputGroup sets its own feedback ID as the aria-describedby value if there are any error or help values and the tooltip is shown.

These automatic features ensure that the InputField remains accessible even without explicitly setting every ARIA attribute, while still allowing for customization when needed. See the Examples section for detailed usage examples of ariaDescribedby.

• When no visible label is provided, use ariaLabel to provide an accessible name for the input field to ensure the input’s purpose is clear to screen reader users. Alternatively, you can use ariaLabelledby to reference the ID of an existing element that labels the input.

• Always ensure that ariaLabel text and any text in elements referenced by ariaLabelledby are properly translated to match the user’s language.

• Don’t rely solely on placeholder for providing instructions or label of the input.

• For inputs that trigger autocomplete behavior or control other elements, use the appropriate ARIA attributes (ariaAutocomplete, ariaActiveDescendant, ariaHasPopup, ariaExpanded, ariaControls) to make the functionality accessible.

• When using prefix or suffix elements, ensure they don’t interfere with the accessibility of the input field and are properly labeled if they are interactive.

<InputField label="Email address" placeholder="your@email.com" type="email" name="email" required />

In this example, screen readers would announce “Email address, required, edit, email” when focusing on the input field.

<InputField
  label="City"
  placeholder="Start typing..."
  role="combobox"
  ariaHasPopup={true}
  ariaExpanded={suggestionsVisible}
  ariaControls="city-suggestions"
  ariaAutocomplete="list"
  ariaActiveDescendant={activeItemId}
/>

In this example, the InputField is configured as a combobox with autocomplete features. Screen readers would announce information about the combobox state, including whether suggestions are available and which suggestion is currently active.

The ariaDescribedby prop allows you to specify an aria-describedby attribute for the InputField component. This attribute links the component to additional descriptive text, enhancing accessibility by providing supplementary information to screen readers.

<InputField label="Password" type="password" ariaDescribedby="password-requirements" />
<p id="password-requirements" style={{ display: "none", visibility: "hidden" }}>
  Password must be at least 8 characters long and include at least one uppercase letter and one number.
</p>

When using the error or help props, the component automatically manages the aria-describedby attribute:

<InputField label="Username" error="This username is already taken" />

In this example, the error message is automatically associated with the input field via aria-describedby.

If you provide both an ariaDescribedby prop and use error or help, the component automatically combines them, ensuring that screen readers announce all descriptive content:

<InputField label="Email" error="Invalid email format" ariaDescribedby="email-hint" />
<p id="email-hint" style={{ display: "none", visibility: "hidden" }}>
  We'll never share your email with anyone else.
</p>

In this example, both the “email-hint” text and the error message will be announced by screen readers. The text from ariaDescribedby will be announced first, followed by the text from error.

When using InputField within an InputGroup, the aria-describedby association follows these rules:

If the InputGroup has error/help messages, all child components will have aria-describedby set to these values by default:

<InputGroup label="Passenger details" error="Incomplete information">
  <InputField label="First name" />
  <InputField label="Last name" />
</InputGroup>

In this example, all InputField components will have the InputGroup’s error message “Incomplete information” announced by screen readers.

If individual InputField components have their own error/help messages (and the InputGroup doesn’t), only those specific components will have aria-describedby set:

<InputGroup label="Passenger details">
  <InputField label="First name" />
  <InputField label="Last name" error="Last name is required" />
</InputGroup>

In this example, only the second InputField will have its error message “Last name is required” announced.

Avoid setting ariaDescribedby directly on InputField components when inside an InputGroup, as these values will be overwritten by the InputGroup’s internal accessibility logic:

<InputGroup label="Contact information">
  <Select options={countryOptions} label="Country" />
  <InputField
    label="Phone number"
    ariaDescribedby="phone-hint" // This will be overwritten
  />
  <p id="phone-hint" style={{ display: "none", visibility: "hidden" }}>
    Enter your phone number
  </p>
</InputGroup>

In this example, the ariaDescribedby value “phone-hint” will be ignored because the InputGroup manages the accessibility associations internally. Instead, rely on the InputGroup’s error/help props or the component’s own error/help props.