Package 'shiny.fluent'

Button

Description

Buttons give people a way to trigger an action. They’re typically found in forms, dialog panels, and dialogs. Some buttons are specialized for particular tasks, such as navigation, repeated actions, or presenting menus.

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.

Usage

ActionButton(...)

CommandBarButton(...)

CommandButton(...)

CompoundButton(...)

DefaultButton(...)

IconButton(...)

PrimaryButton(...)

ActionButton.shinyInput(inputId, ...)

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

CommandBarButton.shinyInput(inputId, ...)

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

CommandButton.shinyInput(inputId, ...)

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

CompoundButton.shinyInput(inputId, ...)

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

DefaultButton.shinyInput(inputId, ...)

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

IconButton.shinyInput(inputId, ...)

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

PrimaryButton.shinyInput(inputId, ...)

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

Arguments

...	Props to pass to the component. The allowed props are listed below in the Details section.
inputId	ID of the component.
session	Object passed as the session argument to Shiny server.

Details

• baseClassName string
  

• variantClassName string
  

• allowDisabledFocus boolean
  Whether the button can have focus in disabled mode

• ariaDescription string
  Detailed description of the button for the benefit of screen readers.

Besides the compound button, other button types will need more information provided to screen reader.

• ariaHidden boolean
  If provided and is true it adds an 'aria-hidden' attribute instructing screen readers to ignore the element.

• ariaLabel string
  The aria label of the button for the benefit of screen readers.

• buttonType ButtonType
  Deprecated at v1.2.3, to be removed at \>= v2.0.0. Use specific button component instead.

• checked boolean
  Whether the button is checked

• className string
  If provided, additional class name to provide on the root element.

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

• data any
  Any custom data the developer wishes to associate with the menu item.

• defaultRender any
  yet unknown docs

• description IStyle
  Style for the description text if applicable (for compound buttons.) Deprecated, use secondaryText instead.

• disabled boolean
  Whether the button is disabled

• getClassNames ⁠(theme: ITheme, className: string, variantClassName: string, iconClassName: string | undefined, menuIconClassName: string | undefined, disabled: boolean, checked: boolean, expanded: boolean, hasMenu: boolean, isSplit: boolean | undefined, allowDisabledFocus: boolean) => IButtonClassNames⁠
  Method to provide the classnames to style a button. The default value for this prop is the getClassnames func defined in BaseButton.classnames.

• getSplitButtonClassNames ⁠(disabled: boolean, expanded: boolean, checked: boolean, allowDisabledFocus: boolean) => ISplitButtonClassNames⁠
  Method to provide the classnames to style a button. The default value for this prop is the getClassnames func defined in BaseButton.classnames.

• href string
  If provided, this component will be rendered as an anchor.

• iconProps IIconProps
  The props for the icon shown in the button.

• keytipProps IKeytipProps
  Optional keytip for this button

• menuAs ⁠IComponentAs<IContextualMenuProps>⁠
  Render a custom menu in place of the normal one.

• menuIconProps IIconProps
  The props for the icon shown when providing a menu dropdown.

• menuProps IContextualMenuProps
  Props for button menu. Providing this will default to showing the menu icon. See menuIconProps for overriding how the default icon looks. Providing this in addition of onClick and setting the split property to true will render a SplitButton.

• menuTriggerKeyCode KeyCodes | null
  Provides a custom KeyCode that can be used to open the button menu. The default KeyCode is the down arrow. A value of null can be provided to disable the key codes for opening the button menu.

• onAfterMenuDismiss ⁠() => void⁠
  Callback that runs after Button's contextualmenu was closed (removed from the DOM)

• onMenuClick ⁠(ev?: React.MouseEvent<HTMLElement> | React.KeyboardEvent<HTMLElement>, button?: IButtonProps) => void⁠
  Optional callback when menu is clicked.

• onRenderAriaDescription ⁠IRenderFunction<IButtonProps>⁠
  Custom render function for the aria description element.

• onRenderChildren ⁠IRenderFunction<IButtonProps>⁠
  Custom render function for rendering the button children.

• onRenderDescription ⁠IRenderFunction<IButtonProps>⁠
  Custom render function for the desciption text.

• onRenderIcon ⁠IRenderFunction<IButtonProps>⁠
  Custom render function for the icon

• onRenderMenu ⁠IRenderFunction<IContextualMenuProps>⁠
  Deprecated at v6.3.2, to be removed at \>= v7.0.0. Use menuAs instead.

• onRenderMenuIcon ⁠IRenderFunction<IButtonProps>⁠
  Custom render function for button menu icon

• onRenderText ⁠IRenderFunction<IButtonProps>⁠
  Custom render function for the label text.

• 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 button itself to mount.

• primary boolean
  Changes the visual presentation of the button to be emphasized (if defined)

• primaryActionButtonProps IButtonProps
  Optional props to be applied only to the primary action button of SplitButton and not to the overall SplitButton container

• primaryDisabled boolean
  If set to true and if this is a splitButton (split == true) then the primary action of a split button is disabled.

• renderPersistedMenuHiddenOnMount boolean
  If true, the persisted menu is rendered hidden when the button initially mounts. Non-persisted menus will not be in the component tree unless they are being shown

Note: This increases the time the button will take to mount, but can improve perceived menu open perf. when the user opens the menu.

• rootProps ⁠React.ButtonHTMLAttributes<HTMLButtonElement> | React.AnchorHTMLAttributes<HTMLAnchorElement>⁠
  Deprecated at v0.56.2, to be removed at \>= v1.0.0. Just pass in button props instead. they will be mixed into the button/anchor element rendered by the component.

• secondaryText string
  Description of the action this button takes. Only used for compound buttons

• split boolean
  If set to true, and if menuProps and onClick are provided, the button will render as a SplitButton.

• splitButtonAriaLabel string
  Accessible label for the dropdown chevron button if this button is split.

• splitButtonMenuProps IButtonProps
  Experimental prop that get passed into the menuButton that's rendered as part of split button. Anything passed in will likely need to have accompanying style changes.

• styles IButtonStyles
  Custom styling for individual elements within the button DOM.

• text string
  Text to render button label. If text is supplied, it will override any string in button children. Other children components will be passed through after the text.

• theme ITheme
  Theme provided by HOC.

• toggle boolean
  Whether button is a toggle button with distinct on and off states. This should be true for buttons that permanently change state when a press event finishes, such as a volume mute button.

• toggled boolean
  Any custom data the developer wishes to associate with the menu item. Deprecated, use checked if setting state.

• uniqueId string | number
  Unique id to identify the item. Typically a duplicate of key value.

Value

Object with shiny.tag class suitable for use in the UI of a Shiny app. The update functions return nothing (called for side effects).

Best practices

Layout

• For dialog boxes and panels, where people are moving through a sequence of screens, right-align buttons with the container.

• For single-page forms and focused tasks, left-align buttons with the container.

• Always place the primary button on the left, the secondary button just to the right of it.

• Show only one primary button that inherits theme color at rest state. If there are more than two buttons with equal priority, all buttons should have neutral backgrounds.

• Don't use a button to navigate to another place; use a link instead. The exception is in a wizard where "Back" and "Next" buttons may be used.

• Don't place the default focus on a button that destroys data. Instead, place the default focus on the button that performs the "safe act" and retains the content (such as "Save") or cancels the action (such as "Cancel").

Content

• Use sentence-style capitalization—only capitalize the first word. For more info, see Capitalization in the Microsoft Writing Style Guide.

• Make sure it's clear what will happen when people interact with the button. Be concise; usually a single verb is best. Include a noun if there is any room for interpretation about what the verb means. For example, "Delete folder" or "Create account".

Examples

# Example 1
library(shiny)
library(shiny.fluent)

tokens <- list(childrenGap = 20)

ui <- function(id) {
  ns <- NS(id)
  tags$div(
    Stack(
      DefaultButton.shinyInput(
        ns("button1"),
        text = "Default Button",
        styles = list("background: green")
      ),
      PrimaryButton.shinyInput(
        ns("button2"),
        text = "Primary Button"
      ),
      CompoundButton.shinyInput(
        ns("button3"),
        secondaryText = "Compound Button has additional text",
        text = "Compound Button"
      ),
      ActionButton.shinyInput(
        ns("button4"),
        iconProps = list("iconName" = "AddFriend"),
        text = "Action Button"
      ),
      horizontal = TRUE,
      tokens = tokens
    ),
    textOutput(ns("text"))
  )
}

server <- function(id) {
  moduleServer(id, function(input, output, session) {
    clicks <- reactiveVal(0)
    addClick <- function() { clicks(isolate(clicks() + 1)) }
    observeEvent(input$button0, addClick())
    observeEvent(input$button1, addClick())
    observeEvent(input$button2, addClick())
    observeEvent(input$button3, addClick())
    observeEvent(input$button4, addClick())
    output$text <- renderText({
      paste0("Clicks:", clicks())
    })
  })
}

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

# Example 2
library(shiny)
library(shiny.fluent)

# Split button with menu
menuProps <- list(
  items = list(
    list(
      key = "emailMessage",
      text = "Email message",
      onClick = JS("() => alert('Email message clicked')"),
      iconProps = list(
        iconName = "Mail"
      )
    ),
    list(
      key = "calendarEvent",
      text = "Calendar event",
      onClick = JS("() => alert('Calendar event clicked')"),
      iconProps = list(
        iconName = "Calendar"
      )
    )
  )
)

ui <- function(id) {
  ns <- NS(id)
  fluentPage(
    Stack(
      horizontal = TRUE,
      wrap = TRUE,
      tokens = list(
        childrenGap = 40
      ),
      DefaultButton.shinyInput(
        inputId = ns("button_1"),
        text = "Standard",
        primary = FALSE,
        split = TRUE,
        splitButtonAriaLabel = "See 2 options",
        `aria-roledescription` = "split button",
        menuProps = menuProps,
        disabled = FALSE,
        checked = FALSE
      ),
      DefaultButton.shinyInput(
        inputId = ns("button_2"),
        text = "Primary",
        primary = TRUE,
        split = TRUE,
        splitButtonAriaLabel = "See 2 options",
        `aria-roledescription` = "split button",
        menuProps = menuProps,
        disabled = FALSE,
        checked = FALSE
      ),
      DefaultButton.shinyInput(
        inputId = ns("button_3"),
        text = "Main action disabled",
        primaryDisabled = NA,
        split = TRUE,
        splitButtonAriaLabel = "See 2 options",
        `aria-roledescription` = "split button",
        menuProps = menuProps,
        checked = FALSE
      ),
      DefaultButton.shinyInput(
        inputId = ns("button_4"),
        text = "Disabled",
        disabled = TRUE,
        split = TRUE,
        splitButtonAriaLabel = "See 2 options",
        `aria-roledescription` = "split button",
        menuProps = menuProps,
        checked = FALSE
      )
    ),
    uiOutput(ns("text"))
  )
}

server <- function(id) {
  moduleServer(id, function(input, output, session) {
    output$text <- renderUI({
      lapply(seq_len(4), function(i) {
        paste0("button_", i, ": ", input[[paste0("button_", i)]])
      })
    })
  })
}

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

# Example 3
library(shiny)
library(shiny.fluent)
library(shinyjs)

# This example app shows how to use a Fluent UI Button to trigger a file upload.
# File upload is not natively supported by shiny.fluent so shinyjs is used
# to trigger the file upload input.
ui <- function(id) {
  ns <- NS(id)
  fluentPage(
    useShinyjs(),
    Stack(
      tokens = list(
        childrenGap = 10L
      ),
      horizontal = TRUE,
      DefaultButton.shinyInput(
        inputId = ns("uploadFileButton"),
        text = "Upload File",
        iconProps = list(iconName = "Upload")
      ),
      div(
        style = "
          visibility: hidden;
          height: 0;
          width: 0;
        ",
        fileInput(
          inputId = ns("uploadFile"),
          label = NULL
        )
      )
    ),
    textOutput(ns("file_path"))
  )
}

server <- function(id) {
  moduleServer(id, function(input, output, session) {
    observeEvent(input$uploadFileButton, {
      click("uploadFile")
    })

    output$file_path <- renderText({
      input$uploadFile$name
    })
  })
}

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

# Example 4
library(shiny)
library(shiny.fluent)
library(shinyjs)

# This example app shows how to use a Fluent UI Button to trigger a file download.
# File download is not natively supported by shiny.fluent so shinyjs is used
# to trigger the file download.
ui <- function(id) {
  ns <- NS(id)
  fluentPage(
    useShinyjs(),
    DefaultButton.shinyInput(
      inputId = ns("downloadButton"),
      text = "Download",
      iconProps = list(iconName = "Download")
    ),
    div(
      style = "visibility: hidden;",
      downloadButton(ns("download"), label = "")
    )
  )
}

server <- function(id) {
  moduleServer(id, function(input, output, session) {
    observeEvent(input$downloadButton, {
      click("download")
    })

    output$download <- downloadHandler(
      filename = function() {
        paste("data-", Sys.Date(), ".csv", sep="")
      },
      content = function(file) {
        write.csv(iris, file)
      }
    )
  })
}

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

