Pickers — BasePickerListBelow • shiny.fluent

For more details and examples visit the official docs. The R package cannot 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.

Usage

BasePickerListBelow(...)

TagPicker(...)

Arguments

...: Props to pass to the component. The allowed props are listed below in the Details section.

Value

Object with shiny.tag class suitable for use in the UI of a Shiny app.

Details

className string
ClassName for the picker.
componentRef IRefObject<IBasePicker<T>>
Optional callback to access the IBasePicker interface. Use this instead of ref for accessing the public methods and properties of the component.
createGenericItem (input: string, ValidationState: ValidationState) => ISuggestionModel<T> | T
Function that specifies how arbitrary text entered into the well is handled.
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
onGetMoreResults (filter: string, selectedItems?: T[]) => T[] | PromiseLike<T[]>
A callback that gets the rest of the results when a user clicks get more results.
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.
removeButtonAriaLabel string
Aria label for the "X" button in the selected item 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.
searchingText ((props: { input: string; }) => string) | string
The text to display while searching for more results in a limited suggestions list
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.
styles IStyleFunctionOrObject<IBasePickerStyleProps, IBasePickerStyles>
Call to provide customized styling that will layer on top of the variant rules.
theme ITheme
Theme provided by styled() function.
"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.
componentRef IRefObject<IPickerItem>
Optional callback to access the IPickerItem interface. Use this instead of ref for accessing the public methods and properties of the component.
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.
onRemoveItem () => void
Callback issued when the item is removed from the array of picked items.
removeButtonAriaLabel string
Aria-label for the picked item remove button.
selected boolean
Whether the picked item is selected or not.
className string
Optional className for the root element of the suggestion item.
componentRef IRefObject<ISuggestionsItem>
Optional callback to access the ISuggestionItem interface. Use this instead of ref for accessing the public methods and properties of the component.
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.
styles IStyleFunctionOrObject<ISuggestionsItemStyleProps, ISuggestionsItemStyles>
Call to provide customized styling that will layer on top of the variant rules.
suggestionModel ISuggestionModel<T>
Individual suggestion object containing its properties.
theme ITheme
Theme provided by High-Order Component.
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)
library(shiny.fluent)

makeScript <- function(js) {
  htmltools::htmlDependency(
    name = "TagPickerExample",
    version = "0", # Not used.
    src = c(href = ""), # Not used.
    head = paste0("<script>", js, "</script>")
  )
}

ui <- function(id) {
  ns <- NS(id)
  tagList(
    makeScript("
      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(ns("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(paste0(
        "function(selection) {",
        "  Shiny.setInputValue('", ns("selectedTags") ,"', JSON.stringify(selection));",
        "}"
      ))
    )
  )
}

server <- function(id) {
  moduleServer(id, function(input, output, session) {
    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 = ", ")
        )
      }
    })
  })
}

if (interactive()) {
  shinyApp(ui("app"), function(input, output) server("app"))
}