Skip to main content

useTextInput

This hook can be used to create a custom TextInput with all the accessibility improvements needed.

Usage

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

const MyTextInput = () => {
const { ref, ...rest } = useTextInput({ ...requiredProps });

return <TextInput ref={ref} {...rest} />;
};

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

Props

editable (optional)

TypeDefault
booleanundefined

nextFormField (optional)

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

TypeDefault
RefObjectundefined

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

component.

TypeDefault
stringundefined

nextFieldId

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

TypeDefault
stringundefined

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:

  • Set the error, in case of failure, as part of the accessibilityHint

Here can be find more information about error handling in Forms

TypeDefault
booleanundefined

hasError

If true returns the errorMessage as part of the accessibilityHint

TypeDefault
booleanundefined
info

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

errorMessage

TypeDefault
stringundefined

The error message to be announced by the screen reader.

requiredMessage

TypeDefault
stringundefined

The required message to be announced by the screen reader as part of the accessibility hint.