---

ActivityItem

Description

An activity item (ActivityItem) represents a person's actions, such as making a comment, mentioning someone with an @mention, editing a document, or moving a file.

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.

Usage

ActivityItem(...)

Arguments

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

Details

• activityDescription React.ReactNode[] | React.ReactNode
  An element describing the activity that took place. If no activityDescription, activityDescriptionText, or onRenderActivityDescription are included, no description of the activity is shown.

• activityDescriptionText string
  Text describing the activity that occurred and naming the people involved in it. Deprecated, use activityDescription instead.

• activityIcon React.ReactNode
  An element containing an icon shown next to the activity item.

• activityPersonas ⁠Array<IPersonaSharedProps>⁠
  If activityIcon is not set, then the persona props in this array will be used as the icon for this activity item.

• animateBeaconSignal boolean
  Enables/Disables the beacon that radiates from the center of the center of the activity icon. Signals an activity has started.

• beaconColorOne string
  Beacon color one

• beaconColorTwo string
  Beacon color two

• comments React.ReactNode[] | React.ReactNode
  An element containing the text of comments or \@mention messages. If no comments, commentText, or onRenderComments are included, no comments are shown.

• commentText string
  Text of comments or \@mention messages. Deprecated, use comments instead.

• isCompact boolean
  Indicated if the compact styling should be used.

• onRenderActivityDescription ⁠IRenderFunction<IActivityItemProps>⁠
  A renderer for the description of the current activity.

• onRenderComments ⁠IRenderFunction<IActivityItemProps>⁠
  A renderer that adds the text of a comment below the activity description.

• onRenderIcon ⁠IRenderFunction<IActivityItemProps>⁠
  A renderer to create the icon next to the activity item.

• onRenderTimeStamp ⁠IRenderFunction<IActivityItemProps>⁠
  A renderer adds a time stamp. If not included, timeStamp is shown as plain text below the activity.

• styles IActivityItemStyles
  Optional styling for the elements within the Activity Item.

• timeStamp string | React.ReactNode[] | React.ReactNode
  Element shown as a timestamp on this activity. If not included, no timestamp is shown.

Value

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

Best practices

Layout

• Use a list of multiple activity items to indicate a history of events relating to a single file, folder, person, or other entity. Alternatively, use a single activity item to indicate the most recent event on an entity.

• Group multiple similar events occurring near the same time into a single activity item.

Examples

library(shiny)
library(shiny.fluent)

ui <- function(id) {
  ActivityItem(
    activityDescription = tagList(
      Link(key = 1, "Philippe Lampros"),
      tags$span(key = 2, " commented")
    ),
    activityIcon = Icon(iconName = "Message"),
    comments = tagList(
      tags$span(key = 1, "Hello! I am making a comment.")
    ),
    timeStamp = "Just now"
  )
}

server <- function(id) {
  moduleServer(id, function(input, output, session) {})
}

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

---

Announced

Description

The Announced component aims to fill several of the accessibility gaps that exist in various web application experiences. It provides text for the screen reader in certain scenarios that are lacking comprehensive updates, particularly those showing the completion status or progress of operation(s).

Some real-world applications of the component include copying, uploading, or moving many files; deleting or renaming a single file; "lazy loading" of page sections that do not appear all at once; and appearance of search results.

The Announced component currently has the following documented use cases:

1. Quick Actions: Operations such as editing text or deletion that are short enough that they do not require a status during progress.

2. Search Results: Appearance of search results such as in contact fields or search boxes.

3. Lazy Loading: "Lazy loading" of page sections that do not appear all at once.

4. Bulk Operations: Operations that require multiple sub operations, such as the moving of several files.

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.

Usage

Announced(...)

Arguments

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

Details

• "aria-live" 'off' | 'polite' | 'assertive'
  Priority with which the screen reader should treat updates to this region @default 'polite'

• as React.ElementType
  Optionally render the root of this component as another component type or primitive. The custom type must preserve any children or native props passed in. @default 'div'

• message string
  The status message provided as screen reader output

• styles ⁠IStyleFunctionOrObject<{}, IAnnouncedStyles>⁠
  Call to provide customized styling that will layer on top of the variant rules.

Value

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

Examples

library(shiny)
library(shiny.fluent)

ui <- function(id) {
  Announced(message = "Screen reader message")
}

server <- function(id) {
  moduleServer(id, function(input, output, session) {})
}

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

---

Pickers

Description

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.

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.

Usage

BasePickerListBelow(...)

TagPicker(...)

Arguments

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

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.

Value

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

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"))
}

---

Breadcrumb

Description

Breadcrumbs should be used as a navigational aid in your app or site. They indicate the current page’s location within a hierarchy and help the user understand where they are in relation to the rest of that hierarchy. They also afford one-click access to higher levels of that hierarchy.

Breadcrumbs are typically placed, in horizontal form, under the masthead or navigation of an experience, above the primary content area.

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.

Usage

Breadcrumb(...)

Arguments

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

Details

• ariaLabel string
  Aria label for the root element of the breadcrumb (which is a navigation landmark).

• className string
  Optional class for the root breadcrumb element.

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

• dividerAs ⁠IComponentAs<IDividerAsProps>⁠
  Render a custom divider in place of the default chevron >

• focusZoneProps IFocusZoneProps
  Extra props for the root FocusZone.

• items IBreadcrumbItem[]
  Collection of breadcrumbs to render

• maxDisplayedItems number
  The maximum number of breadcrumbs to display before coalescing. If not specified, all breadcrumbs will be rendered.

• onGrowData ⁠(data: IBreadcrumbData) => IBreadcrumbData | undefined⁠
  Method that determines how to group the length of the breadcrumb. Return undefined to never increase breadcrumb length.

• onReduceData ⁠(data: IBreadcrumbData) => IBreadcrumbData | undefined⁠
  Method that determines how to reduce the length of the breadcrumb. Return undefined to never reduce breadcrumb length.

• onRenderItem ⁠IRenderFunction<IBreadcrumbItem>⁠
  Custom render function for each breadcrumb item.

• onRenderOverflowIcon ⁠IRenderFunction<IButtonProps>⁠
  Render a custom overflow icon in place of the default icon ...

• overflowAriaLabel string
  Aria label for the overflow button.

• overflowIndex number
  Optional index where overflow items will be collapsed. Defaults to 0.

• styles ⁠IStyleFunctionOrObject<IBreadcrumbStyleProps, IBreadcrumbStyles>⁠
  

• theme ITheme
  

• tooltipHostProps ITooltipHostProps
  Extra props for the TooltipHost which wraps each breadcrumb item.

• item IBreadcrumbItem
  Breadcrumb item to left of the divider to be passed for custom rendering. For overflowed items, it will be last item in the list.

Value

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

Examples

library(shiny)
library(shiny.fluent)

items <- list(
  list(text = "Files", key = "Files", href = "#/page"),
  list(text = "Folder 1", key = "f1", href = "#/page"),
  list(text = "Folder 2", key = "f2", href = "#/page"),
  list(text = "Folder 3", key = "f3", href = "#/page"),
  list(text = "Folder 4 (non-clickable)", key = "f4"),
  list(text = "Folder 5", key = "f5", href = "#/page", isCurrentItem = TRUE)
)

ui <- function(id) {
  Breadcrumb(
    items = items,
    maxDisplayedItems = 3,
    ariaLabel = "Breadcrumb with items rendered as links",
    overflowAriaLabel = "More links"
  )
}
server <- function(id) {
  moduleServer(id, function(input, output, session) { })
}

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

---

Calendar

Description

The calendar control lets people select and view a single date or a range of dates in their calendar. It’s made up of 3 separate views: the month view, year view, and decade view.

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.

Usage

Calendar(...)

Calendar.shinyInput(inputId, ..., value = shiny.react::JS("new Date()"))

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

Arguments

...	Props to pass to the component. The allowed props are listed below in the Details section.
inputId	ID of the component.
value	Starting value.
session	Object passed as the session argument to Shiny server.

Details

• allFocusable boolean
  Allows all dates and buttons to be focused, including disabled ones

• autoNavigateOnSelection boolean
  Whether the month view should automatically navigate to the next or previous date range depending on the selected date. If this property is set to true and the currently displayed month is March 2017, if the user clicks on a day outside the month, i.e., April 1st, the picker will automatically navigate to the month of April.

• className string
  Optional class name to add to the root element.

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

• dateRangeType DateRangeType
  The date range type indicating how many days should be selected as the user selects days

• dateTimeFormatter ICalendarFormatDateCallbacks
  Apply additional formating to dates, for example localized date formatting.

• firstDayOfWeek DayOfWeek
  The first day of the week for your locale.

• firstWeekOfYear FirstWeekOfYear
  Defines when the first week of the year should start, FirstWeekOfYear.FirstDay, FirstWeekOfYear.FirstFullWeek or FirstWeekOfYear.FirstFourDayWeek are the possible values

• highlightCurrentMonth boolean
  Whether the month picker should highlight the current month

• highlightSelectedMonth boolean
  Whether the month picker should highlight the selected month

• isDayPickerVisible boolean
  Whether the day picker is shown beside the month picker or hidden.

• isMonthPickerVisible boolean
  Whether the month picker is shown beside the day picker or hidden.

• maxDate Date
  If set the Calendar will not allow navigation to or selection of a date later than this value.

• minDate Date
  If set the Calendar will not allow navigation to or selection of a date earlier than this value.

• navigationIcons ICalendarIconStrings
  Customize navigation icons using ICalendarIconStrings

• onDismiss ⁠() => void⁠
  Callback issued when calendar is closed

• onSelectDate ⁠(date: Date, selectedDateRangeArray?: Date[]) => void⁠
  Callback issued when a date is selected

• restrictedDates Date[]
  If set the Calendar will not allow selection of dates in this array.

• selectDateOnClick boolean
  When clicking on "Today", select the date and close the calendar.

• shouldFocusOnMount boolean
  This property has been removed at 0.80.0 in place of the focus method, to be removed \@ 1.0.0.

• showCloseButton boolean
  Whether the close button should be shown or not

• showGoToToday boolean
  Whether the "Go to today" link should be shown or not

• showMonthPickerAsOverlay boolean
  Show month picker on top of date picker when visible.

• showSixWeeksByDefault boolean
  Whether the calendar should show 6 weeks by default.

• showWeekNumbers boolean
  Whether the calendar should show the week number (weeks 1 to 53) before each week row

• strings ICalendarStrings | null
  Localized strings to use in the Calendar

• today Date
  Value of today. If null, current time in client machine will be used.

• value Date
  Default value of the Calendar, if any

• workWeekDays DayOfWeek[]
  The days that are selectable when dateRangeType is WorkWeek. If dateRangeType is not WorkWeek this property does nothing.

• yearPickerHidden boolean
  Whether the year picker is enabled

Value

Object with shiny.tag class suitable for use in the UI of a Shiny app. The update functions return nothing (called for side effects).

Best practices

Layout

• Don’t break the control apart.

• Include an up and down arrow for navigating between time ranges and a chevron to make the calendar collapsible.

Content

• Use the following format for dates: month, day, year, as in July 31, 2016. When space is limited, use numbers and slashes for dates if the code supports that format and automatically displays the appropriate date format for different locales. For example, 2/16/19.

• Don't use ordinal numbers (such as 1st, 12th, or 23rd) to indicate a date.

Examples

library(shiny)
library(shiny.fluent)

ui <- function(id) {
  ns <- NS(id)
  div(
    Calendar.shinyInput(ns("calendar"), value = "2020-06-25T22:00:00.000Z"),
    textOutput(ns("calendarValue")),
    h3("If `value` is missing, default to system date"),
    Calendar.shinyInput(ns("calendar2")),
    textOutput(ns("calendarDefault")),
    h3("If `value` is NULL, also default to system date"),
    Calendar.shinyInput(ns("calendar3"), value = NULL),
    textOutput(ns("calendarNull"))
  )
}

server <- function(id) {
  moduleServer(id, function(input, output, session) {
    output$calendarValue <- renderText({
      sprintf("Value: %s", input$calendar)
    })
    output$calendarDefault <- renderText({
      sprintf("Value: %s", input$calendar2)
    })
    output$calendarNull <- renderText({
      sprintf("Value: %s", input$calendar3)
    })
  })
}

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

---

Callout

Description

A callout is an anchored tip that can be used to teach people or guide them through the app without blocking them.

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.

Usage

Callout(...)

Arguments

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

Details

• alignTargetEdge boolean
  If true the positioning logic will prefer to flip edges rather than to nudge the rectangle to fit within bounds, thus making sure the element aligns perfectly with target's alignment edge

• ariaDescribedBy string
  Defines the element id referencing the element containing the description for the callout.

• ariaLabel string
  Accessible label text for callout.

• ariaLabelledBy string
  Defines the element id referencing the element containing label text for callout.

• backgroundColor string
  The background color of the Callout in hex format ie. #ffffff.

• beakWidth number
  The width of the beak.

