The responsive layout is in early preview. Please report any bugs.

Tooltip

The Tooltip is a popup that displays clarifying text related to an element that has been focused or hovered on.

Status: alpha
Version: 4.0.2
Sources: Github
Storybook
Import from: @twilio-paste/core/tooltip — or — @twilio-paste/tooltip

Using alpha components in your product

Alpha components are ready for you to use in production. Components such as Tooltip are likely to not see any API changes. This is only an alpha due to the lack of documentation and a matching Sketch symbol. Feel free to share your experience using this component by starting a discussion on GitHub. We are also looking for a contributor to symbolize this component in Sketch. Interested? Reach out!

Guidelines#

The Tooltip component is a popup that displays text related to an element when the element is focused via the keyboard or on mouse hover. Tooltip follows the WAI-ARIA Tooltip Pattern.

Accessibility#

A tooltip must only be placed on a natively focusable HTML element. Good candidates include a Paste Button or a Paste Anchor if the tip also links to a help article.

Do not place tooltips on non-focusable elements, like an icon.

If your tooltip wraps a natively focusable HTML element that includes only an icon, make sure you set the prop decorative={false}, and give the icon a title. The title of the icon should be the accessible name for the button action, like "Delete phone number". The tooltip provides the additional context, like "You can delete phone numbers every 7 days". This ensures the icon and tooltip are accessible to screen readers. Refer to the focusable element example for implementation.

Examples#

<Tooltip text="Black Lives Matter. We stand with the Black community.">
  <Button variant="primary">✊ Action</Button>
</Tooltip>

<Tooltip text="Black Lives Matter. We stand with the Black community.">
  <Button variant="primary">✊ Action</Button>
</Tooltip>

Controlling placement#

The placement of the tooltip is configurable via the placement prop. The available placement options are available in the props description here. No matter the placement, the tooltip will always adjust to remain in the screen so you don't have to worry about it going off the page, or being covered by another element.

<Tooltip text="Welcome to Paste!" placement="right">
  <Button variant="primary">Open Tooltip</Button>
</Tooltip>

<Tooltip text="Welcome to Paste!" placement="right">
  <Button variant="primary">Open Tooltip</Button>
</Tooltip>

Focusable element#

A tooltip must be placed on a focusable element, such as an anchor or button.

Do not place tooltips on non-focusable elements, like an icon. Wrap them in a focusable element and place the tooltip on that.

Social Security Number

<Box display="flex" alignItems="center">
  <Text as="span">Social Security Number</Text>
  <Tooltip text="Your nine-digit Social Security number is your first and continuous connection with Social Security.">
    <Anchor href="https://paste.twilio.design">
      <InformationIcon decorative={false} title="Open Tooltip" display="block" />
    </Anchor>
  </Tooltip>
</Box>

<Box display="flex" alignItems="center">
  <Text as="span">Social Security Number</Text>
  <Tooltip text="Your nine-digit Social Security number is your first and continuous connection with Social Security.">
    <Anchor href="https://paste.twilio.design">
      <InformationIcon decorative={false} title="Open Tooltip" display="block" />
    </Anchor>
  </Tooltip>
</Box>

Tooltips require their children to forwardRefs#

If you want to add a Tooltip around a React component, you must make sure that component forwards refs. All Paste components do this by default, so this is only a concern when placing Tooltips around other types of components.

const FancyButton = React.forwardRef((props, ref) => (
  <button ref={ref} {...props} style={{backgroundColor: 'white', border: '1px solid #000', color: '#000', borderRadius: '5px', padding: '5px'}}>
    Fancy button: {props.children}
  </button>
));

const NonPasteChildComponent = () => {
  return (
    <Tooltip text="Forwarding refs correctly!">
      <FancyButton>Fancy!</FancyButton>
    </Tooltip>
  );
};

render(
  <NonPasteChildComponent />
)

const FancyButton = React.forwardRef((props, ref) => (
  <button ref={ref} {...props} style={{backgroundColor: 'white', border: '1px solid #000', color: '#000', borderRadius: '5px', padding: '5px'}}>
    Fancy button: {props.children}
  </button>
));
const NonPasteChildComponent = () => {
  return (
    <Tooltip text="Forwarding refs correctly!">
      <FancyButton>Fancy!</FancyButton>
    </Tooltip>
  );
};
render(
  <NonPasteChildComponent />
)

