TextInput

TextInput is an extension of the React Native TextInput component, focused on accessibility.

import { TextInput } from 'react-native-ama';

<TextInput
  style={styles.input}
  placeholder=""
  onChangeText={newText => setText(newText)}
  defaultValue={text}
  label={<Text style={styles.label}>First name:</Text>}
  labelPosition="afterText"
  returnKeyType="next"
  nextFormField={nextFormField}
/>;

Accessibility improvements

Compared to the default React Native component, this custom component:

• Uses the given label text as accessibilityLabel; if none is provided
• Hides the label from the screen reader (as it would provide redundant information)
• Handles the value returnKeyType
• Handles focusing the next form field when returnKeyType is next
• Checks for keyboard trap

accessibilityLabel

The input field must have an accessibilityLabel, and also its corresponding must be hidden from the screen reader to avoid redundant announcement of the same label.

returnKeyType

When the user lands on a <TextInput /> the returnKeyType needs to be handled allowing them to either focus the next control, when returnKeyType="next", or submit the form, when returnKeyType="done". The React Native default <TextInput /> allows customing the returnKeyType prop but leaves the developer to handle the action when the button is pressed.

Instead, the AMA customised TextInput automatically handles the property returnKeyType and its action:

• If the TextInput is the last one of the Form then sets returnKeyType="done", otherwise returnKeyType="next"
• The next key focuses the next TextInput or FormField
• The done button submits the Form

note

AMA does not alter the "returnKeyType" when manually passed as a prop.

Keyboard trap

Once the user presses the next key, AMA checks that the:

• The current TextInput does no longer have the focus
• If the next field is a TextInput, then check if it gained the focus

Additional Props

Required labelComponent

The custom labelComponent.

Type	Default
JSX.Element	undefined

If no accessibilityLabel is provided, the component children are used to generate the one. Also, the label is modified, and the following prop added:

• importantForAccessibility: no
• accessibilityElementsHidden: true

So, the label itself is made hidden from the screen reader.

info

If the label content ends with a *, this is stripped from the accessibilityLabel, example:

<TextInput
  style={styles.input}
  placeholder=""
  onChangeText={newText => setText(newText)}
  defaultValue={text}
  label={<Text style={styles.label}>First name:*</Text>}
  labelPosition="afterText"
  returnKeyType="next"
  nextTextInput={lastNameRef}
/>

The accessibilityLabel generate is: "First name:"

labelPosition

Specify where to render the label.

Type	Default
'beforeInput' | 'afterInput'	'beforeInput'

nextFormField (optional)

This parameter specifies the next form field to focus on when the next button is pressed.

Type	Default
RefObject	undefined

Example

<TextInput
  style={styles.input}
  placeholder=""
  onChangeText={newText => setText(newText)}
  defaultValue={text}
  label={<Text style={styles.label}>Last name:</Text>}
  returnKeyType="next"
  nextFormField={emailRef}
  ref={lastNameRef}
/>

id

The field ID. This info is stored, with the field ref, inside the <Form /> component.

Type	Default
string	undefined

nextFieldId

The ID of the next field to focus when the user taps on the next button of the keyboard

Type	Default
string	undefined

Required hasValidation

This property is used to know if the input can display an error, in case of failed validation; and if so is used to: pf

1. Set the error, in case of failure, as part of the accessibilityHint
2. Hides the errorComponent from the accessibility tree to prevent redundant information for the user

Here can be find more information about error handling in Forms

Type	Default
boolean	undefined

hasError

If true the component sets the given error as part of the accessibilityHint

Type	Default
boolean	undefined

info

The component will try to extract any text within the errorComponent if no errorText is provided

errorComponent

The error component to render in case of hasError = true. The position of the component can be changed using the errorPosition property.

Type	Default
JSX.Element	undefined

info

The component is automatically modified with the following properties added:

• importantForAccessibility: no
• accessibilityElementsHidden: true

to hide it from the accessibility tree.

errorPosition

The position where to render the errorComponent

Type	Default
'belowLabel' | 'afterInput'	'afterInput'

Related guidelines

• Forms