• bounds ⁠IRectangle | ((target?: Target, targetWindow?: Window) => IRectangle | undefined)⁠
  The bounding rectangle (or callback that returns a rectangle) for which the contextual menu can appear in.

• calloutMaxHeight number
  Set max height of callout When not set the callout will expand with contents up to the bottom of the screen

• calloutMaxWidth number
  Custom width for callout including borders. If value is 0, no width is applied.

• calloutWidth number
  Custom width for callout including borders. If value is 0, no width is applied.

• className string
  CSS class to apply to the callout.

• coverTarget boolean
  If true the position returned will have the menu element cover the target. If false then it will position next to the target;

• directionalHint DirectionalHint
  How the element should be positioned

• directionalHintFixed boolean
  If true the position will not change sides in an attempt to fit the callout within bounds. It will still attempt to align it to whatever bounds are given.

• directionalHintForRTL DirectionalHint
  How the element should be positioned in RTL layouts. If not specified, a mirror of the directionalHint alignment edge will be used instead. This means that DirectionalHint.BottomLeft will change to DirectionalHint.BottomRight but DirectionalHint.LeftAuto will not change.

• doNotLayer boolean
  If true do not render on a new layer. If false render on a new layer.

• finalHeight number
  Specify the final height of the content. To be used when expanding the content dynamically so that callout can adjust its position.

• gapSpace number
  The gap between the Callout and the target

• hidden boolean
  If specified, renders the Callout in a hidden state. Use this flag, rather than rendering a callout conditionally based on visibility, to improve rendering performance when it becomes visible. Note: When callout is hidden its content will not be rendered. It will only render once the callout is visible.

• hideOverflow boolean
  Manually set OverflowYHidden style prop to true on calloutMain element A variety of callout load animations will need this to hide the scollbar that can appear

• isBeakVisible boolean
  If true then the beak is visible. If false it will not be shown.

• layerProps ILayerProps
  Optional props to pass to the Layer component hosting the panel.

• minPagePadding number
  The minimum distance the callout will be away from the edge of the screen.

• onDismiss ⁠(ev?: any) => void⁠
  Callback when the Callout tries to close.

• onLayerMounted ⁠() => void⁠
  Optional callback when the layer content has mounted.

• onPositioned ⁠(positions?: ICalloutPositionedInfo) => void⁠
  Optional callback that is called once the callout has been correctly positioned.

• onRestoreFocus ⁠(options: { originalElement?: HTMLElement | Window; containsFocus: boolean; }) => void⁠
  Called when the component is unmounting, and focus needs to be restored. Argument passed down contains two variables, the element that the underlying popup believes focus should go to * and whether or not the popup currently contains focus. If this is provided, focus will not be restored automatically, you'll need to call originalElement.focus()

• onScroll ⁠() => void⁠
  Callback when the Callout body is scrolled.

• preventDismissOnLostFocus boolean
  If true then the callout will not dismiss when it loses focus

• preventDismissOnResize boolean
  If true then the callout will not dismiss on resize

• preventDismissOnScroll boolean
  If true then the callout will not dismiss on scroll

• role string
  Aria role assigned to the callout (Eg. dialog, alertdialog).

• setInitialFocus boolean
  If true then the callout will attempt to focus the first focusable element that it contains. If it doesn't find an element, no focus will be set and the method will return false. This means that it's the contents responsibility to either set focus or have focusable items.

• shouldRestoreFocus boolean
  If true, when this component is unmounted, focus will be restored to the element that had focus when the component first mounted.

• shouldUpdateWhenHidden boolean
  If true, the component will be updated even when hidden=true. Note that this would consume resources to update even though nothing is being shown to the user. This might be helpful though if your updates are small and you want the callout to be revealed fast to the user when hidden is set to false.

• style React.CSSProperties
  CSS style to apply to the callout.

If you set overflowY in this object, it provides a performance optimization by preventing Popup (underlying component of Callout) from calculating whether it needs a scroll bar.

• styles ⁠IStyleFunctionOrObject<ICalloutContentStyleProps, ICalloutContentStyles>⁠
  Optional styles for the component.

• target Target
  The target that the Callout should try to position itself based on. It can be either an Element a querySelector string of a valid Element or a MouseEvent. If MouseEvent is given then the origin point of the event will be used.

• theme ITheme
  Optional theme for component

Value

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

Best practices

Layout

• Don’t use a callout to ask for action confirmation; use a dialog instead.

• Place a callout near the object being described. At the pointer’s tail or head, if possible.

• Don't use large, unformatted blocks of text in your callout. They're difficult to read and overwhelming.

• Don’t block important UI with the placement of your callout. It's a poor user experience that will lead to frustration.

• Don’t open a callout from within another callout.

• Don’t show callouts on hidden elements.

• Don’t overuse callouts. Too many callouts opening automatically can be perceived as interrupting someone's workflow.

• For a particularly complex concept that needs explanation, place an info icon (iconClassNames.info) next to the concept to indicate there's more helpful information available. When someone hovers over or selects the icon, the callout should appear.

Content

• Because the content inside of a callout isn't always visible, don't put required information in a callout.

• Short sentences or sentence fragments are best.

• Don't use obvious tip text or text that simply repeats what is already on the screen. Limit the information inside of a callout to supplemental information.

• When additional context or a more advanced description is necessary, consider placing a link to "Learn more" at the bottom of the callout. When clicked, open the additional content in a new window or panel.

Examples

library(shiny)
library(shiny.fluent)

ui <- function(id) {
  ns <- NS(id)
  div(
    DefaultButton.shinyInput(ns("toggleCallout"), text = "Toggle Callout"),
    reactOutput(ns("callout"))
  )
}

server <- function(id) {
  moduleServer(id, function(input, output, session) {
    show <- reactiveVal(FALSE)
    observeEvent(input$toggleCallout, show(!show()))
    output$callout <- renderReact({
      if (show()) {
        Callout(
          tags$div(
            style = "margin: 10px",
            "Callout contents"
          )
        )
      }
    })
  })
}

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

---

Checkbox

Description

Check boxes (Checkbox) give people a way to select one or more items from a group, or switch between two mutually exclusive options (checked or unchecked, on or off).

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.

Usage

Checkbox(...)

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

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

Arguments

...	Props to pass to the component. The allowed props are listed below in the Details section.
inputId	ID of the component.
value	Starting value.
session	Object passed as the session argument to Shiny server.

Details

• ariaDescribedBy string
  ID for element that provides extended information for the checkbox.

• ariaLabel string
  Accessible label for the checkbox.

• ariaLabelledBy string
  ID for element that contains label information for the checkbox.

• ariaPositionInSet number
  The position in the parent set (if in a set) for aria-posinset.

• ariaSetSize number
  The total size of the parent set (if in a set) for aria-setsize.

• boxSide 'start' | 'end'
  Allows you to set the checkbox to be at the before (start) or after (end) the label.

• checked boolean
  Checked state. Mutually exclusive to "defaultChecked". Use this if you control the checked state at a higher level and plan to pass in the correct value based on handling onChange events and re-rendering.

• checkmarkIconProps IIconProps
  Custom icon props for the check mark rendered by the checkbox

• className string
  Additional class name to provide on the root element, in addition to the ms-Checkbox class.

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

• defaultChecked boolean
  Default checked state. Mutually exclusive to "checked". Use this if you want an uncontrolled component, and want the Checkbox instance to maintain its own state.

• defaultIndeterminate boolean
  Optional uncontrolled indeterminate visual state for checkbox. Setting indeterminate state takes visual precedence over checked or defaultChecked props given but does not affect checked state. This is not a toggleable state. On load the checkbox will receive indeterminate visual state and after the user's first click it will be removed exposing the true state of the checkbox.

• disabled boolean
  Disabled state of the checkbox.

• indeterminate boolean
  Optional controlled indeterminate visual state for checkbox. Setting indeterminate state takes visual precedence over checked or defaultChecked props given but does not affect checked state. This should not be a toggleable state. On load the checkbox will receive indeterminate visual state and after the first user click it should be removed by your supplied onChange callback function exposing the true state of the checkbox.

• inputProps ⁠React.ButtonHTMLAttributes<HTMLElement | HTMLButtonElement>⁠
  Optional input props that will be mixed into the input element, before other props are applied. This allows you to extend the input element with additional attributes, such as data-automation-id needed for automation. Note that if you provide, for example, "disabled" as well as "inputProps.disabled", the former will take precedence over the later.

• keytipProps IKeytipProps
  Optional keytip for this checkbox

• label string
  Label to display next to the checkbox.

• onChange ⁠(ev?: React.FormEvent<HTMLElement | HTMLInputElement>, checked?: boolean) => void⁠
  Callback that is called when the checked value has changed.

• onRenderLabel ⁠IRenderFunction<ICheckboxProps>⁠
  Custom render function for the label.

• styles ⁠IStyleFunctionOrObject<ICheckboxStyleProps, ICheckboxStyles>⁠
  Call to provide customized styling that will layer on top of the variant rules.

• theme ITheme
  Theme provided by HOC.

Value

Object with shiny.tag class suitable for use in the UI of a Shiny app. The update functions return nothing (called for side effects).

Best practices

Layout

• Use a single check box when there's only one selection to make or choice to confirm. Selecting a blank check box selects it. Selecting it again clears the check box.

• Use multiple check boxes when one or more options can be selected from a group. Unlike radio buttons, selecting one check box will not clear another check box.

Content

• Separate two groups of check boxes with headings rather than positioning them one after the other.

• Use sentence-style capitalization—only capitalize the first word. For more info, see Capitalization in the Microsoft Writing Style Guide.

• Don't use end punctuation (unless the check box label absolutely requires multiple sentences).

• Use a sentence fragment for the label, rather than a full sentence.

• Make it easy for people to understand what will happen if they select or clear a check box.

Examples

library(shiny)
library(shiny.fluent)

ui <- function(id) {
  ns <- NS(id)
  div(
    Checkbox.shinyInput(ns("checkbox"), value = FALSE),
    textOutput(ns("checkboxValue"))
  )
}

server <- function(id) {
  moduleServer(id, function(input, output, session) {
    output$checkboxValue <- renderText({
      sprintf("Value: %s", input$checkbox)
    })
  })
}

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

---

ChoiceGroup

Description

Radio buttons (ChoiceGroup) let people select a single option from two or more choices.

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.

Usage

ChoiceGroup(...)

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

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

Arguments

...	Props to pass to the component. The allowed props are listed below in the Details section.
inputId	ID of the component.
value	Starting value.
session	Object passed as the session argument to Shiny server.

Details

• componentRef ⁠IRefObject<IChoiceGroupOption>⁠
  Optional callback to access the IChoiceGroup interface. Use this instead of ref for accessing the public methods and properties of the component.

• focused boolean
  Indicates if the ChoiceGroupOption should appear focused, visually

• name string
  This value is used to group each ChoiceGroupOption into the same logical ChoiceGroup

• onBlur ⁠(ev: React.FocusEvent<HTMLElement>, props?: IChoiceGroupOption) => void⁠
  A callback for receiving a notification when the choice has lost focus.

• onChange ⁠(evt?: React.FormEvent<HTMLElement | HTMLInputElement>, props?: IChoiceGroupOption) => void⁠
  A callback for receiving a notification when the choice has been changed.

• onFocus ⁠(ev?: React.FocusEvent<HTMLElement | HTMLInputElement>, props?: IChoiceGroupOption) => void | undefined⁠
  A callback for receiving a notification when the choice has received focus.

• required boolean
  If true, it specifies that an option must be selected in the ChoiceGroup before submitting the form

• theme ITheme
  Theme (provided through customization.)

• ariaLabelledBy string
  ID of an element to use as the aria label for this ChoiceGroup.

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

• defaultSelectedKey string | number
  The key of the option that will be initially checked.

• label string
  Descriptive label for the choice group.

• onChange ⁠(ev?: React.FormEvent<HTMLElement | HTMLInputElement>, option?: IChoiceGroupOption) => void⁠
  A callback for receiving a notification when the choice has been changed.

• onChanged ⁠(option: IChoiceGroupOption, evt?: React.FormEvent<HTMLElement | HTMLInputElement>) => void⁠
  Deprecated and will be removed by 07/17/2017. Use onChange instead.

• options IChoiceGroupOption[]
  The options for the choice group.

• selectedKey string | number
  The key of the selected option. If you provide this, you must maintain selection state by observing onChange events and passing a new value in when changed.

• styles ⁠IStyleFunctionOrObject<IChoiceGroupStyleProps, IChoiceGroupStyles>⁠
  Call to provide customized styling that will layer on top of the variant rules.

• theme ITheme
  Theme (provided through customization).

Value

Object with shiny.tag class suitable for use in the UI of a Shiny app. The update functions return nothing (called for side effects).

Best practices

Layout

• Use radio buttons when there are two to seven options, you have enough screen space, and the options are important enough to be a good use of that screen space.

• If there are more than seven options, use a drop-down menu instead.

• To give people a way to select more than one option, use check boxes instead.

• If a default option is recommended for most people in most situations, use a drop-down menu instead.

