TextInputLayout: cos'è, Material Design e configurazione in Android

Cos'è TextInputLayout in Android

TextInputLayout è un ViewGroup del pacchetto com.google.android.material.textfield che estende LinearLayout e contiene un EditText al suo interno. Il componente fa parte della libreria Material Components per Android, a partire dalla versione 1.0.0. L'obiettivo principale di TextInputLayout è fornire un'implementazione pronta all'uso dei campi di testo Material Design con il minimo sforzo da parte dello sviluppatore.

A differenza di un EditText standard, TextInputLayout gestisce l'animazione dell'etichetta fluttuante, che viene impostata tramite l'attributo android:hint dell'EditText interno. Quando il campo è vuoto, l'etichetta viene visualizzata all'interno del campo come un suggerimento normale. Non appena l'utente inizia a digitare, l'etichetta si sposta animatamente nella parte superiore del campo, riducendo le dimensioni. Secondo le Material Design Guidelines (2025), questa animazione migliora la percezione del modulo perché l'utente vede sempre il nome del campo, anche dopo aver inserito i dati.

Architetturalmente, TextInputLayout implementa il pattern decoratore: intercetta gli eventi di EditText, gestisce la visualizzazione di elementi aggiuntivi (etichetta, errore, icone, contatore) e coordina la loro animazione. L'EditText interno è accessibile tramite il metodo getEditText() e può essere configurato con attributi standard, inclusi inputType, maxLines e hint.

<!-- Basic TextInputLayout markup -->
@+id/tilEmail
android:layout_width="match_parent"
android:layout_height="wrap_content">

    @+id/etEmail
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:hint="Email"
    android:inputType="textEmailAddress" />

</com.google.android.material.textfield.TextInputLayout>

Etichetta fluttuante e sua configurazione

L'etichetta fluttuante (floating label) è la caratteristica principale di TextInputLayout. Quando il campo è vuoto, il testo di android:hint viene visualizzato all'interno di EditText come un segnaposto normale. Quando il campo riceve il focus o viene inserito del testo, l'etichetta si solleva nella parte superiore di TextInputLayout, riducendo la dimensione del carattere e cambiando colore. Questo comportamento risolve il problema del suggerimento che diventa invisibile dopo che l'utente inizia a digitare.

La configurazione dell'etichetta fluttuante avviene tramite gli attributi di TextInputLayout: app:hintEnabled determina se l'etichetta fluttuante è abilitata (default true), app:hintAnimationEnabled abilita o disabilita l'animazione di transizione, app:expandedHintEnabled permette di visualizzare l'etichetta anche quando il campo è vuoto e non focalizzato. Il colore dell'etichetta in diversi stati è gestito tramite gli stili colorPrimary e colorControlHighlight.

Secondo il Google Material Components Team (2025), l'etichetta fluttuante è particolarmente utile nei moduli con molti campi, dove l'utente potrebbe dimenticare il nome del campo dopo aver iniziato a digitare. A differenza di un semplice android:hint che scompare durante l'inserimento, l'etichetta fluttuante rimane sempre visibile, fornendo contesto per ogni campo.

Visualizzazione degli errori in TextInputLayout

TextInputLayout fornisce un sistema integrato di visualizzazione degli errori visivamente integrato con il campo di input. Quando si imposta un errore tramite il metodo setError, il componente evidenzia il campo (il colore della linea o del contorno diventa rosso) e visualizza il testo di errore sotto il campo. Questo elimina la necessità di un TextView separato per i messaggi di errore.

La gestione della visualizzazione degli errori avviene tramite i metodi setError(CharSequence) e setErrorEnabled(boolean). Quando setError viene chiamato con del testo, l'errore viene visualizzato immediatamente; quando setError(null) viene chiamato, viene nascosto. TextInputLayout supporta anche un'icona di errore personalizzata tramite l'attributo app:errorIconDrawable e la gestione del colore dell'errore tramite app:errorTextColor.

Secondo le Material Design Guidelines (2025), i messaggi di errore dovrebbero essere specifici e utili: invece di “Input non valido” scrivi “L'email deve contenere @”. La visualizzazione dell'errore dovrebbe avvenire dopo il completamento dell'inserimento (alla perdita del focus o dopo l'invio del modulo), non in tempo reale — questo riduce lo stress dell'utente durante la compilazione dei moduli.

// Configurazione programmatica degli errori
textInputLayout.error = "Password min 8 chars"

// Nascondimento degli errori
textInputLayout.error = null

