Teaching bubble
The teaching bubble is useful to highlight new features, first-run experiences, and other new or changed areas in the product.
Examples
Usage
Do
- Use for first run experiences, to highlight new features, and things that have changed in the product
- Keep the content simple and brief
- Always include a description text in the teaching bubble; image, title, and buttons are optional
- Always include a title except for text-only teaching bubbles
- Use with caution — excessive use can create cognitive overload for the user
Don't
- Include screenshots as these can be mistaken for actual UI
- Use the text-only teaching bubble when the tooltip component is more appropriate
- Use for instances where the component display depends on user action (e.g. mouse over or click) — the teaching bubble shows up independently from user action
- Display more than one teaching bubble at the same time
Note: The teaching bubble will not reposition and is not dismissed if it moves offscreen through resizing or scrolling, unless the anchor element is repositioned and/or resized. You’ll need to make sure the user can access the teaching bubble.
APIs
ITeachingBubble
dismiss
() => void
ITeachingBubbleProps
anchorElementrequiredInherited From: ICustomTeachingBubbleProps
HTMLElement
The element the teaching bubble is positioned relative to.
anchorOriginrequiredInherited From: ICustomTeachingBubbleProps
IOrigin
When an anchorElement is supplied the anchorOrigin is used to describe the
relative location of the callout with respect to the anchorElement.
ariaDescribedByInherited From: ICustomTeachingBubbleProps
string
aria-describedby for the teaching bubble
ariaLabeledByInherited From: ICustomTeachingBubbleProps
string
aria-label for the teaching bubble
cornerPlacementverticalInherited From: ICustomTeachingBubbleProps
How the bubble should be aligned if the anchor origin is a corner
defaultActiveElementInherited From: ICustomTeachingBubbleProps
string | (() => string)
When the teaching bubble is mounted, what will be the element inside that gets focus.
onDismissrequiredInherited From: ICustomTeachingBubbleProps
() => void
Callback for when the teaching bubble is dismissed. The owner should be responsible for hiding the teaching bubble.
onLocationChangeInherited From: ICustomTeachingBubbleProps
() => void
Callback when a teaching bubble changes postion upon changing the anchor element or anchor origin.
textrequired
React.ReactNode
Body to be rendered in the bubble
textOnlyInherited From: ICustomTeachingBubbleProps
boolean
Is the teachign bubble only text? This will cause the callout to have light dismiss behavior.
title
string
A title to be rendered for the bubble
ICustomTeachingBubbleProps
anchorElementrequired
HTMLElement
The element the teaching bubble is positioned relative to.
anchorOriginrequired
IOrigin
When an anchorElement is supplied the anchorOrigin is used to describe the
relative location of the callout with respect to the anchorElement.
ariaDescribedBy
string
aria-describedby for the teaching bubble
ariaLabeledBy
string
aria-label for the teaching bubble
cornerPlacementvertical
How the bubble should be aligned if the anchor origin is a corner
defaultActiveElement
string | (() => string)
When the teaching bubble is mounted, what will be the element inside that gets focus.
onDismissrequired
() => void
Callback for when the teaching bubble is dismissed. The owner should be responsible for hiding the teaching bubble.
onLocationChange
() => void
Callback when a teaching bubble changes postion upon changing the anchor element or anchor origin.
textOnly
boolean
Is the teachign bubble only text? This will cause the callout to have light dismiss behavior.
TeachingBubbleCornerPlacement
horizontal0
number
If the anchor origin is a corner, the bubble will be positioned to the right/left of the element
vertical1
number
If the anchor origin is a corner, the bubble will be positioned above/below the element
