Skip to main content

Combobox

    The Combobox component allows users to choose one option from a collapsed dropdown, filter options by typing, or create a new one.

    When to use​

    • To let users choose one option from a list or enter a value that isn't already in the list.
    • To let users type to filter a long list of options.
    • The list of options is long, and users probably know what they're looking for.

    When not to use​

    • Users must choose only from predefined options. Use Select instead.
    • Users should choose multiple options. Use Select with the multiple prop or Checkbox.
    • There are only two options. Use Radio or Switch for binary choices.
    • Users should enter free text with no suggestions. Use TextInput instead.

    Create custom values​

    Users can create a new value in the following ways:

    • Select the create option at the end of the list.
    • Press Enter while the create option is highlighted.
    • Move focus out of the Combobox after typing text.

    Moving focus out of Combobox also commits the typed text. If the text matches an option, regardless of case, the Combobox selects that option. Otherwise, it creates a new value. In a controlled Combobox, the created value is only applied if onCreateOption sets it.

    The create option never appears for empty or whitespace-only input, or when the text matches an existing option. The comparison ignores case.

    In an uncontrolled Combobox, the value is applied and onChange is called before onCreateOption. In a controlled Combobox, onChange isn't called for the created value.

    Values not in the list​

    The Combobox accepts a value that doesn't match any option and shows it as the selected value. This lets your app show previously saved data even if the list of options has changed.

    Content guidelines​

    Add a label that describes the purpose of the field. Keep it descriptive but short (one to two words).

    • Do: Programming language
    • Don't: Select or enter a programming language

    Placeholder​

    The default placeholder is "Search or create". It works for most use cases. You may want to customize the placeholder for certain use cases. If you do, use this pattern:

    • Select + [subject] or Select or enter + [subject].
    • Omit unnecessary articles (a, an, the).
    • Don't add periods, ellipses, or exclamation marks.

    Examples:

    • Select language
    • Select or enter language
    Use a hint for essential information

    Don't use the placeholder for information that users need to complete the task. The placeholder disappears as soon as users start typing.

    Hint (optional)​

    Use the hint (FormFieldMessages component) for information users need to avoid errors or work efficiently. Always provide any error messages here too.

    Example: New languages can be added using any alphabet.

    • Keep the hint short.
    • Add periods after sentences.

    Option labels​

    • Use sentence case.
    • Keep labels short so users can scan the list.
    • Order options in a logical way, for example alphabetically, or group them with Combobox.Group.
    • If you use content other than plain text in an option, provide a textValue so filtering works.

    Create label​

    The create option produces the label "Create" followed by the entered text. Don't change the action word "Create" with the createLabel prop unless "create" doesn't fit the use case. For example, the action verb "Use" is a better fit if the value is applied without being saved.

    Still have questions?
    Find answers in the Dynatrace Community