AutocompleteInput#

Download this notebook from GitHub (right-click to download).

import panel as pn
import panel_material_ui as pmui

pn.extension()

The AutocompleteInput widget enhances a standard text input by providing a panel of suggested options as you type. This widget is ideal in two main scenarios:


    

  • When the input must be selected from a predefined set of valid values, such as a location field requiring a recognized location name.
    • 

  • When any value is allowed, but offering suggestions—such as previous searches or similar terms—can help users save time and reduce errors.
    • 



AutocompleteInput belongs to the family of single-value, option-selection widgets, which also includes RadioBoxGroup, Select, and DiscreteSlider. These widgets share a consistent API for ease of use.


The panel-material-ui Autocomplete is built on top of the Material UI Autocomplete, providing a modern and flexible user experience.




Parameters#


For more details on customization, see the customization guides.




Core#


    

  • disabled (bool): If True, the widget is not editable.
    • 

  • case_sensitive (bool, default=True): Controls whether matching is case sensitive.
    • 

  • min_characters (int, default=2): Minimum number of characters required before suggestions appear.
    • 

  • options (list or dict): The set of selectable options, provided as a list or dictionary.
    • 

  • restrict (bool, default=True): If False, users can enter values not present in the options list.
    • 

  • search_strategy (str): Determines how suggestions are matched. “starts_with” (default) matches from the beginning; “includes” matches any substring.
    • 

  • value (str): The selected value, updated when the user presses . If restrict=True, must be one of the options.
    • 

  • value_input (str): The current input value, updated on every key press.
    • 







Display#


    

  • label (str): The widget’s title.
    • 

  • placeholder (str): Text shown when no value is selected.
    • 







Styling#


    

  • color (str): Choose from “default” (default), “primary”, “secondary”, “error”, “info”, “success”, “warning”, “light”, “dark”, or “danger”.
    • 

  • sx (dict): Component-level styling options.
    • 

  • theme_config (dict): Theming options.
    • 

  • variant (str): Choose from “filled”, “outlined” (default), or “standard”.
    • 







Aliases#


For compatibility with Panel, some parameters have aliases:


    

  • name: Alias for label
    • 











Basic Usage#


In its simplest form, AutocompleteInput lets users select a value from a predefined list of options.


autocomplete = pmui.AutocompleteInput(
    label='Autocomplete Input', options=['Biology', 'Chemistry', 'Physics'], color='warning'
)

pmui.Row(autocomplete, height=125)







            
            
The available options appear as you start typing parts of the options in the list like “Bi”, “Ch” or “Ph”.


    

  • The value parameter shows the currently selected option (updated when you press  or select an option).
    • 

  • The value_input parameter reflects the text currently entered or highlighted in the input field.
    • 



pmui.Row(autocomplete.param.value, autocomplete.param.value_input)







            
            
Try typing “Ph” in the AutocompleteInput above, then select “Physics”. Notice how the value parameter updates only when you make a selection, while value_input reflects your current input.






Using a Dictionary for Options#


You can also provide the options parameter as a dictionary. The keys will be displayed as labels in the dropdown menu, while the values are the actual option values.


options_dict = pmui.AutocompleteInput(label='Autocomplete', options={'Biology': 1, 'Chemistry': 2, 'Physics': 3})

pmui.Row(options_dict, height=125)







            
            
Notice that the label is shown when no value is selected.


Let’s observe how the value and value_input parameters change as you type and select a value.


pmui.Row(options_dict.param.value, options_dict.param.value_input)







            
            




Placeholder#


You can set a placeholder to display helpful guidance in the input field when no value is selected.


pmui.AutocompleteInput(
    label='Autocomplete Input', placeholder="Enter a value", options=['Biology', 'Chemistry', 'Physics'],
)







            
            




Case Sensitivity#


Control whether the filter is case sensitive using the case_sensitive parameter.


case_insensitive = pmui.AutocompleteInput(
    label='Autocomplete Input', case_sensitive=False, options=['Biology', 'Chemistry', 'Physics'],
)

pmui.Row(case_insensitive, height=125)







            
            
Now, the option “Physics” will appear regardless of whether you type “ph”, “pH”, “Ph”, or “PH”.






Minimum Characters Required#


You can adjust the minimum number of characters a user must type before suggestions appear using the min_characters parameter.


min_characters = pmui.AutocompleteInput(
    label='Autocomplete Input', min_characters=0, options=['Biology', 'Chemistry', 'Physics'],
)

pmui.Row(min_characters, height=200)







            
            




Search Strategy#


By default, search_strategy is set to “starts_with”. You can change it to “includes” to match any part of the option string.


Try entering “aa”, “bb”, “cc”, or “zz” to see how the matching works.


search_strategy = pmui.AutocompleteInput(
    label='Autocomplete Input', search_strategy="includes", options=['aabbcc', 'bbaacc', 'zzaabb'],
)

pmui.Row(search_strategy, height=200)







            
            
Try entering “aa”, “bb”, “cc” or “zz”.






Restrict Input#


Control whether users can enter values not present in the options list using the restrict parameter.


If restrict=False, the AutocompleteInput will allow any input, not just the provided options. This is useful when you want to suggest completions but not limit user input.


not_restricted = autocomplete.clone(value='Mathematics', restrict=False, options=['Biology', 'Chemistry', 'Physics'])

pmui.Row(not_restricted, height=125)







            
            
Let’s observe how the value parameter updates as you enter custom values.


pn.pane.Str(not_restricted.param.value)







            
            




Disabled and Loading States#


Like other widgets, AutocompleteInput can be disabled and/or show a loading indicator.


pmui.AutocompleteInput(
    label='Autocomplete Input', disabled=True, loading=True, options=['Biology', 'Chemistry', 'Physics'],
)







            
            




Color Options#


You can set the color parameter to visually distinguish the AutocompleteInput when active. Available options include “default”, “primary”, “secondary”, “error”, “info”, “success”, “warning”, “light”, “dark”, and “danger”:


pmui.FlexBox(
    *[pmui.AutocompleteInput(label=color, color=color) for color in pmui.AutocompleteInput.param.color.objects]
)







            
            




Variant#


The variant parameter controls the visual style of the input. Choose from “filled”, “outlined” (default), or “standard”:


pmui.FlexBox(
    pmui.AutocompleteInput(label='Filled', variant="filled"),
    pmui.AutocompleteInput(label='Outlined', variant="outlined"),
    pmui.AutocompleteInput(label='Standard', variant="standard"),
)







            
            




API Reference#




Parameters#


pmui.AutocompleteInput(
    label='Autocomplete Input', options=['Biology', 'Chemistry', 'Physics'],
).api(jslink=True)







            
            






References#


Discover more on using widgets to add interactivity to your applications in the how-to guides on interactivity.


Learn how to set up callbacks and (JS-)links between parameters or how to use them as part of declarative UIs with Param.


See also the Material UI Autocomplete Reference and API documentation for inspiration.




Download this notebook from GitHub (right-click to download).