PopoverEducational

View source on GitHub
; Opens a new tab
See recent changes on GitHub
; Opens a new tab

PopoverEducational is a floating container that introduces users to elements on the screen. Used for education or onboarding experiences.

Figma:
Ready
Responsive:
Ready
Adaptive:
N/A
A11y:
Partially ready

Props

Component props
Name
Type
Default
anchor
Required
?HTMLElement
-

The reference element that PopoverEducational uses to set its position.

onDismiss
Required
() => void
-

Callback fired when PopoverEducational is closed. Must be used to control Popover’s on/off display state. See the visibility on page load variant to learn more.

accessibilityLabel
string
"Popover"

Unique label to describe each PopoverEducational. See the accessibility section for more guidance.

children
React.Node
-

The optional content shown in PopoverEducational. See the custom content section for more guidance.

id
string
-

Unique id to identify each PopoverEducational. Used for accessibility purposes.

idealDirection
"up" | "right" | "down" | "left"
-

Specifies the preferred position of PopoverEducational relative to its anchor element.

message
string | React.Element<typeof Text>
-

Main text content of PopoverEducational. Content should be localized. See the message variant to learn more.

primaryAction
{
    accessibilityLabel?: string,
    href: string,
    onClick?: ({
      event: SyntheticMouseEvent<HTMLAnchorElement> | SyntheticKeyboardEvent<HTMLAnchorElement>,
      dangerouslyDisableOnNavigation: () => void,
    }) => void,
    rel?: "none" | "nofollow",
    role: "link",
    target?: null | "self" | "blank",
    text: string,
  }
| {
    accessibilityLabel?: string,
    onClick?: ({
      event: SyntheticMouseEvent<HTMLButtonElement> | SyntheticKeyboardEvent<HTMLButtonElement>,
    }) => void,
    role?: "button",
    text: string,
  }
-

Main action for users to take on PopoverEducational. If href is supplied, the action will serve as a link. See GlobalEventsHandlerProvider to learn more about link navigation.
If no href is supplied, the action will be a button.
The accessibilityLabel should follow the accessibility guidelines for Button.
See the primary action variant to learn more.

role
"dialog" | "tooltip"
"tooltip"

The underlying ARIA role for PopoverEducational. See the role section in Accessibility for more info.

shouldFocus
boolean
false

Puts the focus on PopoverEducational when it’s triggered. See the keyboard navigation section in Accessibility to learn more.

size
"sm" | "flexible"
"sm"

The maximum width of PopoverEducational. See the size variant to learn more.

zIndex
Indexable
-

An object representing the zIndex value of PopoverEducational. Learn more about zIndex classes

Usage guidelines

When to use
  • Bringing attention to specific user interface elements for educational or onboarding purposes.
When not to use
  • Displaying critical information that prevents users from accomplishing a task.
  • Displaying information out of context.
  • As a replacement for Tooltip.
  • For presenting a list of actions or options. Use Dropdown instead.

Best practices

Do

Use the PopoverEducational to educate users on a new or existing feature. Be sure to use a caret pointing to the feature. If there is more than one item, use a CTA button to move the user to the next popover.

Don't

Show more than one PopoverEducational at a time. If used for onboarding, show a next button instead, to launch the next popover.

Do

Position PopoverEducational appropriately on the screen. Make sure the arrow points directly to the element it is referencing.

Accessibility

Keyboard navigation

PopoverEducational doesn't behave like regular popovers where they are open/closed upon user interaction, i.e. Tooltip, Dropdown, or ComboBox. PopoverEducational visibility is not directly controlled by the user; instead, its visibility is defined as part of a broader user experience and the user interaction engagement with this experience.

In most cases, PopoverEducational might be already visible on page load. See visible on page load to learn more. However, popover-based components rely on the component opening/dismissing event to capture focus.

If PopoverEducational is already visible, we need its content to be keyboard accessible in sequential order. Don't use Layer to wrap PopoverEducational as it would move PopoverEducational outside the DOM hierarchy of the parent component and it will lose contextual sequencial order. The content will placed last in the keyboard navigations sequence, becoming unreachable in its content context. Moreover, make sure PopoverEducational is implemented right after the code of the anchor element so that it navigates the popover right after the anchor.

ARIA attributes

To provide an accessible experience, make sure accessibilityLabel introduces the elements on the screen that PopoverEducational is providing context about. Use id paired to aria-describedBy to link PopoverEducational to the element is providing additional information about to the user.

Role

We recommend passing the following ARIA attribute to PopoverEducational for a better screen reader experience:

  • accessibilityLabel: describes the main purpose of a PopoverEducational for the screen reader. Should be unique and concise. For example, "Save to board" instead of "PopoverEducational". It populates aria-label.

When not passing children, PopoverEducational handles role. However, when passing children to a custom PopoverEducational, role is set to "tooltip" by default. Override role following the guidance provided.

For the role prop, use:

  • 'tooltip' if the PopoverEducational is a simple contextual text bubble that displays a description on a feature. When message is passed with no primaryAction, role is set to "tooltip".
  • 'dialog' if the PopoverEducational is a dialog that requires a response from the user. When primaryAction is passed to PopoverEducational, role is set to "dialog".

Localization

Be sure to localize all text strings. Note that localization can lengthen text by 20 to 30 percent.

Variants

Message

The message prop accepts either a string or Text. Use a string for simple messages without any visual style. PopoverEducational will handle the message style and adherence to design guidelines. If a message with more complex style is required, such as bold text or inline links, use Text to wrap your message with any additional Text or Link usages contained within.

Primary action

CTA buttons are used to move users through an onboarding or informational flow.
Generally with the text “Next”.

primaryAction displays a CTA button at the bottom of PopoverEducational.

Custom content

For more flexibility, PopoverEducational allows passing children. If passed, message and primaryAction are not rendered.

PopoverEducational doesn't overwrite style in children or set any padding or margin, therefore, make sure any Text's color is "light" and any Button's color is "white".

Size

The maximum width of PopoverEducational. PopoverEducational has different size configurations:

  • sm: 230px wide by default. Height grows to accommodate
  • flexible: Without a defined maximum width. Grows to fill the container. Height grows to accommodate copy.

Visibility on page load

PopoverEducational's positioning algorithm requires that the anchor element renders before PopoverEducational is rendered. If PopoverEducational should be visible on page load, use useEffect to toggle the visibility after the first render.

With z-index

PopoverEducational supports zIndex

Component quality checklist

Component quality checklist
Quality item
Status
Status description
Figma Library
Ready
Component is available in Figma for web and mobile web.
Responsive Web
Ready
Component responds to changing viewport sizes in web and mobile web.
Issues
This component has known issues.

Dropdown
Use Dropdown to display a list of actions or options in a Popover.

Tooltip
Tooltip describes the function of an interactive element, typically IconButton, on hover.

Edit page on GitHub
; Opens a new tab