HelpButton

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

HelpButton is an affordance that accompanies an element on the screen. It helps describe or provide assistance on how to use the accompanying element.

also known as InfoButton

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

Props

Component props
Name
Type
Default
accessibilityLabel
Required
string
-

Supply a short, descriptive label screen readers. Follow the pattern Click to learn more about [description]. See Accessibility section for guidance.

accessibilityPopoverLabel
Required
string
-

Supply a short, descriptive label for screen-readers to describe the popover content. Used for accessibility purposes.

text
Required
string | React.Element<typeof Text>
-

Informational content that's displayed when the user clicks on HelpButton.

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

Specifies the preferred position of the tooltip and popover relative to HelpButton. See Popover's ideal direction variant to learn more.

isWithinFixedContainer
boolean
false

Enables correct behavior when HelpButton is used within a fixed container. To achieve this it removes the Layer component around Popover and enables positioning relative to its anchor element. Should only be used in cases where Layer breaks the HelpButton positionings such as when the anchor element is within a sticky component.

{
  accessibilityLabel?: string,
  externalLinkIcon?:
    | "none"
    | "default"
    | {
        color: $ElementType<ElementConfig<typeof Icon>, "color">,
        size: $ElementType<ElementConfig<typeof Text>, "size">,
      },
  href: string,
  onClick?: ({
    event: SyntheticMouseEvent<HTMLAnchorElement> | SyntheticKeyboardEvent<HTMLAnchorElement>,
    dangerouslyDisableOnNavigation: () => void,
  }) => void,
  ref?: React.Ref<"a">,
  text: string,
  target?: null | "self" | "blank",
}
-

If provided, displays a link api at the bottom of the popover message.

  • href is the URL that the hyperlink points to.
  • text is the displayed text for the link. See the link variant for more details.
  • target see the target Link variant to learn more. If not defined the link will open in a new window.
  • Optionally use accessibilityLabel to supply a short, descriptive label for screen-readers to replace link texts that don't provide sufficient context about the link component behavior. Texts like "Click Here", or "Read More" can be confusing when a screen reader reads them out of context. In those cases, we must pass an alternative text to replace the link text. It populates aria-label. Screen readers read the accessibilityLabel prop, if present, instead of the link text. See Link's accessibility guidelines for more information.
  • Optionally provide an onClick callback, which is fired when the link is clicked (pressed and released) with a mouse or keyboard. See GlobalEventsHandlerProvider to learn more about link navigation.
onClick
({
  event: SyntheticMouseEvent<HTMLDivElement> | SyntheticKeyboardEvent<HTMLDivElement>,
}) => void
-

Callback fired when HelpIcon is clicked (pressed and released) with a mouse or keyboard.

zIndex
Indexable
-

Specifies the z-index for HelpButton's tooltip and popover to resolve any layering issues with other elements. See the zIndex variant for more details.

Usage guidelines

When to use
  • To offer simple, bite-sized assistive information about an element or section on the screen.
  • To provide information or links to information that enhances a user's understanding of the feature.
When not to use
  • To provide extensive information that is longer than a short sentence. Use BannerSlim instead.
  • To display recommendations for how to improve a user's experience. Use BannerSlim instead.
  • To display time-sensitive information to a user. Use BannerCallout or BannerSlim instead.

Best practices

Do

Place HelpButton to the end of the element you wish to add guidance to.

Don't

Include HelpButton within blocks of content.

Accessibility

HelpButton's tooltip text is static, defined as Click to learn more. Use the required accessibilityLabel prop to give the user more details, using the format "Click to learn more about {the associated element}". accessibilityPopoverLabel should be similar, but using the format "Expanded information about {the associated element}".

Localization

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

HelpButton depends on DefaultLabelProvider for internal text strings. Localize the texts via DefaultLabelProvider. Learn more
import { DefaultLabelProvider, Flex, HelpButton } from 'gestalt';

export default function Example() {
  return (
    <DefaultLabelProvider
      // $FlowExpectedError[incompatible-type] For demostration purposes
      labels={{
        HelpButton: {
          tooltipMessage: 'Klicken Sie hier, um mehr zu erfahren',
        },
      }}
    >
      <Flex alignItems="center" height="100%" justifyContent="center">
        <HelpButton
          accessibilityLabel="Klicken Sie hier, um mehr über die Schaltfläche Hilfe zu erfahren."
          accessibilityPopoverLabel="Erweiterte Informationen über die Schaltfläche Hilfe"
          text="Informativer Kontext, der bei einem Klick angezeigt wird"
        />
      </Flex>
    </DefaultLabelProvider>
  );
}

Variants

HelpButton's popover content can contain a link to additional information. If needed, this interaction can be paired with GlobalEventsHandlerProvider.

import { Flex, HelpButton, Text } from 'gestalt';

export default function Example() {
  return (
    <Flex alignItems="center" gap={1} height="100%" justifyContent="center">
      <Text>This is Gestalt</Text>
      <HelpButton
        accessibilityLabel="Click to learn more about gestalt"
        accessibilityPopoverLabel="Expanded information about Gestalt"
        link={{
          href: 'https://gestalt.pinterest.systems/',
          text: 'Read our documentation',
          accessibilityLabel: 'Visit Gestalt portal',
        }}
        text="Gestalt is Pinterest's design system."
      />
    </Flex>
  );
}

Text

The text prop accepts either a string or Text. Use a string for simple text without any visual style. HelpButton 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 components contained within.

import { Flex, HelpButton, Text } from 'gestalt';

export default function Example() {
  return (
    <Flex alignItems="center" gap={1} height="100%" justifyContent="center">
      <Text>This is Gestalt</Text>
      <HelpButton
        accessibilityLabel="Click to learn more about gestalt"
        accessibilityPopoverLabel="Expanded information about Gestalt"
        link={{
          href: 'https://gestalt.pinterest.systems/',
          text: 'Read our documentation',
          accessibilityLabel: 'Visit Gestalt portal',
        }}
        text={
          <Text>
            <Text inline weight="bold">
              Gestalt
            </Text>{' '}
            is Pinterest`s design system.
          </Text>
        }
      />
    </Flex>
  );
}

Tooltip
Tooltip describes the function of an interactive element, typically IconButton, on hover. However, adding links, buttons or any clickable element within Tooltip is not advisable due to accessibility concerns. Adding Tooltip to HelpButton is not necessary as it's already built in.

IconButton
HelpButton is a more specific component than IconButton. IconButton is preferable for more general uses of interactive icons whereas HelpButton is the preferred solution for providing short-form guidance for an element.

Edit page on GitHub
; Opens a new tab