iOS/Android: Text input error for screenreaders

[amarlette]

Requires API Proposal

This issue requires a new API. An API proposal should be added and discussed before proceeding with implementation. The API proposal can be added in the comments of this issue or linked as a separate issue.

Description

Cannot specify error text on TextInputs. Errors for form fields, while they can be displayed visually in many unique ways, need to have a strong association with the problematic field itself for accessibility. Otherwise, any users who can't visually see the relation of the error to the field won't necessarily know which field is the problem.

React Native version:

v0.63

Expected Results

Upon focus of a text input in an error state, the error message specified should announced after the main focus announcement, prefixed with "Error: ". Upon changing the contents of a text input which puts the input into an error state, an error message should be announced prefixed with "Error: ".

Snack

https://snack.expo.io/X4NIqnJ2K

Android Details

To implement error states on Android, you should call the setError method of the TextView. This will automatically set the correct properties on the AccessibilityNodeInfo that will inform screen readers to this state. If you need to do this manually, what this does behind the scenes is call setContentInvalid(true) and setError(youErrorString) on the AccessibilityNodeInfo.

iOS Details

iOS has no standard pattern for the presentation of error states on text inputs, so I'd recommend we follow Android's pattern here. To do this, you'll need to implement a key press listener, and on change, detect if the field is now in an error state. If it is, you'll need to make a manual screen reader announcement of the error message, and append this message to the accessibilityValue for the field.

[kacieb]

API Proposal:

This will require adding a new prop to JS, and Android and iOS changes to use that prop.

JS

Add a new prop to TextInput:

  /**
   * String to be read by screenreaders to indicate an error state. If this value is
   * not null, an error will be announced. You can use onChangeText or onBlur to 
   * detect an error and set this prop. Once the error is gone, set this to null
   * to clear the error
   */
  errorMessage?: ?Stringish,

Example usage:
In this example, the TextInput goes into an error state if the user types "error" into the TextInput.

export default function Playground(): React.Node {
  const [text, setText] = React.useState('');
  const [error, setError] = React.useState(null);
  return (
    <TextInput
      error={error}
      onChangeText={newText => {
        setText(newText);
        setError(newText === 'error' ? 'this input is invalid' : null);
      }}
      value={text}
    />
  );
}

Note: onChangeText may not be the right place to announce the error. This API gives flexibility to set the error when needed. Another place might be onBlur, which is when the TextInput loses focus.

Implementation Thoughts

On Android, implementation will follow the suggestions in the issue. To avoid visual styling, we will call setContentInvalid(true) and setError(youErrorString) on the AccessibilityNodeInfo manually.

On iOS, since there is no way to do this sanctioned by Apple, we'll follow the recommended approach listed in the issue. The behavior will be as similar to Android as possible.

[zersiax]

Curious to know why this was moved back onto the backlog? This is definitely something that would be a dealbreaker for me if it woldn't work as described here.

[kacieb]

Curious to know why this was moved back onto the backlog? This is definitely something that would be a dealbreaker for me if it woldn't work as described here.

Hello! I changed teams and no longer had capacity to work on it, which is why I released the issue. It'd be really great if you wanted to pick this up, though! You can follow my proposal above if you're interested in working on this.

[grgr-dkrk]

I want to work on this.

[fabOnReact]

@blavalla I would like to work on this after completing the review of #31666 Thanks 🙏

[fabOnReact]

Thanks a lot @blavalla

1- Issues iOS/Android: Text input error for screenreaders #30848 and Android: Error state change (text inputs) #30859 should be solved together (as explained in Brett comment).
2- Issue Android: Error state change (text inputs) #30859 may require updates to Android API (see test case Change of error state from onChangeText show/hides a TextInput error). I found a draft solution for the issue and I think is related to updateState. I will prepare a fix for this issue in a couple of days.
3- I tested Kacie's API Proposal (videos of my tests, my draft branch). I agree with her API Proposal. The prop name would be errorMessageAndroid.
4- I did not yet investigate the iOS API

[fabOnReact]

I added the following test cases. I tested the PR on Fabric and Paper iOS.

76. iOS - announce lastChar (not entire text) onChangeText and avoid multiple announcements (Fabric) (link)
77. iOS - announces or does not announce the accessibilityError through Button onPress (not onChangeText) (Fabric) (link)
78. iOS - the error is announced with accessibilityInvalid true and does not clear after typing text (onChangeText) (Fabric) (link)

I'll complete the below TODOs and move the PR to ready to Review by Monday morning (New York time).

• Implement changes from my own code review
• Implement solution for multiline TextInput (iOS)
• Further review, test and improve the pull request
• fix regression in Fabric iOS. Reintroduce solution from commit 318a964

[fabOnReact]

iOS - Exception thrown while executing UI block: - RCTUITextView setAccessibilityErrorMessage:]: unrecognized selector sent to instance (iOS - Paper on main branch)

solved with 34c5526

[fabOnReact]

I moved PR #33468 Ready for Review.
I remain available for any improvement. Thanks

[github-actions]

This issue is stale because it has been open 180 days with no activity. Remove stale label or comment or this will be closed in 7 days.

[github-actions]

This issue was closed because it has been stalled for 7 days with no activity.

[fabOnReact]

PR not merged, could add it as separate library

[zersiax]

This is considered basic functionality. This should not be a library, as developers will not know of its existence and therefore render an accessibility experience that is inferior without the package installed. This should be part of core.

[zersiax]

My problem with that approach is that developers aren't going to make that choice. They won't know the choice exists, or they won't care enough to make the choice, or their hands will be tied by management/an overzealous product owner/what have you to not make the choice for all sorts of different reasons. It'd be one more thing to maintain, one more third-party dependency.
Proper error prevention and reporting is among the basics of basics where accessibility is concerned. Not getting this right is a failure of WCAG, which will get a company sued and will give users who actually need this to work a bad user experience. Apps on mobile are already being yanked under this same umbrella and it's up to the maintainers of React Native to realize that this has priority and can't be hanging out in the wings for years. If you reckon this will take years, I'm all for creating a fork of the component so there is at least an option for devs who care about not discriminating against a bunch of users. This really needs to be in main though, eventually.