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.

Pickers are used to select one or more items, such as tags or files, from a large list.

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.

BasePickerListBelow(...)

TagPicker(...)

Arguments

defaultSelectedItems

T[]
Initial items that have already been selected and should appear in the people picker.

disabled

boolean
Flag for disabling the picker.

enableSelectedSuggestionAlert

boolean
Adds an additional alert for the currently selected suggestion. This prop should be set to true for IE11 and below, as it enables proper screen reader behavior for each suggestion (since aria-activedescendant does not work with IE11). It should not be set for modern browsers (Edge, Chrome).

getTextFromItem

(item: T, currentValue?: string) => string
A callback to get text from an item. Used to autofill text in the pickers.

inputProps

IInputProps
AutoFill input native props

itemLimit

number
Restrict the amount of selectable items.

onBlur

React.FocusEventHandler<HTMLInputElement | Autofill>
A callback for when the user moves the focus away from the picker

onChange

(items?: T[]) => void
A callback for when the selected list of items changes.

onDismiss

(ev?: any, selectedItem?: T) => boolean | void
A callback to override the default behavior of adding the selected suggestion on dismiss. If it returns true or nothing, the selected item will be added on dismiss. If false, the selected item will not be added on dismiss.

onEmptyInputFocus

(selectedItems?: T[]) => T[] | PromiseLike<T[]>
A callback for what should happen when a user clicks within the input area.

onEmptyResolveSuggestions

(selectedItems?: T[]) => T[] | PromiseLike<T[]>
A callback for what should happen when suggestions are shown without input provided. Returns the already selected items so the resolver can filter them out. If used in conjunction with resolveDelay this will only kick off after the delay throttle.

onFocus

React.FocusEventHandler<HTMLInputElement | Autofill>
A callback for when the user put focus on the picker

onInputChange

(input: string) => string
A callback used to modify the input string.

onItemSelected

(selectedItem?: T) => T | PromiseLike<T> | null
A callback to process a selection after the user selects something from the picker. If the callback returns null, the item will not be added to the picker.

onRemoveSuggestion

(item: T) => void
A callback for when an item is removed from the suggestion list

onRenderItem

(props: IPickerItemProps<T>) => JSX.Element
Function that specifies how the selected item will appear.

onRenderSuggestionsItem

(props: T, itemProps: ISuggestionItemProps<T>) => JSX.Element
Function that specifies how an individual suggestion item will appear.

onResolveSuggestions

(filter: string, selectedItems?: T[]) => T[] | PromiseLike<T[]>
A callback for what should happen when a person types text into the input. Returns the already selected items so the resolver can filter them out. If used in conjunction with resolveDelay this will only kick off after the delay throttle.

onValidateInput

(input: string) => ValidationState
A function used to validate if raw text entered into the well can be added into the selected items list

pickerCalloutProps

ICalloutProps
The properties that will get passed to the Callout component.

pickerSuggestionsProps

IBasePickerSuggestionsProps
The properties that will get passed to the Suggestions component.

resolveDelay

number
The delay time in ms before resolving suggestions, which is kicked off when input has been changed. e.g. If a second input change happens within the resolveDelay time, the timer will start over. Only until after the timer completes will onResolveSuggestions be called.

selectedItems

T[]
The items that the base picker should currently display as selected. If this is provided then the picker will act as a controlled component.

"aria-label"

string
Screen reader label to apply to an input element.

defaultVisibleValue

string
The default value to be visible when the autofill first created. This is different than placeholder text because the placeholder text will disappear and re-appear. This text persists until deleted or changed.

index

number
Index number of the item in the array of picked items.

item

T
The item of Type T (Persona, Tag, or any other custom item provided).

key

string | number
Unique key for each picked item.

onItemChange

(item: T, index: number) => void
Internal Use only, gives a callback to the renderer to call when an item has changed. This allows the base picker to keep track of changes in the items.

selected

boolean
Whether the picked item is selected or not.

id

string
Unique id of the suggested item.

isSelectedOverride

boolean
An override for the 'selected' property of the SuggestionModel.

onClick

(ev: React.MouseEvent<HTMLButtonElement>) => void
Callback for when the user clicks on the suggestion.

onRemoveItem

(ev: React.MouseEvent<HTMLButtonElement>) => void
Callback for when the item is removed from the array of suggested items.

removeButtonAriaLabel

string
The ARIA label for the button to remove the suggestion from the list.

RenderSuggestion

(item: T, suggestionItemProps: ISuggestionItemProps<T>) => JSX.Element
Optional renderer to override the default one for each type of picker.

showRemoveButton

boolean
Whether the remove button should be rendered or not.

suggestionModel

ISuggestionModel<T>
Individual suggestion object containing its properties.

className

string
The CSS className of the suggestions root.

componentRef

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

createGenericItem

() => void
The callback that should be called when the user attempts to use the input text as as item

forceResolveText

string
The text that appears indicating to the use to force resolve the input

isLoading

boolean
Used to indicate whether or not the suggestions are loading.

isMostRecentlyUsedVisible

boolean
Indicates if a short list of recent suggestions should be shown.