// Controllo e impostazione degli errori di validazione
if (email.isNullOrBlank()) {
    tilEmail.error = "Email is required"
} else {
    tilEmail.error = null
}

Icone e azioni in TextInputLayout

TextInputLayout supporta la visualizzazione di icone sia all'inizio del campo (icona di inizio) che alla fine (icona di fine). Le icone possono svolgere varie funzioni: alternare la visibilità della password, cancellare il campo, azioni personalizzate. Ogni tipo di icona è controllato da un attributo separato e può essere sostituito con uno personalizzato tramite l'attributo app:startIconDrawable o app:endIconDrawable.

La modalità icona di fine è impostata tramite l'attributo app:endIconMode, che può assumere i seguenti valori: password_toggle — alternanza della visibilità della password, clear_text — cancellazione del campo, dropdown_menu — freccia per un elenco a discesa, custom — icona personalizzata. Per password_toggle, TextInputLayout gestisce automaticamente l'alternanza di inputType tra textPassword e textVisiblePassword, e anima anche l'icona dell'occhio.

• password_toggle — icona dell'occhio per mostrare/nascondere la password, animazione integrata.
• clear_text — icona a croce per cancellare il campo, appare in presenza di testo.
• dropdown_menu — freccia per Exposed Dropdown Menu (Material Design 3).
• custom — qualsiasi icona personalizzata con un gestore tramite setEndIconOnClickListener.

<!-- TextInputLayout with password toggle icon -->
@+id/tilPassword
android:layout_width="match_parent"
app:endIconMode="password_toggle"
app:passwordToggleTint="@color/primary">

    @+id/etPassword
    android:inputType="textPassword" />

</com.google.android.material.textfield.TextInputLayout>

Stili di TextInputLayout: FilledBox e OutlinedBox

Material Components per Android fornisce due stili principali per TextInputLayout: FilledBox (riempito) e OutlinedBox (con contorno). Lo stile FilledBox ha uno sfondo riempito di colore e una linea sotto il campo che cambia colore al focus. Lo stile OutlinedBox ha uno sfondo trasparente e un contorno attorno all'intero campo, creando confini più chiari e adattandosi meglio ai moduli con molti campi.

La scelta dello stile dipende dal design dell'app: FilledBox è consigliato per i moduli utilizzati frequentemente poiché attira meno attenzione sui singoli campi. OutlinedBox è preferibile per moduli brevi (login, registrazione) dove ogni campo deve essere chiaramente contrassegnato. Lo stile viene impostato tramite l'attributo style in XML o tramite il tema dell'app.

Material Design 3 (M3) ha introdotto stili aggiornati per TextInputLayout con tipografia migliorata, nuovi token di colore e supporto per i colori dinamici di Material You. In M3, OutlinedBox è diventato lo stile consigliato predefinito e FilledBox ha adattato il suo padding e il raggio del bordo per soddisfare la nuova specifica.

Esempi di codice con TextInputLayout

Un esempio completo di implementazione di un modulo di registrazione con TextInputLayout, che include la validazione di email e password, la visualizzazione degli errori e l'icona di mostra password. Quando si preme il pulsante di registrazione, tutti i campi vengono controllati e vengono visualizzati i corrispondenti messaggi di errore.

Layout XML del modulo di registrazione

@+id/tilName
app:boxBackgroundMode="outlined">
    @+id/etName
    android:hint="Name" />
</...TextInputLayout>

@+id/tilRegEmail
app:boxBackgroundMode="outlined">
    @+id/etRegEmail
    android:hint="Email"
    android:inputType="textEmailAddress" />
</...TextInputLayout>

@+id/tilRegPassword
app:boxBackgroundMode="outlined"
app:endIconMode="password_toggle">
    @+id/etRegPassword
    android:hint="Password"
    android:inputType="textPassword" />
</...TextInputLayout>

Validazione del modulo in Kotlin

private fun validateForm(): Boolean {
    var isValid = true

    if (etName.text.isNullOrBlank()) {
        tilName.error = "Enter your name"
        isValid = false
    } else {
        tilName.error = null
    }

    val email = etRegEmail.text.toString()
    if (!Patterns.EMAIL_ADDRESS.matcher(email).matches()) {
        tilRegEmail.error = "Invalid email format"
        isValid = false
    } else {
        tilRegEmail.error = null
    }

    val password = etRegPassword.text.toString()
    if (password.length < 8) {
        tilRegPassword.error = "Password min 8 chars"
        isValid = false
    } else {
        tilRegPassword.error = null
    }

    return isValid
}