• Align radio buttons vertically instead of horizontally, if possible. Horizontal alignment is harder to read and localize. If there are only two mutually exclusive options, combine them into a single check box or toggle. For example, use a check box for "I agree" statements instead of radio buttons for "I agree" and "I disagree".

Content

• List the options in a logical order, such as most likely to be selected to least, simplest operation to most complex, or least risk to most. Listing options in alphabetical order isn't recommended because the order will change when the text is localized.

• Select the safest (to prevent loss of data or system access), most secure, and most private option as the default. If safety and security aren't factors, select the most likely or convenient option.

• Use a phrase for the label, rather than a full sentence.

• Make sure to give people the option to not make a choice. For example, include a "None" option.

Examples

library(shiny)
library(shiny.fluent)

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

ui <- function(id) {
  ns <- NS(id)
  div(
    ChoiceGroup.shinyInput(ns("choice"), value = "B", options = options),
    textOutput(ns("groupValue"))
  )
}

server <- function(id) {
  moduleServer(id, function(input, output, session) {
    output$groupValue <- renderText({
      sprintf("Value: %s", input$choice)
    })
  })
}

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

---

Coachmark

Description

Coach marks (Coachmark) are used to draw a person’s attention to parts of the UI and increase engagement with those elements. A teaching bubble appears on hover or selection of the coach mark.

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.

Usage

Coachmark(...)

Arguments

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

Details

• ariaAlertText string
  Text to announce to screen reader / narrator when Coachmark is displayed

• ariaDescribedBy string
  Defines the element id referencing the element containing the description for the Coachmark.

• ariaDescribedByText string
  Defines the text content for the ariaDescribedBy element

• ariaLabelledBy string
  Defines the element id referencing the element containing label text for Coachmark.

• ariaLabelledByText string
  Defines the text content for the ariaLabelledBy element

• beaconColorOne string
  Beacon color one.

• beaconColorTwo string
  Beacon color two.

• beakHeight number
  The height of the Beak component.

• beakWidth number
  The width of the Beak component.

• className string
  If provided, additional class name to provide on the root element.

• collapsed boolean
  The starting collapsed state for the Coachmark. Use isCollapsed instead.

• color string
  Color of the Coachmark/TeachingBubble.

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

• delayBeforeCoachmarkAnimation number
  Delay in milliseconds before Coachmark animation appears.

• delayBeforeMouseOpen number
  Delay before allowing mouse movements to open the Coachmark.

• height number
  The height of the Coachmark.

• isCollapsed boolean
  The starting collapsed state for the Coachmark.

• isPositionForced boolean
  Whether or not to force the Coachmark/TeachingBubble content to fit within the window bounds.

• mouseProximityOffset number
  The distance in pixels the mouse is located before opening up the Coachmark.

• onAnimationOpenEnd ⁠() => void⁠
  Callback when the opening animation completes.

• onAnimationOpenStart ⁠() => void⁠
  Callback when the opening animation begins.

• onDismiss ⁠(ev?: any) => void⁠
  Callback when the Coachmark tries to close.

• onMouseMove ⁠(e: MouseEvent) => void⁠
  Callback to run when the mouse moves.

• persistentBeak boolean
  If true then the Coachmark beak (arrow pointing towards target) will always be visible as long as Coachmark is visible

• positioningContainerProps IPositioningContainerProps
  Props to pass to the PositioningContainer component. Specify the directionalHint to indicate on which edge the Coachmark/TeachingBubble should be positioned.

• preventDismissOnLostFocus boolean
  If true then the Coachmark will not dismiss when it loses focus

• preventFocusOnMount boolean
  If true then focus will not be set to the Coachmark when it mounts. Useful in cases where focus on coachmark is causing other components in page to dismiss upon losing focus.

• styles ⁠IStyleFunctionOrObject<ICoachmarkStyleProps, ICoachmarkStyles>⁠
  Call to provide customized styling that will layer on top of the variant rules

• target HTMLElement | string | null
  The target that the Coachmark should try to position itself based on.

• teachingBubbleRef ITeachingBubble
  Ref for TeachingBubble

• theme ITheme
  Theme provided by higher order component.

• width number
  The width of the Coachmark.

• ariaDescribedBy string
  Defines the element id referencing the element containing the description for the positioningContainer.

• ariaLabel string
  Accessible label text for positioningContainer.

• ariaLabelledBy string
  Defines the element id referencing the element containing label text for positioningContainer.

• backgroundColor string
  The background color of the positioningContainer in hex format ie. #ffffff.

• bounds IRectangle
  The bounding rectangle for which the contextual menu can appear in.

• className string
  CSS class to apply to the positioningContainer.

• componentRef ⁠IRefObject<IPositioningContainer>⁠
  All props for your component are to be defined here.

• coverTarget boolean
  If true the position returned will have the menu element cover the target. If false then it will position next to the target;

• directionalHint DirectionalHint
  How the element should be positioned

• directionalHintFixed boolean
  If true the position will not change sides in an attempt to fit the positioningContainer within bounds. It will still attempt to align it to whatever bounds are given.

• directionalHintForRTL DirectionalHint
  How the element should be positioned in RTL layouts. If not specified, a mirror of directionalHint will be used instead

• doNotLayer boolean
  If true do not render on a new layer. If false render on a new layer.

• finalHeight number
  Specify the final height of the content. To be used when expanding the content dynamically so that positioningContainer can adjust its position.

• minPagePadding number
  The minimum distance the positioningContainer will be away from the edge of the screen.

• offsetFromTarget number
  The gap between the positioningContainer and the target

• onDismiss ⁠(ev?: any) => void⁠
  Callback when the positioningContainer tries to close.

• onLayerMounted ⁠() => void⁠
  Optional callback when the layer content has mounted.

• onPositioned ⁠(positions?: IPositionedData) => void⁠
  Optional callback that is called once the positioningContainer has been correctly positioned.

• positioningContainerMaxHeight number
  Set max height of positioningContainer When not set the positioningContainer will expand with contents up to the bottom of the screen

• positioningContainerWidth number
  Custom width for positioningContainer including borders. If value is 0, no width is applied.

• preventDismissOnScroll boolean
  If true then the onClose will not not dismiss on scroll

• role string
  Aria role assigned to the positioningContainer (Eg. dialog, alertdialog).

• setInitialFocus boolean
  If true then the positioningContainer will attempt to focus the first focusable element that it contains. If it doesn't find an element, no focus will be set and the method will return false. This means that it's the contents responsibility to either set focus or have focusable items.

• target HTMLElement | string | MouseEvent | Point | null
  The target that the positioningContainer should try to position itself based on. It can be either an HTMLElement a querySelector string of a valid HTMLElement or a MouseEvent. If MouseEvent is given then the origin point of the event will be used.

• targetPoint Point
  Point used to position the positioningContainer. Deprecated, use target instead.

• useTargetPoint boolean
  If true use a point rather than rectangle to position the positioningContainer. For example it can be used to position based on a click.

Value

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

Best practices

Layout

• Only one coach mark and teaching bubble combo should be displayed at a time.

• Coach marks can be standalone or sequential. Sequential coach marks should be used sparingly to walk through complex multistep interactions. It’s recommended that a sequence of coach marks doesn’t exceed three steps.

• Coach marks are designed to only hold teaching bubbles.

• Coach mark size, color, and animation shouldn’t be altered.

Examples

library(shiny)
library(shiny.fluent)

ui <- function(id) {
  ns <- NS(id)
  tagList(
    uiOutput(ns("coachmark")),
    DefaultButton.shinyInput(ns("toggleCoachmark"),
      id = "target", text = "Toggle coachmark"
    )
  )
}

server <- function(id) {
  moduleServer(id, function(input, output, session) {
    ns <- session$ns
    coachmarkVisible <- reactiveVal(FALSE)
    observeEvent(input$toggleCoachmark, coachmarkVisible(!coachmarkVisible()))
    observeEvent(input$hideCoachmark, coachmarkVisible(FALSE))
    output$coachmark <- renderUI({
      if (coachmarkVisible()) Coachmark(
        target = "#target",
        TeachingBubbleContent(
          hasCloseButton = TRUE,
          onDismiss = triggerEvent(ns("hideCoachmark")),
          headline = "Example title",
          primaryButtonProps = list(text = "Try it"),
          secondaryButtonProps = list(text = "Try it again"),
          "Welcome to the land of coachmarks!"
        )
      )
    })
  })
}

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

---

ColorPicker

Description

The color picker (ColorPicker) is used to browse through and select colors. By default, it lets people navigate through colors on a color spectrum; or specify a color in either Red-Green-Blue (RGB); or alpha color code; or Hexadecimal textboxes.

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.

Usage

ColorPicker(...)

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

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

Arguments

...	Props to pass to the component. The allowed props are listed below in the Details section.
inputId	ID of the component.
value	Starting value.
session	Object passed as the session argument to Shiny server.

Details

• alphaLabel string
  Label for the alpha textfield.

• alphaSliderHidden boolean
  Whether to hide the alpha (or transparency) slider and text field.

• alphaType 'alpha' | 'transparency' | 'none'
alpha (the default) means display a slider and text field for editing alpha values. transparency also displays a slider and text field but for editing transparency values. none hides these controls.

Alpha represents the opacity of the color, whereas transparency represents the transparentness of the color: i.e. a 30% transparent color has 70% opaqueness.

• blueLabel string
  Label for the blue text field.

• className string
  Additional CSS class(es) to apply to the ColorPicker.

• color IColor | string
  Object or CSS-compatible string to describe the color.

• componentRef ⁠IRefObject<IColorPicker>⁠
  Gets the component ref.

• greenLabel string
  Label for the green text field.

• hexLabel string
  Label for the hex text field.

• onChange ⁠(ev: React.SyntheticEvent<HTMLElement>, color: IColor) => void⁠
  Callback for when the user changes the color. (Not called when the color is changed via props.)

• redLabel string
  Label for the red text field.

• showPreview boolean
  Whether to show color preview box.

• strings IColorPickerStrings
  Labels for elements within the ColorPicker. Defaults are provided in English only.

• styles ⁠IStyleFunctionOrObject<IColorPickerStyleProps, IColorPickerStyles>⁠
  Call to provide customized styling that will layer on top of the variant rules.

• theme ITheme
  Theme (provided through customization).

• ariaDescription string
  Detailed description for how to use the color rectangle. Moving the thumb horizontally adjusts saturation and moving it vertically adjusts value (essentially, brightness).

• ariaLabel string
  Label of the ColorRectangle for the benefit of screen reader users.

• ariaValueFormat string
  Format string for the color rectangle's current value as read by screen readers. The string must include descriptions and two placeholders for the current values: {0} for saturation and {1} for value/brightness.

• className string
  Additional CSS class(es) to apply to the ColorRectangle.

• color IColor
  Current color of the rectangle.

• componentRef ⁠IRefObject<IColorRectangle>⁠
  Gets the component ref.

• minSize number
  Minimum width and height.

• onChange ⁠(ev: React.MouseEvent | React.KeyboardEvent, color: IColor) => void⁠
  Callback for when the color changes.

• styles ⁠IStyleFunctionOrObject<IColorRectangleStyleProps, IColorRectangleStyles>⁠
  Call to provide customized styling that will layer on top of the variant rules.

• theme ITheme
  Theme (provided through customization).

• ariaLabel string
  Label of the ColorSlider for the benefit of screen reader users.

• className string
  Additional CSS class(es) to apply to the ColorSlider.

• componentRef ⁠IRefObject<IColorSlider>⁠
  Gets the component ref.

• isAlpha boolean
  If true, the slider represents an alpha slider and will display a gray checkered pattern in the background. Otherwise, the slider represents a hue slider.

• maxValue number
  Maximum value of the slider.

• minValue number
  Minimum value of the slider.

• onChange ⁠(event: React.MouseEvent | React.KeyboardEvent, newValue?: number) => void⁠
  Callback issued when the value changes.

• overlayColor string
  Hex color to use when rendering an alpha or transparency slider's overlay, without the ⁠#⁠.

• overlayStyle React.CSSProperties
  Custom style for the overlay element.

• styles ⁠IStyleFunctionOrObject<IColorSliderStyleProps, IColorSliderStyles>⁠
  Call to provide customized styling that will layer on top of the variant rules.

• theme ITheme
  Theme (provided through customization).

• thumbColor string
  CSS-compatible string for the color of the thumb element.

• type 'hue' | 'alpha' | 'transparency'
  Type of slider to display.

• value number
  Current value of the slider.

Value

Object with shiny.tag class suitable for use in the UI of a Shiny app. The update functions return nothing (called for side effects).

Examples

library(shiny)
library(shiny.fluent)

ui <- function(id) {
  ns <- NS(id)
  div(
    ColorPicker.shinyInput(ns("color"), value = "#00FF01"),
    textOutput(ns("colorValue"))
  )
}

server <- function(id) {
  moduleServer(id, function(input, output, session) {
    output$colorValue <- renderText({
      sprintf("Value: %s", input$color)
    })
  })
}

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

---

ComboBox