Using state hooks#

🚨 Power user move! 🚨

Only use this property if you are a power user. It's very easy to break your implementation and unfortunately the Paste team will not be able to debug this for you. Proceed with extreme caution.

The tooltip comes with the option of "hooking" into the internal state by using the state hook originally provided by Reakit.

Rather than the state be internal to the component, you can use the useTooltipState hook and pass the returned state to Tooltip as the state prop.

This allows you to use certain returned props from the state hook, including functions like hide and show.

An example usecase of this might be programmatically providing the user a tooltip when a certain user action is taken. In the example below we are showing a tooltip when another button is pressed. When pressed the button uses the show function from the hook. Another button using the hide function from the hook is also provided to hide the tooltip when pressed.

It should be noted that when doing so, the state prop takes precident over the other properties that affect the state or initial state of the Tooltip. They will be ignored in favour of them being provided as arguments to the useTooltipState hook.

For full details on how to use the state hook, and what props to provide it, follow the Tooltip Primitive documentation. It's the same hook, just renamed.

const StateHookExample = () => {
  const tooltip = useTooltipState();
  return (
    <Stack orientation="horizontal" spacing="space60">
      <Tooltip
      state={tooltip}
      text="This should be visible by pressing another button"
      >
        <Button variant="primary">Open tooltip</Button>
      </Tooltip>
      <Button variant="secondary" onClick={() => tooltip.show()}>
        Open tooltip on click
      </Button>
      <Button variant="secondary" onClick={() => tooltip.hide()}>
        Close tooltip on click
      </Button>
    </Stack>
  );
};

render(
  <StateHookExample />
)

const StateHookExample = () => {
  const tooltip = useTooltipState();
  return (
    <Stack orientation="horizontal" spacing="space60">
      <Tooltip
      state={tooltip}
      text="This should be visible by pressing another button"
      >
        <Button variant="primary">Open tooltip</Button>
      </Tooltip>
      <Button variant="secondary" onClick={() => tooltip.show()}>
        Open tooltip on click
      </Button>
      <Button variant="secondary" onClick={() => tooltip.hide()}>
        Close tooltip on click
      </Button>
    </Stack>
  );
};
render(
  <StateHookExample />
)

Anatomy#

Property	Default token	Modifiable?
background-color	color-background-body-inverse	No
border-width	border-width-10	No
border-color	color-border-dark	No
border-radius	border-radius-20	No
box-shadow	shadow	No
max-width	size-30	No
padding	space-30	No
padding-top	space-20	No
padding-bottom	space-20	No
z-index	z-index-90	No

Usage Guide#

API#

Installation#

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

Usage#

import {Tooltip} from '@twilio-paste/tooltip';
const PopoverExample: React.FC = () => {
  return (
    <Tooltip baseId="tooltip-example" text="Tooltip text...">
      <Button variant="primary">Open Tooltip</Button>
    </Tooltip>
  );
};

`baseId?: string`

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

`children: ReactElement`

The tooltip reference, meaning the element where the tooltip originates. Must be a focusable element.

