TextInput — qué es, entrada de texto y React Native

Qué es TextInput en React Native

TextInput es un componente de React Native que permite al usuario introducir texto mediante el teclado del dispositivo. Es el bloque de construcción principal para formularios de registro, barras de búsqueda, campos de mensajes y cualquier otro escenario que requiera entrada del usuario. A diferencia del desarrollo web, donde existen tipos de input separados (text, email, password, search), en React Native todas estas variantes se implementan mediante un único componente TextInput con diferentes props.

TextInput admite dos modos de operación: controlado(gestionado mediante el estado de React) y no controlado (mediante una ref). En el modo controlado, el valor del campo se almacena en el estado del componente y se actualiza mediante el callback onChangeText. Este enfoque se recomienda para la mayoría de las aplicaciones, ya que proporciona una única fuente de verdad y simplifica la validación.

Según React Native Handling Text Input, 2024, TextInput se adapta automáticamente a la plataforma: en iOS usa UITextField nativo, en Android — EditText. Esto garantiza el correcto funcionamiento del autocompletado, la autocorrección y los menús del sistema (cortar/copiar/pegar) sin configuración adicional.

Propiedades y API de TextInput

TextInput proporciona un amplio conjunto de props para controlar la entrada, la apariencia y el comportamiento. Todos los props se dividen en varias categorías: gestión del valor, tipo de teclado, estilo, eventos y características específicas de la plataforma.

Props de gestión del valor

value — el valor actual del campo (para modo controlado). onChangeText — callback invocado en cada cambio de texto. placeholder — texto de sugerencia mostrado cuando el campo está vacío. defaultValue — valor inicial para modo no controlado. maxLength limita el número máximo de caracteres que el usuario puede introducir.

Eventos de TextInput

El componente admite onFocus(el campo recibió el foco), onBlur (el campo perdió el foco), onSubmitEditing (el usuario presionó Enter/Return), onKeyPress (presión de tecla). El evento onEndEditing se llama después de finalizar la edición al perder el foco. Estos callbacks permiten implementar lógica compleja de validación y envío de formularios.

Props específicos de plataforma

En iOS: clearButtonMode (botón de limpieza), keyboardAppearance (teclado claro/oscuro), returnKeyType (tipo de botón Return), enablesReturnKeyAutomatically. En Android: textContentType (autocompletado), underlineColorAndroid, inlineImageLeft. secureTextEntry funciona en ambas plataformas para entrada de contraseñas.

Entrada controlada y no controlada

En React Native, TextInput puede funcionar en dos modos. En modo controlado, React gestiona el valor del campo: pasas el valor desde el estado y lo actualizas mediante onChangeText. En modo no controlado, React solo inicializa el campo y el valor similar a DOM se almacena dentro del componente nativo.

TextInput controlado

El modo controlado se recomienda para todos los formularios que requieran validación, filtrado o formateo de datos de entrada. El estado del campo está sincronizado con el estado del componente React, lo que proporciona control total sobre el valor.

const LoginForm = () => {
    const [email, setEmail] = useState('');
    const [password, setPassword] = useState('');

    return (
        <View>
            <TextInput
                placeholder="Email"
                value={email}
                onChangeText={setEmail}
                keyboardType="email-address"
                autoCapitalize="none"
            />
            <TextInput
                placeholder="Password"
                value={password}
                onChangeText={setPassword}
                secureTextEntry
                maxLength={32}
            />
        </View>
    );
};

En este ejemplo, ambos campos usan el modo controlado. El campo de email tiene el tipo de teclado email-address y la autocapitalización desactivada. El campo de contraseña usa secureTextEntry para ocultar los caracteres y está limitado a 32 caracteres mediante maxLength.

TextInput no controlado

El modo no controlado es adecuado para campos simples que no requieren validación o reacción inmediata a la entrada. El valor del campo se obtiene mediante una ref en el momento del envío del formulario.

const SimpleSearch = () => {
    const inputRef = useRef(null);

    const handleSearch = () => {
        console.log(inputRef.current.value());
    };

    return (
        <TextInput
            ref={inputRef}
            placeholder="Search..."
            onSubmitEditing={handleSearch}
        />
    );
};

En modo no controlado, el componente se renderiza más rápido ya que no requiere sincronización de estado en cada cambio de texto. Sin embargo, pierdes la capacidad de filtrar, formatear o validar la entrada en tiempo real.

Tipos de teclado y características de plataforma

TextInput admite varios tipos de teclado que adaptan la disposición al formato de entrada esperado. Elegir el tipo de teclado correcto mejora la experiencia del usuario y reduce errores de entrada en dispositivos móviles.

En iOS hay tipos adicionales: numbers-and-punctuation, twitter, web-search (con búsqueda por voz). En Android también está disponible visible-password (muestra la contraseña). Elegir el keyboardType correcto es un aspecto importante del UX de una aplicación móvil.

Las características de plataforma también incluyen autoCapitalize(capitalización automática de la primera palabra), autoCorrect (autocorrección), spellCheck (revisión ortográfica), textContentType (autocompletado en iOS). Estos props funcionan de manera diferente en cada plataforma y requieren pruebas.

Ejemplos prácticos con TextInput

Consideremos dos escenarios reales: un campo multilínea para entrada de mensajes y un campo con máscara para número de teléfono. Ambos usan TextInput con diferentes props para lograr el comportamiento deseado.

Ejemplo 1: Campo multilínea para mensajes

Para introducir texto largo (comentarios, descripciones), TextInput cambia al modo multilínea mediante la prop multiline. En este modo, el campo crece verticalmente y admite saltos de línea.

const MessageInput = ({ onSend }) => {
    const [text, setText] = useState('');

    return (
        <TextInput
            style={styles.input}
            multiline
            numberOfLines={4}
            placeholder="Write a message..."
            value={text}
            onChangeText={setText}
            textAlignVertical="top"
        />
    );
};

La prop multiline activa el modo multilínea, numberOfLines establece la altura inicial en líneas. textAlignVertical: 'top' alinea el texto en la parte superior (por defecto, en Android TextInput multilínea centra el texto verticalmente).

Ejemplo 2: Campo con formato de número de teléfono

Para introducir un número de teléfono, a menudo se requiere formato en tiempo real. Combinando onChangeText con expresiones regulares, puedes implementar una máscara de entrada.

const PhoneInput = () => {
    const [phone, setPhone] = useState('');

    const formatPhone = (text) => {
        const cleaned = text.replace(/\D/g, '');
        if (cleaned.length <= 11) {
            return cleaned.replace(
                /(\d{1})(\d{3})(\d{3})(\d{2})(\d{2})/,
                '+$1 ($2) $3 $4 $5'
            );
        }
        return cleaned;
    };

    return (
        <TextInput
            keyboardType="phone-pad"
            value={phone}
            onChangeText={(t) => setPhone(formatPhone(t))}
            placeholder="+7 (999) 123 45 67"
            maxLength={20}
        />
    );
};

La función formatPhone elimina todos los caracteres no numéricos y formatea el número en un formato internacional estándar. keyboardType: 'phone-pad' muestra el teclado telefónico. Este enfoque mejora la UX para la introducción de números de teléfono y previene errores de formato.