TeachingBubble — TeachingBubble • shiny.fluent

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

TeachingBubble(...)

TeachingBubbleContent(...)

Arguments

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.

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.fluent)

if (interactive()) {
  shinyApp(
    ui = div(
      DefaultButton.shinyInput("toggleTeachingBubble", id = "target", text = "Toggle TeachingBubble"),
      reactOutput("teachingBubble")
    ),
    server = function(input, output) {
      showBubble <- reactiveVal(FALSE)
      observeEvent(input$toggleTeachingBubble, showBubble(!showBubble()))
      output$teachingBubble <- renderReact({
        if (showBubble()) {
          TeachingBubble(
            target = "#target",
            headline = "Very useful!"
          )
        }
      })
    }
  )
}