Description

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 cannot handle each and every case, so for advanced use cases you need to work using the original docs to achieve the desired result.

Usage

ComboBox(...)

VirtualizedComboBox(...)

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

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

Arguments

...	Props to pass to the component. The allowed props are listed below in the Details section.
inputId	ID of the component.
value	Starting value.
session	Object passed as the session argument to Shiny server.

Details

• 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.

Value

Object with shiny.tag class suitable for use in the UI of a Shiny app. The update functions return nothing (called for side effects).

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)
library(shiny.fluent)

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

ui <- function(id) {
  ns <- NS(id)
  div(
    ComboBox.shinyInput(ns("combo"), value = list(text = "some text"),
      options = options, allowFreeform = TRUE
    ),
    textOutput(ns("comboValue"))
  )
}

server <- function(id) {
  moduleServer(id, function(input, output, session) {
    output$comboValue <- renderText({
      sprintf("Value: %s", input$combo$text)
    })
  })
}

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

---

CommandBar

Description

CommandBar is a surface that houses commands that operate on the content of the window, panel, or parent region it resides above. CommandBars are one of the most visible and recognizable ways to surface commands, and can be an intuitive method for interacting with content on the page; however, if overloaded or poorly organized, they can be difficult to use and hide valuable commands from your user. CommandBars can also display a search box for finding content, hold simple commands as well as menus, or display the status of ongoing actions.

Commands should be sorted in order of importance, from left-to-right or right-to-left depending on the culture. Secondarily, organize commands in logical groupings for easier recall. CommandBars work best when they display no more than 5-7 commands. This helps users quickly find your most valuable features. If you need to show more commands, consider using the overflow menu. If you need to render status or viewing controls, these go on the right side of the CommandBar (or left side if in a left-to-right experience). Do not display more than 2-3 items on the right side as it will make the overall CommandBar difficult to parse.

All command items should have an icon and a label. Commands can render as labels only as well. In smaller widths, commands can just use icon only, but only for the most recognizable and frequently used commands. All other commands should go into an overflow where text labels can be shown.

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.

Usage

CommandBar(...)

CommandBar.shinyInput(inputId, ..., itemValueGetter = function(el) el$key)

Arguments

...	Props to pass to the component. The allowed props are listed below in the Details section.
inputId	ID of the component. Value of the clicked CommandBarItem will be sent to this ID.
itemValueGetter	A function that takes a CommandBarItem and returns a value to be sent to Shiny. By default it returns key of the item.

Details

• buttonStyles IButtonStyles
  Custom styles for individual button

• cacheKey string
  A custom cache key to be used for this item. If cacheKey is changed, the cache will invalidate. Defaults to key value.

• commandBarButtonAs ⁠IComponentAs<ICommandBarItemProps>⁠
  Method to override the render of the individual command bar button. Not used when item is rendered in overflow.

• iconOnly boolean
  Show only an icon for this item, not text. Does not apply if item is in the overflow.

• renderedInOverflow boolean
  Context under which the item is being rendered. This value is mutated by the CommandBar and is useful for adjusting the onRender function.

• tooltipHostProps ITooltipHostProps
  Props for the tooltip when in iconOnly mode.

• ariaLabel string
  Accessibility text to be read by the screen reader when the user's focus enters the command bar. The screen reader will read this text after reading information about the first focusable item in the command bar.

• buttonAs ⁠IComponentAs<IButtonProps>⁠
  Custom component for the near and far item buttons. Not used for overflow menu items.

• className string
  Additional css class to apply to the command bar

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

• dataDidRender ⁠(renderedData: any) => void⁠
  Function to be called every time data is rendered. It provides the data that was actually rendered. A use case would be adding telemetry when a particular control is shown in an overflow or dropped as a result of onReduceData, or to count the number of renders that an implementation of onReduceData triggers.

• farItems ICommandBarItemProps[]
  Items to render on the right side (or left, in RTL). ICommandBarItemProps extends IContextualMenuItem.

• items ICommandBarItemProps[]
  Items to render. ICommandBarItemProps extends IContextualMenuItem.

• onDataGrown ⁠(movedItem: ICommandBarItemProps) => void⁠
  Callback invoked when data has been grown.

• onDataReduced ⁠(movedItem: ICommandBarItemProps) => void⁠
  Callback invoked when data has been reduced.

• onGrowData ⁠(data: ICommandBarData) => ICommandBarData | undefined⁠
  Custom function to grow data if items are too small for the given space. Return undefined if no more steps can be taken to avoid infinate loop.

• onReduceData ⁠(data: ICommandBarData) => ICommandBarData | undefined⁠
  Custom function to reduce data if items do not fit in given space. Return undefined if no more steps can be taken to avoid infinate loop.

• overflowButtonAs ⁠IComponentAs<IButtonProps>⁠
  Custom component for the overflow button.

• overflowButtonProps IButtonProps
  Props to be passed to overflow button. If menuProps are passed through this prop, any items provided will be prepended to any computed overflow items.

• overflowItems ICommandBarItemProps[]
  Default items to have in the overflow menu. ICommandBarItemProps extends IContextualMenuItem.

• shiftOnReduce boolean
  When true, items will be 'shifted' off the front of the array when reduced, and unshifted during grow.

• styles ⁠IStyleFunctionOrObject<ICommandBarStyleProps, ICommandBarStyles>⁠
  Customized styling that will layer on top of the variant rules.

• theme ITheme
  Theme provided by HOC.

Value

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

Examples

library(shiny)
library(shiny.fluent)

items <- function(ns) {
  list(
    CommandBarItem(
      key = ns("newItem"),
      text = "New",
      cacheKey = "myCacheKey",
      split = TRUE,
      iconProps = list(iconName = "Add"),
      subMenuProps = list(
        items = list(
          CommandBarItem(
            key = ns("emailMessage"),
            text = "Email message",
            iconProps = list(iconName = "Mail")
          ),
          CommandBarItem(
            key = ns("calendarEvent"),
            text = "Calendar event",
            iconProps = list(iconName = "Calendar")
          )
        )
      )
    ),
    CommandBarItem(
      key = ns("upload"),
      text = "Upload",
      iconProps = list(iconName = "Upload")
    ),
    CommandBarItem(
      key = ns("share"),
      text = "Share",
      iconProps = list(iconName = "Share")
    ),
    CommandBarItem(
      key = ns("download"),
      text = "Download",
      iconProps = list(iconName = "Download")
    )
  )
}

farItems <- function(ns) {
  list(
    CommandBarItem(
      key = ns("tile"),
      text = "Grid view",
      ariaLabel = "Grid view",
      iconOnly = TRUE,
      iconProps = list(iconName = "Tiles")
    ),
    CommandBarItem(
      key = ns("info"),
      text = "Info",
      ariaLabel = "Info",
      iconOnly = TRUE,
      iconProps = list(iconName = "Info")
    )
  )
}

ui <- function(id) {
  ns <- NS(id)
  tagList(
    CommandBar(
      items = items(ns),
      farItems = farItems(ns)
    ),
    textOutput(ns("commandBarItems")),
    CommandBar.shinyInput(
      inputId = ns("commandBar"),
      items = items(identity),
      farItems = farItems(identity)
    ),
    textOutput(ns("commandBar"))
  )
}

server <- function(id) {
  moduleServer(id, function(input, output, session) {
    commandBarItemClicked <- reactiveVal()
    observeEvent(input$newItem, commandBarItemClicked("newItem clicked (explicitly observed)"))
    observeEvent(input$upload, commandBarItemClicked("upload clicked (explicitly observed)"))
    output$commandBarItems <- renderText(commandBarItemClicked())
    output$commandBar <- renderText(input$commandBar)
  })
}

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

---

Command bar item

Description

Helper function for constructing items for CommandBar and CommandBar.shinyInput.

Usage

CommandBarItem(
  key,
  text,
  onClick = setInputValue(inputId = key, value = 0, event = TRUE),
  ...
)

Arguments

key	Key of the item.
text	Text to be displayed on the menu.
onClick	A JS function that runs on item click. By default it sends input value to input[[key]]. If used within CommandBar.shinyInput, it will send the value to the input ID specified in inputId argument of CommandBar.shinyInput.
...	Additional props to pass to CommandBarItem.

Value

Item suitable for use in the CommandBar and CommandBar.shinyInput.

See Also

CommandBar

---

PeoplePicker

Description

The people picker (PeoplePicker) is used to select one or more entities, such as people or groups, from a list. It makes composing an email to someone, or adding them to a group, easy if you don’t know their full name or email address.

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.

Usage

CompactPeoplePicker(...)

NormalPeoplePicker(...)

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

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

Arguments

...	Props to pass to the component. The allowed props are listed below in the Details section.
inputId	ID of the component.
value	Starting value.
session	Object passed as the session argument to Shiny server.

Details

• styles ⁠IStyleFunctionOrObject<IPeoplePickerItemSelectedStyleProps, IPeoplePickerItemSelectedStyles>⁠
  Call to provide customized styling that will layer on top of the variant rules.

• ValidationState ValidationState
  

• className string
  Additional CSS class(es) to apply to the PeoplePickerItem root element.

• theme ITheme
  Theme provided by High-Order Component.

• compact boolean
  Flag that controls whether each suggested PeoplePicker item (Persona) is rendered with or without secondary text for compact look.

• personaProps IPersonaProps
  Persona props for each suggested for picking PeoplePicker item.

• styles ⁠IStyleFunctionOrObject<IPeoplePickerItemSuggestionStyleProps, IPeoplePickerItemSuggestionStyles>⁠
  Call to provide customized styling that will layer on top of the variant rules.

• suggestionsProps IBasePickerSuggestionsProps
  General common props for all PeoplePicker items suggestions.

Value

Object with shiny.tag class suitable for use in the UI of a Shiny app. The update functions return nothing (called for side effects).

Best practices

Layout

• Use the people picker to add someone to the To line of an email, or to add someone to a list.

• Use the ⁠MemberList PeoplePicker⁠ to display selections below the input field.

Examples

library(shiny)
library(shiny.fluent)

assetsUrl <- "https://static2.sharepointonline.com/files/fabric/office-ui-fabric-react-assets/"
malePersonaUrl <- paste0(assetsUrl, "persona-male.png")
femalePersonaUrl <- paste0(assetsUrl, "persona-female.png")

people <- tibble::tibble(
  key = c(1, 2, 3, 4, 5, 6, 7),
  imageUrl = c(
    femalePersonaUrl,
    malePersonaUrl,
    malePersonaUrl,
    malePersonaUrl,
    malePersonaUrl,
    femalePersonaUrl,
    malePersonaUrl
  ),
  imageInitials = c("PV", "AR", "AL", "RK", "CB", "VL", "MS"),
  text = c(
    "Annie Lindqvist",
    "Aaron Reid",
    "Alex Lundberg",
    "Roko Kolar",
    "Christian Bergqvist",
    "Valentina Lovric",
    "Maor Sharett"
  ),
  secondaryText = c(
    "Designer",
    "Designer",
    "Software Developer",
    "Financial Analyst",
    "Sr. Designer",
    "Design Developer",
    "UX Designer"
  ),
  tertiaryText = c(
    "In a meeting",
    "In a meeting",
    "In a meeting",
    "In a meeting",
    "In a meeting",
    "In a meeting",
    "In a meeting"
  ),
  optionalText = c(
    "Available at 4:00pm",
    "Available at 4:00pm",
    "Available at 4:00pm",
    "Available at 4:00pm",
    "Available at 4:00pm",
    "Available at 4:00pm",
    "Available at 4:00pm"
  ),
  isValid = c(TRUE, TRUE, TRUE, TRUE, TRUE, TRUE, TRUE),
  presence = c(2, 6, 4, 1, 2, 2, 3),
  canExpand = c(NA, NA, NA, NA, NA, NA, NA)
)

ui <- function(id) {
  ns <- NS(id)
  tagList(
    textOutput(ns("selectedPeople")),
    NormalPeoplePicker.shinyInput(
      ns("selectedPeople"),
      options = people,
      pickerSuggestionsProps = list(
        suggestionsHeaderText = 'Matching people',
        mostRecentlyUsedHeaderText = 'Sales reps',
        noResultsFoundText = 'No results found',
        showRemoveButtons = TRUE
      )
    )
  )
}

server <- function(id) {
  moduleServer(id, function(input, output, session) {
    output$selectedPeople <- renderText({
      if (length(input$selectedPeople) == 0) {
        "Select recipients below:"
      } else {
        selectedPeople <- dplyr::filter(people, key %in% input$selectedPeople)
        paste("You have selected:", paste(selectedPeople$text, collapse=", "))
      }
    })
  })
}

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

---

ContextualMenu

Description

ContextualMenus are lists of commands that are based on the context of selection, mouse hover or keyboard focus. They are one of the most effective and highly used command surfaces, and can be used in a variety of places.

There are variants that originate from a command bar, or from cursor or focus. Those that come from CommandBars use a beak that is horizontally centered on the button. Ones that come from right click and menu button do not have a beak, but appear to the right and below the cursor. ContextualMenus can have submenus from commands, show selection checks, and icons.

