Checkbox: Checkbox

In Appsilon/shiny.fluent: Microsoft Fluent UI for Shiny Apps

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

Appsilon/shiny.fluent documentation built on Oct. 4, 2023, 6:59 a.m.