TeachingBubble: TeachingBubble

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

TeachingBubble

Description

A teaching bubble (TeachingBubble) brings attention to a new or important feature, with the goal of increasing engagement with the feature. A teaching bubble typically follows a coach mark.

Use teaching bubbles sparingly. Consider how frequently people will see it, and how many they’ll see across their entire experience.

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

TeachingBubble(...)

TeachingBubbleContent(...)

Arguments

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

Details

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

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

• calloutProps ICalloutProps
  Properties to pass through for Callout, reference detail properties in ICalloutProps

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

• focusTrapZoneProps IFocusTrapZoneProps
  Properties to pass through for FocusTrapZone, reference detail properties in IFocusTrapZoneProps

• footerContent string | JSX.Element
  Text that will be rendered in the footer of the TeachingBubble. May be rendered alongside primary and secondary buttons.

• hasCloseButton boolean
  Whether the TeachingBubble renders close button in the top right corner.

• hasCloseIcon boolean
  

• hasCondensedHeadline boolean
  A variation with smaller bold headline and no margins.

• hasSmallHeadline boolean
  A variation with smaller bold headline and margins to the body. (hasCondensedHeadline takes precedence if it is also set to true.)

• headline string
  A headline for the Teaching Bubble.

• illustrationImage IImageProps
  An Image for the TeachingBubble.

• isWide boolean
  Whether or not the TeachingBubble is wide, with image on the left side.

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

• primaryButtonProps IButtonProps
  The Primary interaction button

• secondaryButtonProps IButtonProps
  The Secondary interaction button

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

• target Target
  Element, MouseEvent, Point, or querySelector string that the TeachingBubble should anchor to.

• targetElement HTMLElement
  

• 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

• Teaching bubbles can be used in sequence to walk people through complex, multistep interactions only. And only show one teaching bubble at a time.

• A maximum of no more than 3 sequenced teaching bubbles should be used in a single experience.

• Sequenced teaching bubbles should have “x of y” text to indicate progress through the sequence. For example, the first teaching bubble in a sequence might be “1 of 3”.)

• 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. In the event there are more than two buttons with equal priority, all buttons should have neutral backgrounds.

Content

A teaching bubble should include:

Title

You have 25 characters (including spaces) to draw people in and get them interested. Limit to one line of text, and use sentence casing (capitalize only the first word and any proper nouns) with no punctuation.

Body copy

Lead with why the feature is useful rather than describe what it is. What does it make possible? Keep it within 120 characters (including spaces).

Action buttons

Limit button labels to 15 characters (including spaces). Provide people with an explicit action to dismiss the teaching bubble, such as “Got it”. Include a secondary button to give people the option to take action, such as “Show me” or “Edit settings”. When two buttons are needed, make the call-to-action button the primary button and the dismissal button (such as “No thanks”) the secondary button. Use sentence casing (capitalize only the first word and any proper nouns) with no punctuation. On a sequenced teaching bubble, use "Next" for the action button label and "Got it" for the final sequenced teaching bubble action button with text that closes the experience.

Link (Optional)

If there are additional steps people need to know about, or helpful information they may want to read, consider linking to a help article. Typically, these links are labeled “Learn more” with no punctuation at the end.

Examples

library(shiny)
library(shiny.fluent)

ui <- function(id) {
  ns <- NS(id)
  div(
    DefaultButton.shinyInput(
      ns("toggleTeachingBubble"),
      id = "target",
      text = "Toggle TeachingBubble"
    ),
    reactOutput(ns("teachingBubble"))
  )
}

server <- function(id) {
  moduleServer(id, function(input, output, session) {
    showBubble <- reactiveVal(FALSE)
    observeEvent(input$toggleTeachingBubble, showBubble(!showBubble()))
    output$teachingBubble <- renderReact({
      if (showBubble()) {
        TeachingBubble(
          target = "#target",
          headline = "Very useful!"
        )
      }
    })
  })
}

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

Appsilon/shiny.fluent documentation built on April 20, 2024, 1:03 p.m.