PopoverMessage

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

also known as PopoverEducational, PopoverNotification

Figma:

Ready

Responsive:

Ready

Adaptive:

N/A

Props

Component props
Name	Type	Default
`anchor` Required	`HTMLElement \| null \| undefined`	-
	The reference element that PopoverMessage uses to set its position.
`onDismiss` Required	`() => void`	-
	Callback fired when PopoverMessage 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 PopoverMessage. See the accessibility section for more guidance.
`children`	`React.Node`	-
	The optional content shown in PopoverMessage. See the custom content section for more guidance.
`forceDirection`	`boolean`	`false`
	Forces the position of Popover relative to its anchor element.
`id`	`string`	-
	Unique id to identify each PopoverMessage. Used for accessibility purposes.
`idealDirection`	`"up" \| "right" \| "down" \| "left"`	-
	Specifies the preferred position of PopoverMessage relative to its anchor element. See the ideal direction variant in Popover's to learn more.
`message`	`string \| ReactElement`	-
	Main text content of PopoverMessage. Content should be localized. See the message variant to learn more.
`primaryAction`	`{ accessibilityLabel?: string; href: string; onClick?: (arg1: { event: React.MouseEvent<HTMLAnchorElement> \| React.KeyboardEvent<HTMLAnchorElement>; dangerouslyDisableOnNavigation: () => void; }) => void; rel?: "none" \| "nofollow"; role: "link"; target?: null \| "self" \| "blank"; text: string; } \| { accessibilityLabel?: string; onClick?: (arg1: { event: React.MouseEvent<HTMLButtonElement> \| React.KeyboardEvent<HTMLButtonElement>; }) => void; role?: "button"; text: string; }`	-
	Main action for users to take on PopoverMessage. 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 PopoverMessage. See the role section in Accessibility for more info.
`shouldFocus`	`boolean`	`false`
	Puts the focus on PopoverMessage when it’s triggered. See the keyboard navigation section in Accessibility to learn more.
`size`	`"sm" \| "flexible"`	`"sm"`
	The maximum width of PopoverMessage. See the size variant to learn more.
`type`	`"notification" \| "education"`	`"education"`
	If set to 'notification', the background color will be darkGray, and if set to 'education', background color will be blue.
`zIndex`	`Indexable`	-
	An object representing the zIndex value of PopoverMessage. 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

Use the PopoverMessage 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 PopoverMessage at a time. If used for onboarding, show a next button instead, to launch the next popover.

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

Accessibility

PopoverMessage doesn't behave like regular popovers where they are open/closed upon user interaction, i.e. Tooltip, Dropdown, or ComboBox. PopoverMessage 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, PopoverMessage 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 PopoverMessage is already visible, we need its content to be keyboard accessible in sequential order. Don't use Layer to wrap PopoverMessage as it would move PopoverMessage 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 PopoverMessage 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 PopoverMessage is providing context about. Use id paired to aria-describedBy to link PopoverMessage to the element is providing additional information about to the user.

Role

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

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

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

For the role prop, use:

'tooltip' if the PopoverMessage 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 PopoverMessage is a dialog that requires a response from the user. When primaryAction is passed to PopoverMessage, 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

Type

If type is set to 'notification', the background color will be darkGray, and if set to 'education', background color will be blue.

Education type

import { useEffect, useRef, useState } from 'react';
import { Box, Flex, Image, Mask, PopoverMessage, Text } from 'gestalt';

export default function Example() {
  const [open, setOpen] = useState(false);
  const anchorRef = useRef(null);

  useEffect(() => {
    setOpen(true);
  }, []);

  return (
    <Box display="flex" height="100%" width="100%">
      <Box
        ref={anchorRef}
        color="secondary"
        height={75}
        padding={3}
        rounding={3}
        width={200}
      >
        <Flex gap={2}>
          <Box aria-hidden width={50}>
            <Mask rounding={3} wash>
              <Image
                alt="Image of a Spanish paella from above. Yellow rice with red peppers and shrimp on top."
                color="rgb(231, 186, 176)"
                loading="lazy"
                naturalHeight={1}
                naturalWidth={1}
                src="https://i.ibb.co/d2tpDss/IMG-0494.jpg"
              />
            </Mask>
          </Box>
          <Flex direction="column">
            <Text size="100">More ideas for</Text>
            <Text weight="bold">Food, Drinks, Snacks</Text>
          </Flex>
        </Flex>
      </Box>
      {open && (
        <PopoverMessage
          accessibilityLabel={`Description of new "More ideas" feature`}
          anchor={anchorRef.current}
          id="popovereducational-message"
          idealDirection="down"
          message="Tap to tag a product or press and hold to see product details"
          onDismiss={() => {}}
          primaryAction={{ text: 'Next', role: 'button' }}
        />
      )}
    </Box>
  );
}

Notification type

import { useEffect, useRef, useState } from 'react';
import { Box, IconButton, PopoverMessage } from 'gestalt';

export default function Example() {
  const [open, setOpen] = useState(false);
  const anchorRef = useRef(null);

  useEffect(() => {
    setOpen(true);
  }, []);

  return (
    <Box alignItems="center" display="flex" height="100%" width="100%">
      <IconButton
        ref={anchorRef}
        accessibilityLabel="Inbox"
        bgColor="lightGray"
        icon="speech"
      />
      {open && (
        <PopoverMessage
          anchor={anchorRef.current}
          id="popovereducational-notification"
          idealDirection="right"
          message="You have 2 messages!"
          onDismiss={() => {}}
          type="notification"
        />
      )}
    </Box>
  );
}

Message

The message prop accepts either a string or Text. Use a string for simple messages without any visual style. PopoverMessage 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 PopoverMessage.

Custom content

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

PopoverMessage 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 PopoverMessage. PopoverMessage 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

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

With z-index

PopoverMessage 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.

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