--- title: "Autocomplete suggestions for PDF form fields on Android | Nutrient" canonical_url: "https://www.nutrient.io/guides/android/forms/fill-form-fields/autocomplete-suggestions/" md_url: "https://www.nutrient.io/guides/android/forms/fill-form-fields/autocomplete-suggestions.md" last_updated: "2026-08-12T00:00:00.000Z" description: "Learn how to show a list of autocomplete suggestions when a user fills a text form field in Nutrient Android SDK." --- # Autocomplete suggestions for PDF form fields on Android Nutrient Android SDK can show a list of autocomplete suggestions while a user fills a text form field. When the user taps a suggestion, its value is written into the field. This is useful for fields with a known set of likely values — names, departments, site codes, or values you’ve already collected elsewhere in your app. Suggestions are supplied by your app through [`FormManager.OnTextFormElementSuggestionRequestListener`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.ui.special_mode.manager/-form-manager/-on-text-form-element-suggestion-request-listener/index.html), so you decide which fields offer suggestions and what those suggestions are. No UI or view subclassing is required. Autocomplete suggestions require Nutrient Android SDK 10.7.0 or later. ## Providing suggestions Register a listener on the [`PdfFragment`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.ui/-pdf-fragment/index.html) and return the suggestions for the given form element. Returning an empty list disables autocomplete for that field: ### KOTLIN ```kotlin class MyActivity : PdfActivity() { override fun onDocumentLoaded(document: PdfDocument) { super.onDocumentLoaded(document) pdfFragment?.addOnTextFormElementSuggestionRequestListener { formElement -> when (formElement.name) { "First Name" -> listOf("Alice", "Andrew", "Anna", "Bob", "Barbara") "Last Name" -> listOf("Anderson", "Brown", "Davis", "Smith", "Wilson") // Returning an empty list means this field has no suggestions. else -> emptyList() } } } } ``` ### JAVA ```java public class MyActivity extends PdfActivity { @Override public void onDocumentLoaded(@NonNull PdfDocument document) { super.onDocumentLoaded(document); PdfFragment fragment = getPdfFragment(); if (fragment == null) return; fragment.addOnTextFormElementSuggestionRequestListener(formElement -> { String name = formElement.getName(); if ("First Name".equals(name)) { return Arrays.asList("Alice", "Andrew", "Anna", "Bob", "Barbara"); } else if ("Last Name".equals(name)) { return Arrays.asList("Anderson", "Brown", "Davis", "Smith", "Wilson"); } // Returning an empty list means this field has no suggestions. return Collections.emptyList(); }); } } ``` Call [`removeOnTextFormElementSuggestionRequestListener`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.ui.special_mode.manager/-form-manager/remove-on-text-form-element-suggestion-request-listener.html) when you no longer want to provide suggestions. The example above matches on [`FormElement#getName`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.forms/-form-element/get-name.html), but you can use any property of the supplied [`TextFormElement`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.forms/-text-form-element/index.html) to decide what to return — for example, its [`inputFormat`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.forms/-text-form-element/get-input-format.html) or the page it lives on. ## Controlling when suggestions appear By default, the suggestion list is shown as soon as the user starts editing the field. Override `shouldShowSuggestionsImmediately` and return `false` to show it only after the user taps the field again or begins typing: ### KOTLIN ```kotlin pdfFragment?.addOnTextFormElementSuggestionRequestListener( object : FormManager.OnTextFormElementSuggestionRequestListener { override fun onTextFormElementGetSuggestions(formElement: TextFormElement): List = suggestionsFor(formElement) override fun shouldShowSuggestionsImmediately(formElement: TextFormElement): Boolean { // Only show the list once the user has typed something. return false } } ) ``` ### JAVA ```java fragment.addOnTextFormElementSuggestionRequestListener( new FormManager.OnTextFormElementSuggestionRequestListener() { @NonNull @Override public List onTextFormElementGetSuggestions(@NonNull TextFormElement formElement) { return suggestionsFor(formElement); } @Override public boolean shouldShowSuggestionsImmediately(@NonNull TextFormElement formElement) { // Only show the list once the user has typed something. return false; } } ); ``` ## How suggestions are matched - Suggestions are requested once: when the field enters editing mode. The returned list is then filtered locally as the user types, so the callback isn’t invoked on every keystroke. - Filtering is a case-insensitive *substring* match against the current field contents — typing `an` matches both `Anna` and `Alexander`. The list is shown in the order you return it, so return it presorted if order matters to your users. - If nothing matches the current text, the list is hidden. - Tapping a suggestion replaces the entire contents of the field with the selected value and dismisses the list. ## Styling The suggestion list picks up the `pspdf__suggestionListBackgroundColor` and `pspdf__suggestionListTextColor` attributes of your `pspdf__formSelectionStyle`. See the [form selection section](https://www.nutrient.io/guides/android/customizing-the-interface/appearance-styling.md) of the appearance and styling guide for the full attribute list. ## Things to keep in mind - The callback is invoked on the main thread and has to return synchronously. If your suggestions come from a database or a network call, load them before the user reaches the field and return the cached values here. - If you register more than one listener, the first one to return a non-empty list wins. For `shouldShowSuggestionsImmediately`, the list is shown immediately if any registered listener returns `true`. - Suggestions are only offered for text form fields. They’re also suppressed on fields whose [`inputFormat`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.forms/-text-form-element/get-input-format.html) is a date or a time while the date and time pickers are enabled, so that the picker and the suggestion list don’t compete for the same space. - Suggestions are supported by [`PdfFragment`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.ui/-pdf-fragment/index.html) and [`PdfActivity`](https://www.nutrient.io/api/android/nutrient/com.pspdfkit.ui/-pdf-activity/index.html). They aren’t available in the Jetpack Compose SDK flavor. ## Example For a complete, runnable example, see `FormTextFieldSuggestionExample` in our [Catalog app](https://www.nutrient.io/guides/android/prebuilt-solutions/example-projects.md). --- ## Related pages - [Attach files to PDF form fields on Android](/guides/android/forms/fill-form-fields/attach-a-file.md) - [Detecting user clicks in PDF form elements on Android](/guides/android/forms/fill-form-fields/detect-clicks.md) - [Detect user input in Android PDF forms](/guides/android/forms/fill-form-fields/detect-user-input.md) - [Undo and redo for PDF forms on Android](/guides/android/forms/fill-form-fields/undo-and-redo.md) - [Form field support in our Android PDF viewer](/guides/android/forms/fill-form-fields/using-the-ui.md) - [Fill PDF form fields programmatically on Android](/guides/android/forms/form-filling.md)