A combo box (ComboBox) combines a text field and a drop-down menu, giving people a way to select an option from a list or enter their own choice.

For more details and examples visit the official docs. The R package can not handle each and every case, so for advanced use cases you need to work using the original docs to achieve the desired result.

ComboBox(...)

VirtualizedComboBox(...)

ComboBox.shinyInput(inputId, ..., value = defaultValue)

updateComboBox.shinyInput(
  session = shiny::getDefaultReactiveDomain(),
  inputId,
  ...
)

Arguments

allowFreeform

boolean
Whether the ComboBox is free form, meaning that the user input is not bound to provided options. Defaults to false.

ariaDescribedBy

string
Optional prop to add a string id that can be referenced inside the aria-describedby attribute

autoComplete

'on' | 'off'
Whether the ComboBox auto completes. As the user is inputing text, it will be suggested potential matches from the list of options. If the combo box is expanded, this will also scroll to the suggested option, and give it a selected style.

autofill

IAutofillProps
The AutofillProps to be passed into the Autofill component inside combobox

buttonIconProps

IIconProps
The IconProps to use for the button aspect of the combobox

caretDownButtonStyles

Partial<IButtonStyles>
Styles for the caret down button.

comboBoxOptionStyles

Partial<IComboBoxOptionStyles>
Default styles that should be applied to ComboBox options, in case an option does not come with user-defined custom styles

componentRef

IRefObject<IComboBox>
Optional callback to access the IComboBox interface. Use this instead of ref for accessing the public methods and properties of the component.

dropdownMaxWidth

number
Custom max width for dropdown

dropdownWidth

number
Custom width for dropdown (unless useComboBoxAsMenuWidth is undefined or false)

getClassNames

(theme: ITheme, isOpen: boolean, disabled: boolean, required: boolean, focused: boolean, allowFreeForm: boolean, hasErrorMessage: boolean, className?: string) => IComboBoxClassNames
Custom function for providing the classNames for the ComboBox. Can be used to provide all styles for the component instead of applying them on top of the default styles.

iconButtonProps

IButtonProps
Optional iconButton props on combo box

isButtonAriaHidden

boolean
Sets the 'aria-hidden' attribute on the ComboBox's button element instructing screen readers how to handle the element. This element is hidden by default because all functionality is handled by the input element and the arrow button is only meant to be decorative.

keytipProps

IKeytipProps
Optional keytip for this combo box

multiSelectDelimiter

string
When multiple items are selected, this will be used to separate values in the combobox input.

onChange

(event: React.FormEvent<IComboBox>, option?: IComboBoxOption, index?: number, value?: string) => void
Callback issued when either: 1) the selected option changes 2) a manually edited value is submitted. In this case there may not be a matched option if allowFreeform is also true (and hence only value would be true, the other parameter would be null in this case)

onItemClick

(event: React.FormEvent<IComboBox>, option?: IComboBoxOption, index?: number) => void
Callback issued when a ComboBox item is clicked.

onMenuDismiss

() => void
Function that gets invoked before the menu gets dismissed

onMenuDismissed

() => void
Function that gets invoked when the ComboBox menu is dismissed

onMenuOpen

() => void
Function that gets invoked when the ComboBox menu is launched

onPendingValueChanged

(option?: IComboBoxOption, index?: number, value?: string) => void
Callback issued when the user changes the pending value in ComboBox. This will be called any time the component is updated and there is a current pending value. Option, index, and value will all be undefined if no change has taken place and the previously entered pending value is still valid.

onRenderLabel

IRenderFunction<IOnRenderComboBoxLabelProps>
Custom render function for the label text.

onRenderLowerContent

IRenderFunction<IComboBoxProps>
Add additional content below the callout list.

onRenderUpperContent

IRenderFunction<IComboBoxProps>
Add additional content above the callout list.

onResolveOptions

(options: IComboBoxOption[]) => IComboBoxOption[] | PromiseLike<IComboBoxOption[]>
Callback issued when the options should be resolved, if they have been updated or if they need to be passed in the first time

onScrollToItem

(itemIndex: number) => void
Callback issued when the ComboBox requests the list to scroll to a specific element

options

IComboBoxOption[]
Collection of options for this ComboBox

persistMenu

boolean
Menu will not be created or destroyed when opened or closed, instead it will be hidden. This will improve perf of the menu opening but could potentially impact overall perf by having more elements in the dom. Should only be used when perf is important. Note: This may increase the amount of time it takes for the comboBox itself to mount.

scrollSelectedToTop

boolean
When options are scrollable the selected option is positioned at the top of the callout when it is opened (unless it has reached the end of the scrollbar).

shouldRestoreFocus

boolean
When specified, determines whether the callout (the menu which drops down) should restore the focus after being dismissed or not. If false, then the menu will not try to set focus to whichever element had focus before the menu was opened.

styles

Partial<IComboBoxStyles>
Custom styles for this component

text

string
Value to show in the input, does not have to map to a combobox option

theme

ITheme
Theme provided by HOC.

useComboBoxAsMenuWidth

boolean
Whether to use the ComboBoxes width as the menu's width

multiselectAccessibleText

string
Accessible text for label when combobox is multiselected.

props

IComboBoxProps
Props to render the combobox.

Best practices

Layout

  • Use a combo box when there are multiple choices that can be collapsed under one title, when the list of items is long, or when space is constrained.

Content

  • Use single words or shortened statements as options.

  • Don't use punctuation at the end of options.

Examples

library(shiny.fluent)

if (interactive()) {
  options <- list(
    list(key = "A", text = "Option A"),
    list(key = "B", text = "Option B"),
    list(key = "C", text = "Option C")
  )

  shinyApp(
    ui = div(
      ComboBox.shinyInput("combo", value = list(text = "some text"),
        options = options, allowFreeform = TRUE
      ),
      textOutput("comboValue")
    ),
    server = function(input, output) {
      output$comboValue <- renderText({
        sprintf("Value: %s", input$combo$text)
      })
    }
  )
}