`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 tooltip in relation to the child element. 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

`text: string`

The text content of the Tooltip.

Tooltip

Using alpha components in your product

Guidelines.css-1p5xx02{-webkit-text-decoration:none;text-decoration:none;margin-left:0.5rem;color:rgb(96,107,133);}.css-1p5xx02:hover{-webkit-text-decoration:underline;text-decoration:underline;}#

About Tooltip#

Tooltip compared to Popover#

Accessibility#

Examples#

Basic Tooltip#

Controlling placement#

Focusable element#

Tooltips require their children to forwardRefs#

Using state hooks#

🚨 Power user move! 🚨

Anatomy#

Tooltip#

Usage Guide#

API#

Installation#

Usage#

Tooltip Props#

baseId?: string

children: ReactElement

gutter?: string

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

text: string

4.0.2#

Patch Changes#

4.0.1#

Patch Changes#

4.0.0#

Patch Changes#

3.0.1#

Patch Changes#

3.0.0#

Patch Changes#

2.0.3#

Patch Changes#

2.0.2#

Patch Changes#

2.0.1#

Patch Changes#

2.0.0#

Patch Changes#

1.0.1#

Patch Changes#

1.0.0#

Patch Changes#

0.4.1link takes you to an external page (2021-01-25)

Features#

0.3.35link takes you to an external page (2021-01-15)

0.3.34link takes you to an external page (2021-01-14)

0.3.33link takes you to an external page (2021-01-14)

0.3.32link takes you to an external page (2021-01-13)

0.3.31link takes you to an external page (2021-01-07)

0.3.30link takes you to an external page (2020-12-17)

0.3.29link takes you to an external page (2020-12-17)

0.3.28link takes you to an external page (2020-12-15)

0.3.27link takes you to an external page (2020-12-11)

0.3.26link takes you to an external page (2020-12-11)

0.3.25link takes you to an external page (2020-12-09)

0.3.24link takes you to an external page (2020-12-03)

0.3.23link takes you to an external page (2020-12-02)

0.3.22link takes you to an external page (2020-11-16)

0.3.21link takes you to an external page (2020-11-11)

0.3.20link takes you to an external page (2020-11-10)

0.3.19link takes you to an external page (2020-11-06)

0.3.18link takes you to an external page (2020-11-05)

0.3.17link takes you to an external page (2020-10-30)

0.3.16link takes you to an external page (2020-10-29)

0.3.15link takes you to an external page (2020-10-23)

0.3.14link takes you to an external page (2020-10-21)

0.3.13link takes you to an external page (2020-10-19)

0.3.12link takes you to an external page (2020-10-15)

0.3.11link takes you to an external page (2020-10-13)

0.3.10link takes you to an external page (2020-10-09)

0.3.9link takes you to an external page (2020-10-07)

0.3.8link takes you to an external page (2020-10-07)

0.3.7link takes you to an external page (2020-10-07)

0.3.6link takes you to an external page (2020-10-07)

0.3.5link takes you to an external page (2020-09-22)

Guidelines#

`baseId?: string`

`children: ReactElement`

`gutter?: string`

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

`text: string`

0.4.1 (2021-01-25)

0.3.35 (2021-01-15)

0.3.34 (2021-01-14)

0.3.33 (2021-01-14)

0.3.32 (2021-01-13)

0.3.31 (2021-01-07)

0.3.30 (2020-12-17)

0.3.29 (2020-12-17)

0.3.28 (2020-12-15)

0.3.27 (2020-12-11)

0.3.26 (2020-12-11)

0.3.25 (2020-12-09)

0.3.24 (2020-12-03)

0.3.23 (2020-12-02)

0.3.22 (2020-11-16)

0.3.21 (2020-11-11)

0.3.20 (2020-11-10)

0.3.19 (2020-11-06)

0.3.18 (2020-11-05)

0.3.17 (2020-10-30)

0.3.16 (2020-10-29)

0.3.15 (2020-10-23)

0.3.14 (2020-10-21)

0.3.13 (2020-10-19)

0.3.12 (2020-10-15)

0.3.11 (2020-10-13)

0.3.10 (2020-10-09)

0.3.9 (2020-10-07)

0.3.8 (2020-10-07)

0.3.7 (2020-10-07)

0.3.6 (2020-10-07)

0.3.5 (2020-09-22)

0.3.4 (2020-09-21)

0.3.3 (2020-09-15)

0.3.2 (2020-09-15)

0.3.1 (2020-09-14)

0.2.15 (2020-09-10)

0.2.14 (2020-09-09)

0.2.13 (2020-09-09)

0.2.12 (2020-09-08)

0.2.11 (2020-09-08)

0.2.10 (2020-09-03)

0.2.9 (2020-08-31)

0.2.8 (2020-08-31)

0.2.7 (2020-08-31)

0.2.6 (2020-08-24)

0.2.5 (2020-08-19)

0.2.4 (2020-08-12)

0.2.3 (2020-08-12)

0.2.2 (2020-08-06)

0.2.1 (2020-08-05)

0.1.11 (2020-08-04)

0.1.10 (2020-07-31)

0.1.9 (2020-07-30)

0.1.8 (2020-07-29)

0.1.7 (2020-07-28)

0.1.6 (2020-07-22)

0.1.5 (2020-07-20)

0.1.4 (2020-07-15)

0.1.3 (2020-07-14)

0.1.2 (2020-07-14)

0.1.1 (2020-07-08)