Organize commands in groups divided by rules. This helps users remember command locations, or find less used commands based on proximity to others. One should also group sets of mutually exclusive or multiple selectable options. Use icons sparingly, for high value commands, and don’t mix icons with selection checks, as it makes parsing commands difficult. Avoid submenus of submenus as they can be difficult to invoke or remember.

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.

Usage

ContextualMenu(...)

Arguments

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

Details

• className string
  Additional css class to apply to the ContextualMenuItem

• classNames IMenuItemClassNames
  Classnames for different aspects of a menu item

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

• dismissMenu ⁠(ev?: any, dismissAll?: boolean) => void⁠
  This prop will get set by ContextualMenu and can be called to close the menu this item belongs to. If dismissAll is true, all menus will be closed.

• dismissSubMenu ⁠() => void⁠
  This prop will get set by ContextualMenu and can be called to close this item's subMenu, if present.

• getSubmenuTarget ⁠() => HTMLElement | undefined⁠
  This prop will get set by the wrapping component and will return the element that wraps this ContextualMenuItem. Used for openSubMenu.

• hasIcons boolean | undefined
  If this item has icons

• index number
  Index of the item

• item IContextualMenuItem
  The item to display

• onCheckmarkClick ⁠(item: IContextualMenuItem, ev: React.MouseEvent<HTMLElement>) => void⁠
  Click handler for the checkmark

• openSubMenu ⁠(item: any, target: HTMLElement) => void⁠
  This prop will get set by ContextualMenu and can be called to open this item's subMenu, if present.

• styles ⁠IStyleFunctionOrObject<IContextualMenuItemStyleProps, IContextualMenuItemStyles>⁠
  Call to provide customized styling that will layer on top of the variant rules.

• theme ITheme
  Theme provided by High-Order Component.

• focusableElementIndex number
  

• hasCheckmarks boolean
  

• hasIcons boolean
  

• index number
  

• totalItemCount number
  

• defaultMenuItemRenderer ⁠(item: IContextualMenuItemRenderProps) => React.ReactNode⁠
  

• hasCheckmarks boolean
  

• hasIcons boolean
  

• items IContextualMenuItem[]
  

• role string
  

• totalItemCount number
  

• alignTargetEdge boolean
  If true the positioning logic will prefer to flip edges rather than to nudge the rectangle to fit within bounds, thus making sure the element aligns perfectly with target's alignment edge

• ariaLabel string
  Accessible label for the ContextualMenu's root element (inside the callout).

• beakWidth number
  The width of the beak.

• bounds ⁠IRectangle | ((target?: Target, targetWindow?: Window) => IRectangle | undefined)⁠
  The bounding rectangle (or callback that returns a rectangle) which the contextual menu can appear in.

• calloutProps ICalloutProps
  Additional custom props for the Callout.

• className string
  Additional CSS class to apply to the ContextualMenu.

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

• contextualMenuItemAs ⁠React.ComponentClass<IContextualMenuItemProps> | React.FunctionComponent<IContextualMenuItemProps>⁠
  Custom component to use for rendering individual menu items.

• coverTarget boolean
  If true, the menu will be positioned to cover the target. If false, it will be positioned next to the target.

• delayUpdateFocusOnHover boolean
  If true, the contextual menu will not be updated until focus enters the menu via other means. This will only result in different behavior when shouldFocusOnMount = false.

• directionalHint DirectionalHint
  How the menu should be positioned

• directionalHintFixed boolean
  If true the position will not change sides in an attempt to fit the ContextualMenu within bounds. It will still attempt to align it to whatever bounds are given.

• directionalHintForRTL DirectionalHint
  How the menu should be positioned in RTL layouts. If not specified, a mirror of directionalHint will be used.

• doNotLayer boolean
  If true do not render on a new layer. If false render on a new layer.

• focusZoneProps IFocusZoneProps
  Props to pass down to the FocusZone. NOTE: the default FocusZoneDirection will be used unless a direction is specified in the focusZoneProps (even if other focusZoneProps are defined)

• gapSpace number
  The gap between the ContextualMenu and the target

• getMenuClassNames ⁠(theme: ITheme, className?: string) => IContextualMenuClassNames⁠
  Method to provide the classnames to style the contextual menu.

• hidden boolean
  If true, renders the ContextualMenu in a hidden state. Use this flag, rather than rendering a ContextualMenu conditionally based on visibility, to improve rendering performance when it becomes visible. Note: When ContextualMenu is hidden its content will not be rendered. It will only render once the ContextualMenu is visible.

• id string
  ID for the ContextualMenu's root element (inside the callout). Should be used for aria-owns and other such uses, rather than direct reference for programmatic purposes.

• isBeakVisible boolean
  If true then the beak is visible. If false it will not be shown.

• isSubMenu boolean
  Whether this menu is a submenu of another menu.

• items IContextualMenuItem[]
  Menu items to display.

• labelElementId string
  Used as aria-labelledby for the menu element inside the callout.

• onDismiss ⁠(ev?: React.MouseEvent | React.KeyboardEvent, dismissAll?: boolean) => void⁠
  Callback when the ContextualMenu tries to close. If dismissAll is true then all submenus will be dismissed.

• onItemClick ⁠(ev?: React.MouseEvent<HTMLElement> | React.KeyboardEvent<HTMLElement>, item?: IContextualMenuItem) => boolean | void⁠
  Click handler which is invoked if onClick is not passed for individual contextual menu item. Returning true will dismiss the menu even if ev.preventDefault() was called.

• onMenuDismissed ⁠(contextualMenu?: IContextualMenuProps) => void⁠
  Callback for when the menu is being closed (removing from the DOM).

• onMenuOpened ⁠(contextualMenu?: IContextualMenuProps) => void⁠
  Callback for when the menu has been opened.

• onRenderMenuList ⁠IRenderFunction<IContextualMenuListProps>⁠
  Method to override the render of the list of menu items.

• onRenderSubMenu ⁠IRenderFunction<IContextualMenuProps>⁠
  Custom render function for a submenu.

• onRestoreFocus ⁠(options: { originalElement?: HTMLElement | Window; containsFocus: boolean; }) => void⁠
  Called when the component is unmounting, and focus needs to be restored. Argument passed down contains two variables, the element that the underlying popup believes focus should go to and whether or not the popup currently contains focus. If this prop is provided, focus will not be restored automatically, you'll need to call originalElement.focus()

• shouldFocusOnContainer boolean
  Whether to focus on the contextual menu container (as opposed to the first menu item).

• shouldFocusOnMount boolean
  Whether to focus on the menu when mounted.

• shouldUpdateWhenHidden boolean
  If true, the menu will be updated even when hidden=true. Note that this will consume resources to update even when nothing is being shown to the user. This might be helpful if your updates are small and you want the menu to display quickly when hidden is set to false.

• styles ⁠IStyleFunctionOrObject<IContextualMenuStyleProps, IContextualMenuStyles>⁠
  Call to provide customized styling that will layer on top of the variant rules.

• subMenuHoverDelay number
  Delay (in milliseconds) to wait before expanding / dismissing a submenu on mouseEnter or mouseLeave

• target Target
  The target that the ContextualMenu should try to position itself based on. It can be either an element, a query selector string resolving to a valid element, or a MouseEvent. If a MouseEvent is given, the origin point of the event will be used.

• theme ITheme
  Theme provided by higher-order component.

• title string
  Title to be displayed at the top of the menu, above the items.

• useTargetAsMinWidth boolean
  If true the context menu will have a minimum width equal to the width of the target element

• useTargetWidth boolean
  If true the context menu will render as the same width as the target element

Value

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

Examples

library(shiny)
library(shiny.fluent)

ui <- function(id) {
  ns <- NS(id)
  div(
    DefaultButton.shinyInput(
      ns("toggleContextualMenu"),
      id = "target",
      text = "Toggle menu"
    ),
    reactOutput(ns("contextualMenu"))
  )
}

server <- function(id) {
  moduleServer(id, function(input, output, session) {
    ns <- session$ns

    showContextualMenu <- reactiveVal(FALSE)
    observeEvent(input$toggleContextualMenu, {
      showContextualMenu(!showContextualMenu())
    })

    output$contextualMenu <- renderReact({
      menuItems <- JS("[
        {
          key: 'newItem',
          text: 'New',
          onClick: () => console.log('New clicked'),
        },
        {
          key: 'divider_1',
          itemType: 1,
        },
        {
          key: 'rename',
          text: 'Rename',
          onClick: () => console.log('Rename clicked'),
        },
        {
          key: 'edit',
          text: 'Edit',
          onClick: () => console.log('Edit clicked'),
        },
        {
          key: 'properties',
          text: 'Properties',
          onClick: () => console.log('Properties clicked'),
        },
        {
          key: 'linkNoTarget',
          text: 'Link same window',
          href: 'http://bing.com',
        },
        {
          key: 'linkWithTarget',
          text: 'Link new window',
          href: 'http://bing.com',
          target: '_blank',
        },
        {
          key: 'linkWithOnClick',
          name: 'Link click',
          href: 'http://bing.com',
          onClick: function(){
            alert('Link clicked');
            ev.preventDefault();
          },
          target: '_blank',
        },
        {
          key: 'disabled',
          text: 'Disabled item',
          disabled: true,
          onClick: () => console.error('Disabled item should not be clickable.'),
        },
      ]")

      ContextualMenu(
        items = menuItems,
        hidden = !showContextualMenu(),
        target = "#target",
        onItemClick = JS(paste0(
          "function() {",
          "  Shiny.setInputValue('", ns("toggleContextualMenu"), "', Math.random());",
          "}"
        )),
        onDismiss = JS(paste0(
          "function() {",
          "  Shiny.setInputValue('", ns("toggleContextualMenu"), "', Math.random());",
          "}"
        ))
      )
    })
  })
}

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

---

DatePicker

Description

Picking a date can be tough without context. A date picker (DatePicker) offers a drop-down control that’s optimized for picking a single date from a calendar view where contextual information like the day of the week or fullness of the calendar is important. You can modify the calendar to provide additional context or to limit available dates.

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.

Usage

DatePicker(...)

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

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

Arguments

...	Props to pass to the component. The allowed props are listed below in the Details section.
inputId	ID of the component.
value	Starting value.
session	Object passed as the session argument to Shiny server.

Details

• allFocusable boolean
  Allows all elements to be focused, including disabled ones

• allowTextInput boolean
  Whether the DatePicker allows input a date string directly or not

• ariaLabel string
  Aria Label for TextField of the DatePicker for screen reader users.

• borderless boolean
  Determines if DatePicker has a border.

• calendarAs ⁠IComponentAs<ICalendarProps>⁠
  Custom Calendar to be used for date picking

• calendarProps ICalendarProps
  Pass calendar props to calendar component

• calloutProps ICalloutProps
  Pass callout props to callout component

• className string
  Optional Classname for datepicker root element .

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

• dateTimeFormatter ICalendarFormatDateCallbacks
  Apply additional formating to dates, for example localized date formatting.

• disableAutoFocus boolean
  Whether the DatePicker should open automatically when the control is focused

• disabled boolean
  Disabled state of the DatePicker.

• firstDayOfWeek DayOfWeek
  The first day of the week for your locale.

• firstWeekOfYear FirstWeekOfYear
  Defines when the first week of the year should start, FirstWeekOfYear.FirstDay, FirstWeekOfYear.FirstFullWeek or FirstWeekOfYear.FirstFourDayWeek are the possible values

• formatDate ⁠(date?: Date) => string⁠
  Optional method to format the chosen date to a string to display in the DatePicker

• highlightCurrentMonth boolean
  Whether the month picker should highlight the current month

• highlightSelectedMonth boolean
  Whether the month picker should highlight the selected month

• initialPickerDate Date
  The initially highlighted date in the calendar picker

• isMonthPickerVisible boolean
  Whether the month picker is shown beside the day picker or hidden.

• isRequired boolean
  Whether the DatePicker is a required field or not

• label string
  Label for the DatePicker

• maxDate Date
  The maximum allowable date.

• minDate Date
  The minimum allowable date.

• onAfterMenuDismiss ⁠() => void⁠
  Callback that runs after DatePicker's menu (Calendar) is closed

• onSelectDate ⁠(date: Date | null | undefined) => void⁠
  Callback issued when a date is selected

• parseDateFromString ⁠(dateStr: string) => Date | null⁠
  Optional method to parse the text input value to date, it is only useful when allowTextInput is set to true

• pickerAriaLabel string
  Aria label for date picker popup for screen reader users.

• placeholder string
  Placeholder text for the DatePicker

• showCloseButton boolean
  Whether the CalendarDay close button should be shown or not.

• showGoToToday boolean
  Whether the "Go to today" link should be shown or not

• showMonthPickerAsOverlay boolean
  Show month picker on top of date picker when visible.

• showWeekNumbers boolean
  Whether the calendar should show the week number (weeks 1 to 53) before each week row

• strings IDatePickerStrings
  Localized strings to use in the DatePicker

