useTextInput

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

note

To use useTextInput it must be wrapped by the <Form> provider component from this package.

Usage

import { useTextInput } from '@react-native-ama/forms';

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

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

Form TextInputs must be wrapped by a Form Provider

import { Form } from '@react-native-ama/forms';

import { MyTextInput } from './MyTextInput';

const CustomForm = () => {
  return (
    <Form onSubmit={handleSubmit} ref={ref}>
      <FormTextInput {...props} />
    </Form>
  );
};

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)

Type	Default
boolean	undefined

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

This property is used to set the input as required and will display and error if a value has not been set

Type	Default
boolean	undefined

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

Type	Default
boolean	undefined

hasError

If true returns the errorMessage 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

errorMessage

Type	Default
string	undefined

The error message to be announced by the screen reader.

requiredMessage

Type	Default
string	undefined

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

Related guidelines

• Forms