Tooltip Primitive

const StyledTooltip = React.forwardRef(({ style, element, ...props }, ref) => {
  return (
    <Box
      ref={ref}
      element={element}
      zIndex="zIndex90"
      backgroundColor="colorBackgroundBody"
      borderRadius="borderRadius20"
      borderStyle="solid"
      borderWidth="borderWidth10"
      borderColor="colorBorderInverse"
      maxWidth="size50"
      paddingX="space30"
      paddingY="space20"
      fontSize="fontSize30"
      {...props}
      {...style}
    />
  );
});

const TooltipExample = () => {
  const tooltip = useTooltipPrimitiveState();
  return (
    <>
      <TooltipPrimitiveReference {...tooltip} as={Button} variant="primary">
        ✊ Action
      </TooltipPrimitiveReference>
      <TooltipPrimitive {...tooltip} as={StyledTooltip}>
        Black Lives Matter. We stand with the Black community.
      </TooltipPrimitive>
    </>
  );
};

render(
  <TooltipExample />
)

The tooltip primitive is an unstyled functional version of a tooltip. It can be used to build a component following the WAI-ARIA Tooltip pattern. Our Tooltip is built on top of this primitive.

The purpose of providing these unstyled primitives is to cater for instances when the styled Tooltip provided by Paste doesn’t meet the requirements needed to solve a unique or individual customer problem. At that point you are welcome to fall back to this functional primitive to roll your own styled tooltip while still providing a functional and accessible experience to your customers. However, we strongly recommend reviewing your design proposal with the Design Systems team before doing so.

This primitive should be used to compose all custom tooltips to ensure accessibility and upgrade paths.

const StyledTooltip = React.forwardRef(({ style, element, ...props }, ref) => {
  return (
    <Box
      ref={ref}
      element={element}
      zIndex="zIndex90"
      backgroundColor="colorBackgroundBody"
      borderRadius="borderRadius20"
      borderStyle="solid"
      borderWidth="borderWidth10"
      borderColor="colorBorderInverse"
      maxWidth="size50"
      paddingX="space30"
      paddingY="space20"
      fontSize="fontSize30"
      {...props}
      {...style}
    />
  );
});

const TooltipExample = () => {
  const tooltip = useTooltipPrimitiveState();
  return (
    <>
      <TooltipPrimitiveReference {...tooltip} as={Button} variant="primary">
        ✊ Action
      </TooltipPrimitiveReference>
      <TooltipPrimitive {...tooltip} as={StyledTooltip}>
        Black Lives Matter. We stand with the Black community.
      </TooltipPrimitive>
    </>
  );
};

render(
  <TooltipExample />
)

The placement of the tooltip is configurable via the placement prop. The available placement options are available in the props description here.

const RightPlacementExample = () => {
  const tooltip = useTooltipPrimitiveState({placement: 'right'});
  return (
    <>
      <TooltipPrimitiveReference {...tooltip} as={Button} variant="primary">
        Open tooltip
      </TooltipPrimitiveReference>
      <TooltipPrimitive {...tooltip} style={{backgroundColor: '#fff', zIndex:10}}>
        Welcome to Paste!
      </TooltipPrimitive>
    </>
  );
};
render(
  <RightPlacementExample />
)

The Tooltip primitive can be styled using Paste components and tokens. By using the as prop, we can change the underlying element and combine it with another component. In the example below we're combining the TooltipPrimitiveReference with the Button component. Inside the TooltipPrimitive we're using the Box primitive to create a container with Paste token background color, border radius, and spacing values. Because the tooltip lives outside of the main body tag, we need to provide the base Paste styles using StyledBase from our theme package. This gives the Text primitive the appropriate font stack and sizing. This example also incorporates the TooltipPrimitiveArrow to give the Tooltip a more polished look.

const StyledExample = () => {
  const tooltip = useTooltipPrimitiveState({placement: 'right'});
  return (
    <>
      <TooltipPrimitiveReference {...tooltip} as={Button} variant="secondary">
        Open tooltip
      </TooltipPrimitiveReference>
      <TooltipPrimitive {...tooltip}>
        <Box
          backgroundColor="colorBackgroundPrimaryWeakest"
          borderRadius="borderRadius20"
          padding="space30"
        >
          <TooltipPrimitiveArrow
            {...tooltip}
            fill="colorBackgroundPrimaryWeakest"
            stroke="colorBackgroundPrimaryWeakest"
          />
          <StyledBase>
            <Text color="colorText">
              Welcome to Paste!
            </Text>
          </StyledBase>
        </Box>
      </TooltipPrimitive>
    </>
  );
};
render(
  <StyledExample />
)

This package is a wrapper around the Reakit Tooltip. If you’re wondering why we wrapped that package into our own, we reasoned that it would be best for our consumers’ developer experience. For example:

• If we want to migrate the underlying nuts and bolts in the future, Twilio products that depend on this primitive would need to replace all occurrences of import … from ‘x-package’ to import … from ‘@some-new/package’. By wrapping it in @twilio-paste/x-primitive, this refactor can be avoided. The only change would be a version bump in the ‘package.json` file for the primitive.
• We can more strictly enforce semver and backwards compatibility than some of our dependencies.
• We can control when to provide an update and which versions we allow, to help reduce potential bugs our consumers may face.
• We can control which APIs we expose. For example, we may chose to enable or disable usage of certain undocumented APIs.

yarn add @twilio-paste/tooltip-primitive - or - yarn add @twilio-paste/core

This props list is a scoped version of the properties available from the Reakit Tooltip package.

baseId?: string

Sets the ID that will serve as a base for all the items IDs.

gutter?: string

Sets the offset between the reference and the tooltip on the main axis.

placement?: "auto-start" | "auto" | "auto-end" | "top-start...

Sets the placement of popover in relation to the TooltipPrimitiveReference. Available options include:

• auto-start
• auto-end
• auto
• top-start
• top-end
• top
• bottom-start
• bottom-end
• bottom
• right-start
• right-end
• right
• left-start
• left-end
• left

visible?: boolean

Whether the tooltip is visible or not.

animated?: number | boolean

If true, animating will be set to true when visible is updated. It'll wait for stopAnimation to be called or a CSS transition ends. If animated is set to a number, stopAnimation will be called only after the same number of milliseconds have passed.

size?: string | number | undefined

The size of the arrow

fill?: string

Sets the fill color of the arrow svg path

stroke?: string

Sets the stroke color of the arrow svg path