• styles ⁠IStyleFunctionOrObject<IDatePickerStyleProps, IDatePickerStyles>⁠
  Call to provide customized styling that will layer on top of the variant rules.

• tabIndex number
  The tabIndex of the TextField

• textField ITextFieldProps
  Pass textField props to textField component. Prop name is "textField" for compatiblity with upcoming slots work.

• theme ITheme
  Theme provided by High-Order Component.

• today Date
  Value of today. If null, current time in client machine will be used.

• underlined boolean
  Whether or not the Textfield of the DatePicker is underlined.

• value Date
  Default value of the DatePicker, if any

Value

Object with shiny.tag class suitable for use in the UI of a Shiny app. The update functions return nothing (called for side effects).

Best practices

Layout

• Use the control the way it’s designed and built. Don’t break it apart.

Content

• The control provides the date in a specific format. If the date can be entered in an input field, provide helper text in the appropriate format.

Examples

# Example 1
library(shiny)
library(shiny.fluent)

ui <- function(id) {
  ns <- NS(id)
  div(
    DatePicker.shinyInput(ns("date"), value = "2020-06-25T22:00:00.000Z"),
    textOutput(ns("dateValue")),
    h3("If `value` is missing, default to system date"),
    DatePicker.shinyInput(ns("date2")),
    textOutput(ns("dateDefault")),
    h3("If `value` is NULL, return NULL"),
    DatePicker.shinyInput(ns("date3"), value = NULL, placeholder = "I am placeholder!"),
    textOutput(ns("dateNull"))
  )
}

server <- function(id) {
  moduleServer(id, function(input, output, session) {
    output$dateValue <- renderText({
      sprintf("Value: %s", input$date)
    })
    output$dateDefault <- renderText({
      sprintf("Value: %s", input$date2)
    })
    output$dateNull <- renderText({
      sprintf("Value: %s", deparse(input$date3))
    })
  })
}

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

# Example 2
library(shiny)
library(shiny.fluent)

# Supplying custom strings for DatePicker
ui <- function(id) {
  fluentPage(
    DatePicker.shinyInput(
      "date",
      value = Sys.Date(),
      strings = list(
        months = list(
          "January", "February", "March", "April",
          "May", "June", "July", "August",
          "September", "October", "November", "December"
        ),
        shortMonths = list(
          "Jan", "Feb", "Mar", "Apr", "May", "Jun",
          "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"
        ),
        days = list(
          "Sunday", "Monday", "Tuesday", "Wednesday",
          "Thursday", "Friday", "Saturday"
        ),
        shortDays = list("S", "M", "T", "W", "T", "F", "S"),
        goToToday = "Go to today",
        prevMonthAriaLabel = "Go to previous month",
        nextMonthAriaLabel = "Go to next month",
        prevYearAriaLabel = "Go to previous year",
        nextYearAriaLabel = "Go to next year"
      )
    )
  )
}

server <- function(id) {
  moduleServer(id, function(input, output, session) {})
}

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

---

DetailsList

Description

A details list (DetailsList) is a robust way to display an information-rich collection of items, and allow people to sort, group, and filter the content. Use a details list when information density is critical.

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.

Usage

DetailsList(...)

Arguments

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

Details

• onColumnDragEnd ⁠(props: { dropLocation?: ColumnDragEndLocation; }, event: MouseEvent) => void⁠
  Callback to notify the column dragEnd event to List Need this to check whether the dragEnd has happened on corresponding list or outside of the list

• cellStyleProps ICellStyleProps
  Custom styles for cell rendering.

• column IColumn
  The column definition for the component instance.

• columnIndex number
  The column index for the component instance.

• componentRef ⁠() => void⁠
  A reference to the component instance.

• dragDropHelper IDragDropHelper | null
  The drag and drop helper for the component instance.

• isDraggable boolean
  Whether or not the column can be re-ordered via drag and drop.

• isDropped boolean
  Whether or not the column has been dropped via drag and drop.

• onColumnClick ⁠(ev: React.MouseEvent<HTMLElement>, column: IColumn) => void⁠
  Callback fired when click event occurs.

• onColumnContextMenu ⁠(column: IColumn, ev: React.MouseEvent<HTMLElement>) => void⁠
  Callback fired on contextual menu event to provide contextual menu UI.

• onRenderColumnHeaderTooltip ⁠IRenderFunction<IDetailsColumnRenderTooltipProps>⁠
  Render function for providing a column header tooltip.

• parentId string
  Parent ID used for accessibility label(s).

• setDraggedItemIndex ⁠(itemIndex: number) => void⁠
  

• styles ⁠IStyleFunctionOrObject<IDetailsColumnStyleProps, IDetailsColumnStyles>⁠
  The component styles to respect during render.

• theme ITheme
  The theme object to respect during render.

• updateDragInfo ⁠(props: { itemIndex: number; }, event?: MouseEvent) => void⁠
  Callback on drag and drop event.

• useFastIcons boolean
  Whether to use fast icon and check components. The icons can't be targeted by customization but are still customizable via class names.

• columns IColumn[]
  Column metadata

• selection ISelection
  Selection from utilities

• selectionMode SelectionMode
  Selection mode

• onRenderFooter ⁠IRenderFunction<IDetailsGroupDividerProps>⁠
  

• onRenderHeader ⁠IRenderFunction<IDetailsGroupDividerProps>⁠
  

• ariaLabel string
  ariaLabel for the entire header

• ariaLabelForSelectAllCheckbox string
  ariaLabel for the header checkbox that selects or deselects everything

• ariaLabelForSelectionColumn string
  ariaLabel for the selection column

• ariaLabelForToggleAllGroupsButton string
  ariaLabel for expand/collapse group button

• className string
  Overriding class name

• collapseAllVisibility CollapseAllVisibility
  Whether to collapse for all visibility

• columnReorderOptions IColumnReorderOptions
  Column reordering options

• columnReorderProps IColumnReorderHeaderProps
  Column reordering options

• componentRef ⁠IRefObject<IDetailsHeader>⁠
  Ref to the component itself

• isAllCollapsed boolean
  Whether or not all is collapsed

• layoutMode DetailsListLayoutMode
  Layout mode - fixedColumns or justified

• minimumPixelsForDrag number
  Minimum pixels to be moved before dragging is registered

• onColumnAutoResized ⁠(column: IColumn, columnIndex: number) => void⁠
  Callback for when column is automatically resized

• onColumnClick ⁠(ev: React.MouseEvent<HTMLElement>, column: IColumn) => void⁠
  Callback for when the column is clicked

• onColumnContextMenu ⁠(column: IColumn, ev: React.MouseEvent<HTMLElement>) => void⁠
  Callback for when the column needs to show a context menu

• onColumnIsSizingChanged ⁠(column: IColumn, isSizing: boolean) => void⁠
  Callback for when column sizing has changed

• onColumnResized ⁠(column: IColumn, newWidth: number, columnIndex: number) => void⁠
  Callback for when column is resized

• onRenderColumnHeaderTooltip ⁠IRenderFunction<IDetailsColumnRenderTooltipProps>⁠
  Callback to render a tooltip for the column header

• onRenderDetailsCheckbox ⁠IRenderFunction<IDetailsCheckboxProps>⁠
  If provided, can be used to render a custom checkbox

• onToggleCollapseAll ⁠(isAllCollapsed: boolean) => void⁠
  Callback for when collapse all is toggled

• selectAllVisibility SelectAllVisibility
  Select all button visibility

• styles ⁠IStyleFunctionOrObject<IDetailsHeaderStyleProps, IDetailsHeaderStyles>⁠
  Call to provide customized styling that will layer on top of the variant rules.

• theme ITheme
  Theme from the Higher Order Component

• useFastIcons boolean
  Whether to use fast icon and check components. The icons can't be targeted by customization but are still customizable via class names.

• columns IColumn[]
  Column metadata

• selection ISelection
  Selection from utilities

• selectionMode SelectionMode
  Selection mode

• cellStyleProps ICellStyleProps
  Rules for rendering column cells.

• checkboxVisibility CheckboxVisibility | undefined
  Checkbox visibility

• columns IColumn[]
  Column metadata

• groupNestingDepth number
  Nesting depth of a grouping

• indentWidth number | undefined
  How much to indent

• rowWidth number
  Minimum width of the row.

• selection ISelection | undefined
  Selection from utilities

• selectionMode SelectionMode | undefined
  Selection mode

• viewport IViewport | undefined
  View port of the virtualized list

• ariaLabel string
  Accessible label describing or summarizing the list.

• ariaLabelForGrid string
  Accessible label for the grid within the list.

• ariaLabelForListHeader string
  Accessible label for the list header.

• ariaLabelForSelectAllCheckbox string
  Accessible label for the select all checkbox.

• ariaLabelForSelectionColumn string
  Accessible label for the name of the selection column.

• cellStyleProps ICellStyleProps
  Props impacting the render style of cells. Since these have an impact on calculated column widths, they are handled separately from normal theme styling, but they are passed to the styling system.

• checkboxCellClassName string
  Class name to add to the cell of a checkbox.

• checkboxVisibility CheckboxVisibility
  Controls the visibility of selection check box.

• checkButtonAriaLabel string
  Accessible label for the check button.

• className string
  Class name to add to the root element.

• columnReorderOptions IColumnReorderOptions
  Options for column reordering using drag and drop.

• columns IColumn[]
  column defitions. If none are provided, default columns will be created based on the items' properties.

• compact boolean
  Whether to render in compact mode.

• componentRef ⁠IRefObject<IDetailsList>⁠
  Callback to access the IDetailsList interface. Use this instead of ref for accessing the public methods and properties of the component.

• constrainMode ConstrainMode
  Controls how the list contrains overflow.

• disableSelectionZone boolean
  Whether to disable the built-in SelectionZone, so the host component can provide its own.

• dragDropEvents IDragDropEvents
  Map of callback functions related to row drag and drop functionality.

• enableUpdateAnimations boolean
  Whether to animate updates

• enterModalSelectionOnTouch boolean
  Whether the selection zone should enter modal state on touch.

• getCellValueKey ⁠(item?: any, index?: number, column?: IColumn) => string⁠
  If provided, will be the "default" item column cell value return. A column's getValueKey can override getCellValueKey.

• getGroupHeight IGroupedListProps['getGroupHeight']
  Callback to override default group height calculation used by list virtualization.

• getKey ⁠(item: any, index?: number) => string⁠
  Callback to get the item key, to be used in the selection and on render. Must be provided if sorting or filtering is enabled.

• getRowAriaDescribedBy ⁠(item: any) => string⁠
  Callback to get the aria-describedby IDs (space-separated strings) of elements that describe the item.

• getRowAriaLabel ⁠(item: any) => string⁠
  Callback to get the aria-label string for a given item.

• groupProps IDetailsGroupRenderProps
  Override properties to render groups.

• groups IGroup[]
  Grouping instructions.

• indentWidth number
  Override for the indent width used for group nesting.

• initialFocusedIndex number
  Default index to set focus to once the items have rendered and the index exists.

• isHeaderVisible boolean
  Controls the visibility of the header.

• isPlaceholderData boolean
  Set this to true to indicate that the items being displayed are placeholder data.

• items any[]
  The items to render.

• layoutMode DetailsListLayoutMode
  Controls how the columns are adjusted.

• listProps IListProps
  Properties to pass through to the List components being rendered.

• minimumPixelsForDrag number
  The minimum mouse move distance to interpret the action as drag event.

• onActiveItemChanged ⁠(item?: any, index?: number, ev?: React.FocusEvent<HTMLElement>) => void⁠
  Callback for when an item in the list becomes active by clicking anywhere inside the row or navigating to it with the keyboard.

• onColumnHeaderClick ⁠(ev?: React.MouseEvent<HTMLElement>, column?: IColumn) => void⁠
  Callback for when the user clicks on the column header.

• onColumnHeaderContextMenu ⁠(column?: IColumn, ev?: React.MouseEvent<HTMLElement>) => void⁠
  Callback for when the user asks for a contextual menu (usually via right click) from a column header.

• onColumnResize ⁠(column?: IColumn, newWidth?: number, columnIndex?: number) => void⁠
  Callback fired on column resize

• onDidUpdate ⁠(detailsList?: DetailsListBase) => void⁠
  Callback for when the list has been updated. Useful for telemetry tracking externally.

• onItemContextMenu ⁠(item?: any, index?: number, ev?: Event) => void | boolean⁠
  Callback for when the context menu of an item has been accessed. If undefined or false is returned, ev.preventDefault() will be called.

• onItemInvoked ⁠(item?: any, index?: number, ev?: Event) => void⁠
  Callback for when a given row has been invoked (by pressing enter while it is selected.)

• onRenderCheckbox ⁠IRenderFunction<IDetailsListCheckboxProps>⁠
  If provided, can be used to render a custom checkbox.

• onRenderDetailsFooter ⁠IRenderFunction<IDetailsFooterProps>⁠
  An override to render the details footer.

• onRenderDetailsHeader ⁠IRenderFunction<IDetailsHeaderProps>⁠
  An override to render the details header.