isResultsFooterVisible

boolean
Indicates if the text in resultsFooter or resultsFooterFull should be shown at the end of the suggestion list.

isSearching

boolean
Used to indicate whether or not the component is searching for more results.

loadingText

string
The text to display while the results are loading.

moreSuggestionsAvailable

boolean
Used to indicate whether or not the user can request more suggestions. Dictates whether or not the searchForMore button is displayed.

mostRecentlyUsedHeaderText

string
The text that should appear at the top of the most recently used box.

noResultsFoundText

string
The text that should appear if no results are found when searching.

onGetMoreResults

() => void
The callback that should be called when the user attempts to get more results

onRenderNoResultFound

IRenderFunction<void>
How the "no result found" should look in the suggestion list.

onRenderSuggestion

(props: T, suggestionItemProps: ISuggestionItemProps<T>) => JSX.Element
How the suggestion should look in the suggestion list.

onSuggestionClick

(ev?: React.MouseEvent<HTMLElement>, item?: any, index?: number) => void
What should occur when a suggestion is clicked

onSuggestionRemove

(ev?: React.MouseEvent<HTMLElement>, item?: T | IPersonaProps, index?: number) => void
Function to fire when one of the optional remove buttons on a suggestion is clicked.

TODO (adjective-object) remove IPersonaprops before the next major version bump

refocusSuggestions

(keyCode: KeyCodes) => void
A function that resets focus to the expected item in the suggestion list

removeSuggestionAriaLabel

string
An ARIA label to use for the buttons to remove individual suggestions.

resultsFooter

(props: ISuggestionsProps<T>) => JSX.Element
A renderer that adds an element at the end of the suggestions list it has fewer items than resultsMaximumNumber.

resultsFooterFull

(props: ISuggestionsProps<T>) => JSX.Element
A renderer that adds an element at the end of the suggestions list it has more items than resultsMaximumNumber.

resultsMaximumNumber

number
Maximum number of suggestions to show in the full suggestion list.

searchErrorText

string
The text that should appear if there is a search error.

searchForMoreText

string
The text that appears indicating to the user that they can search for more results.

searchingText

string
The text to display while searching for more results in a limited suggestions list.

showForceResolve

() => boolean
The callback that should be called to see if the force resolve command should be shown

showRemoveButtons

boolean
Indicates whether to show a button with each suggestion to remove that suggestion.

styles

IStyleFunctionOrObject<any, any>
Call to provide customized styling that will layer on top of the variant rules.

suggestions

ISuggestionModel<T>[]
The list of Suggestions that will be displayed

suggestionsAvailableAlertText

string
Screen reader message to read when there are suggestions available.

suggestionsClassName

string
The CSS className of the suggestions list

suggestionsContainerAriaLabel

string
An ARIA label for the container that is the parent of the suggestions.

suggestionsHeaderText

string
The text that appears at the top of the suggestions list.

suggestionsItemClassName

string
The className of the suggestion item.

suggestionsListId

string
The string that will be used as the suggestionsListId. Will be used by the BasePicker to keep track of the list for aria.

theme

ITheme
Theme provided by High-Order Component.

Best practices

Layout

  • Use a picker to quickly search for a few tags or files.

  • Use a picker to manage a group of tags or files.

Examples

library(shiny.fluent)

if (interactive()) {
  shinyApp(
    ui = tagList(
      tags$script(HTML("
        testTags = [
          'black',
          'blue',
          'brown',
          'cyan',
          'green',
          'magenta',
          'mauve',
          'orange',
          'pink',
          'purple',
          'red',
          'rose',
          'violet',
          'white',
          'yellow',
        ].map(item => ({ key: item, name: item }));

        function listContainsTagList(tag, tagList) {
          if (!tagList || !tagList.length || tagList.length === 0) {
            return false;
          }
          return tagList.some(compareTag => compareTag.key === tag.key);
        };

        function filterSuggestedTags(filterText, tagList) {
          return filterText
            ? testTags.filter(
                tag => tag.name.toLowerCase().indexOf(filterText.toLowerCase()) === 0 && !listContainsTagList(tag, tagList),
              )
            : [];
        };
      ")),
      textOutput("selectedTags"),
      TagPicker(
        onResolveSuggestions = JS("filterSuggestedTags"),
        onEmptyInputFocus = JS("function(tagList) { return testTags.filter(tag => !listContainsTagList(tag, tagList)); }"),
        getTextFromItem = JS("function(item) { return item.text }"),
        pickerSuggestionsProps = list(suggestionsHeaderText = 'Suggested tags', noResultsFoundText = 'No color tags found'),
        itemLimit = 2,
        onChange = JS("function(selection) { Shiny.setInputValue('selectedTags', JSON.stringify(selection)) }")
      )
    ),
    server = function(input, output) {
      output$selectedTags <- renderText({
        if (is.null(input$selectedTags)) {
          "Select up to 2 colors below:"
        } else {
          paste("You have selected:", paste(jsonlite::fromJSON(input$selectedTags)$name, collapse = ", "))
        }
      })
    }
  )
}