• onRenderItemColumn ⁠(item?: any, index?: number, column?: IColumn) => React.ReactNode⁠
  If provided, will be the "default" item column renderer method. This affects cells within the rows, not the rows themselves. If a column definition provides its own onRender method, that will be used instead of this.

• onRenderMissingItem ⁠(index?: number, rowProps?: IDetailsRowProps) => React.ReactNode⁠
  Callback for what to render when the item is missing.

• onRenderRow ⁠IRenderFunction<IDetailsRowProps>⁠
  Callback to override the default row rendering.

• onRowDidMount ⁠(item?: any, index?: number) => void⁠
  Callback for when a given row has been mounted. Useful for identifying when a row has been rendered on the page.

• onRowWillUnmount ⁠(item?: any, index?: number) => void⁠
  Callback for when a given row has been unmounted. Useful for identifying when a row has been removed from the page.

• onShouldVirtualize ⁠(props: IListProps) => boolean⁠
  Callback to determine whether the list should be rendered in full, or virtualized.

Virtualization will add and remove pages of items as the user scrolls them into the visible range. This benefits larger list scenarios by reducing the DOM on the screen, but can negatively affect performance for smaller lists.

The default implementation will virtualize when this callback is not provided.

• rowElementEventMap ⁠{ eventName: string; callback: (context: IDragDropContext, event?: any) => void; }[]⁠
  Event names and corresponding callbacks that will be registered to rendered row elements.

• selection ISelection
  Selection model to track selection state.

• selectionMode SelectionMode
  Controls how/if the details list manages selection. Options include none, single, multiple

• selectionPreservedOnEmptyClick boolean
  By default, selection is cleared when clicking on an empty (non-focusable) section of the screen. Setting this value to true overrides that behavior and maintains selection.

• selectionZoneProps ISelectionZoneProps
  Additional props to pass through to the SelectionZone created by default.

• setKey string
  A key that uniquely identifies the given items. If provided, the selection will be reset when the key changes.

• shouldApplyApplicationRole boolean
  Whether the role application should be applied to the list.

• styles ⁠IStyleFunctionOrObject<IDetailsListStyleProps, IDetailsListStyles>⁠
  Custom overrides to the themed or default styles.

• theme ITheme
  Theme provided by a higher-order component.

• useFastIcons boolean
  Whether to use fast icon and check components. The icons can't be targeted by customization but are still customizable via class names.

• usePageCache boolean
  Whether to enable render page caching. This is an experimental performance optimization that is off by default.

• useReducedRowRenderer boolean
  Whether to re-render a row only when props changed. Might cause regression when depending on external updates.

• viewport IViewport
  Viewport info, provided by the withViewport decorator.

• cellsByColumn ⁠{ [columnKey: string]: React.ReactNode; }⁠
  Optional pre-rendered content per column. Preferred over onRender or onRenderItemColumn if provided.

• checkboxCellClassName string
  Class name for the checkbox cell

• checkButtonAriaLabel string
  Check button's aria label

• className string
  Overriding class name

• collapseAllVisibility CollapseAllVisibility
  Collapse all visibility

• compact boolean
  Whether to render in compact mode

• componentRef ⁠IRefObject<IDetailsRow>⁠
  Ref of the component

• dragDropEvents IDragDropEvents
  Handling drag and drop events

• dragDropHelper IDragDropHelper
  Helper for the drag and drop

• enableUpdateAnimations boolean
  Whether to animate updates

• eventsToRegister ⁠{ eventName: string; callback: (item?: any, index?: number, event?: any) => void; }[]⁠
  A list of events to register

• getRowAriaDescribedBy ⁠(item: any) => string⁠
  Callback for getting the row aria-describedby

• getRowAriaLabel ⁠(item: any) => string⁠
  Callback for getting the row aria label

• item any
  Data source for this component

• itemIndex number
  Index of the collection of items of the DetailsList

• onDidMount ⁠(row?: DetailsRowBase) => void⁠
  Callback for did mount for parent

• onRenderCheck ⁠(props: IDetailsRowCheckProps) => JSX.Element⁠
  Callback for rendering a checkbox

• onRenderDetailsCheckbox ⁠IRenderFunction<IDetailsCheckboxProps>⁠
  If provided, can be used to render a custom checkbox

• onWillUnmount ⁠(row?: DetailsRowBase) => void⁠
  Callback for will mount for parent

• rowFieldsAs ⁠React.ComponentType<IDetailsRowFieldsProps>⁠
  DOM element into which to render row field

• styles ⁠IStyleFunctionOrObject<IDetailsRowStyleProps, IDetailsRowStyles>⁠
  Overriding styles to this row

• theme ITheme
  Theme provided by styled() function

• useFastIcons boolean
  Whether to use fast icon and check components. The icons can't be targeted by customization but are still customizable via class names.

• useReducedRowRenderer boolean
  Rerender DetailsRow only when props changed. Might cause regression when depending on external updates.

• anySelected boolean
  Is any selected - also true for isSelectionModal

• canSelect boolean
  Can this checkbox be selectable

• checkClassName string
  The classname to be passed down to Check component

• className string
  Optional className to attach to the slider root element.

• compact boolean
  Is this in compact mode?

• isHeader boolean
  Is the check part of the header in a DetailsList

• isVisible boolean
  Whether or not this checkbox is visible

• onRenderDetailsCheckbox ⁠IRenderFunction<IDetailsCheckboxProps>⁠
  If provided, can be used to render a custom checkbox

• selected boolean
  Whether or not this check is selected

• styles ⁠IStyleFunctionOrObject<IDetailsRowCheckStyleProps, IDetailsRowCheckStyles>⁠
  Style override

• theme ITheme
  Theme provided by High-Order Component.

• useFastIcons boolean
  Whether to use fast icon and check components. The icons can't be targeted by customization but are still customizable via class names.

• cellStyleProps ICellStyleProps
  Style properties to customize cell render output.

• columns IColumn[]
  Columns metadata

• columnStartIndex number
  Index to start for the column

• compact boolean
  whether to render as a compact field

• enableUpdateAnimations boolean
  

• item any
  Data source for this component

• itemIndex number
  The item index of the collection for the DetailsList

• rowClassNames ⁠{ [k in keyof Pick<IDetailsRowStyles, 'isMultiline' | 'isRowHeader' | 'cell' | 'cellAnimation' | 'cellPadded' | 'cellUnpadded' | 'fields'>]: string; }⁠
  Subset of classnames currently generated in DetailsRow that are used within DetailsRowFields.

• columns IColumn[]
  Column metadata

• selection ISelection
  Selection from utilities

• selectionMode SelectionMode
  Selection mode

• ariaLabelForShimmer string
  Aria label for shimmer. Set on grid while shimmer is enabled.

• detailsListStyles IDetailsListProps['styles']
  DetailsList styles to pass through.

• enableShimmer boolean
  Boolean flag to control when to render placeholders vs real items. It's up to the consumer app to know when fetching of the data is done to toggle this prop.

• onRenderCustomPlaceholder ⁠(rowProps: IDetailsRowProps, index?: number, defaultRender?: (props: IDetailsRowProps) => React.ReactNode) => React.ReactNode⁠
  Custom placeholder renderer to be used when in need to override the default placeholder of a DetailsRow. rowProps argument is passed to leverage the calculated column measurements done by DetailsList or you can use the optional arguments of item index and defaultRender to execute additional logic before rendering the default placeholder.

• removeFadingOverlay boolean
  Determines whether to remove a fading out to bottom overlay over the shimmering items used to further emphasize the unknown number of items that will be fetched.

• shimmerLines number
  Number of shimmer placeholder lines to render.

• shimmerOverlayStyles ⁠IStyleFunctionOrObject<IShimmeredDetailsListStyleProps, IShimmeredDetailsListStyles>⁠
  Custom styles to override the styles specific to the ShimmeredDetailsList root area.

• styles ⁠IStyleFunctionOrObject<IShimmeredDetailsListStyleProps, IShimmeredDetailsListStyles>⁠
  Custom styles to override the styles specific to the ShimmeredDetailsList root area.

• skipViewportMeasures boolean
  Whether or not to use ResizeObserver (if available) to detect and measure viewport on 'resize' events.

Falls back to window 'resize' event.

Value

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

Best practices

Layout

• List items are composed of selection, icon, and name columns at minimum. You can include other columns, such as date modified, or any other metadata field associated with the collection.

• Avoid using file type icon overlays to denote status of a file as it can make the entire icon unclear.

• If there are multiple lines of text in a column, consider the variable row height variant.

• Give columns ample default width to display information.

Content

• Use sentence-style capitalization for column headers—only capitalize the first word. For more info, see ⁠[Capitalization]⁠ in the Microsoft Writing Style Guide.

⁠[capitalization]⁠: https://docs.microsoft.com/style-guide/capitalization

FAQ

My scrollable content isn't updating on scroll. What should I do?

Add the data-is-scrollable="true" attribute to your scrollable element containing the DetailsList.

By default, the List used within DetailsList will use the body element as the scrollable element. If you contain the List within a scrollable div using overflow: auto or scroll, the List needs to listen for scroll events on that element instead. On initialization, the List will traverse up the DOM looking for the first element with the data-is-scrollable attribute to know which element to listen to for knowing when to re-evaulate the visible window.

My List is not re-rendering when I mutate its items. What should I do?

To determine if the List within DetailsList should re-render its contents, the component performs a referential equality check within its shouldComponentUpdate method. This is done to minimize the performance overhead associated with re-rendering the virtualized List pages, as recommended by the React documentation.

As a result of this implementation, the inner List will not determine it should re-render if the array values are mutated. To avoid this problem, we recommend re-creating the items array backing the DetailsList by using a method such as Array.prototype.concat or ES6 spread syntax shown below:

By re-creating the items array without mutating the values, the inner List will correctly determine its contents have changed and it should then re-render with the new values.

Examples

# Example 1
library(shiny)
library(shiny.fluent)

items <- list(
  list(key = "1", name = "Mark", surname = "Swanson"),
  list(key = "2", name = "Josh", surname = "Johnson")
)

columns <- list(
  list(key = "name", fieldName = "name", name = "Name"),
  list(key = "surname", fieldName = "surname", name = "Surname")
)


ui <- function(id) {
  ns <- NS(id)
  DetailsList(items = items, columns = columns)
}

server <- function(id) {
  moduleServer(id, function(input, output, session) {})
}

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

# Example 2
library(shiny)
library(shiny.fluent)

# Custom columns text alignment and formatting
items <- list(
  list(
    key = "1",
    name = "Mark",
    number = "2"
  ),
  list(
    key = "2",
    name = "Josh",
    number = "1"
  )
)

columns <- list(
  list(
    key = "name",
    fieldName = "name",
    name = "Name"
  ),
  list(
    key = "number",
    fieldName = "number",
    name = "Number"
  )
)

ui <- function(id) {
  DetailsList(
    items = items,
    columns = columns,
    onRenderItemColumn = JS("(item, index, column) => {
      const fieldContent = item[column.fieldName]
      switch (column.key) {
        case 'name':
          return React.createElement(
            'span',
            {
              style: { textAlign: 'right', width: '100%', display: 'block' }
            },
            fieldContent
          );
        case 'number':
          return React.createElement(
            'span',
            {
              style: { textAlign: 'left', width: '100%', display: 'block' }
            },
            `%${fieldContent}`
          );
        default:
          return React.createElement('span', null, fieldContent);
      }
    }")
  )
}

server <- function(id) {
  moduleServer(id, function(input, output, session) {})
}

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

# Example 3
library(shiny)
library(shiny.fluent)

# Selecting rows in DetailsList
CustomComponents <- tags$script(HTML("(function() {
  const React = jsmodule['react'];
  const Fluent = jsmodule['@fluentui/react'];
  const Shiny = jsmodule['@/shiny'];
  const CustomComponents = jsmodule['CustomComponents'] ??= {};

  function useSelection(inputId) {
    const selection = React.useRef(new Fluent.Selection({
      onSelectionChanged() {
        const value = this.getSelectedIndices().map(i => i + 1); // R uses 1-based indexing.
        Shiny.setInputValue(inputId, value);
      }
    }));
    return selection.current;
  }

  CustomComponents.DetailsList = function DetailsList({ inputId, ...rest }) {
    const selection = useSelection(inputId);
    return React.createElement(Fluent.DetailsList, { selection, ...rest });
  }
})()"))

DetailsList.shinyInput <- function(inputId, ...) {
  shiny.react::reactElement(
    module = "CustomComponents",
    name = "DetailsList",
    props = shiny.react::asProps(inputId = inputId, ...),
    deps = shinyFluentDependency()
  )
}

items <- list(
  list(name = "Apple"),
  list(name = "Banana"),
  list(name = "Cherry")
)

ui <- function(id) {
  ns <- NS(id)
  tagList(
    CustomComponents,
    DetailsList.shinyInput(ns("selection"), items = items),
    textOutput(ns("text"))
  )
}

server <- function(id) {
  moduleServer(id, function(input, output, session) {
    output$text <- renderText(paste(input$selection, collapse = ", "))
  })
}

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

---