---
title: Tooltip
description: >-
  The Tooltip component displays helpful information in a small floating label
  when users hover over or focus on an element. Use tooltips to provide
  additional context or clarify terms without cluttering the interface.
api_version: 2025-07
api_name: customer-account-ui-extensions
source_url:
  html: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/overlays/tooltip
  md: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/overlays/tooltip.md
---

Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use [web components](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/polaris-web-components), native UI elements with built-in accessibility, better performance, and consistent styling with [Shopify's design system](https://shopify.dev/docs/apps/design). Check out the [migration guide](https://shopify.dev/docs/apps/build/customer-accounts/migrate-to-web-components) to upgrade your extension.

# Tooltip

The Tooltip component displays helpful information in a small floating label when users hover over or focus on an element. Use tooltips to provide additional context or clarify terms without cluttering the interface.

The library automatically applies the [WAI-ARIA Tooltip Widget pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/) to both the activator and the tooltip content. Expect screen readers to read the tooltip content when the user focuses the activator. For interactive content like links or buttons, use [Popover](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/overlays/popover) instead.

### Support Targets (25)

### Supported targets

* Customer​Account::Kitchen​Sink
* [customer-account.​footer.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/footer#footer-render-after-)
* [customer-account.​order-index.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-index#order-index-targets)
* [customer-account.​order-index.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-index#order-index-block-)
* [customer-account.​order-status.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#order-status-announcement-)
* [customer-account.​order-status.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#order-status-block-)
* [customer-account.​order-status.​cart-line-item.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#cart-line-item-render-after-)
* [customer-account.​order-status.​cart-line-list.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#cart-line-list-render-after-)
* [customer-account.​order-status.​customer-information.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#customer-information-render-after-)
* [customer-account.​order-status.​fulfillment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/fulfillment-status#fulfillment-status-targets)
* [customer-account.​order-status.​payment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/payments-and-returns#payments-and-returns-targets)
* [customer-account.​order-status.​return-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/payments-and-returns#return-details-render-after-)
* [customer-account.​order-status.​unfulfilled-items.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/fulfillment-status#unfulfilled-items-render-after-)
* [customer-account.​order.​action.​menu-item.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-actions#order-action-menu-item-)
* [customer-account.​order.​action.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-actions#order-action-)
* [customer-account.​order.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/full-page#order-specific-full-page-)
* [customer-account.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/full-page#customer-account-full-page-)
* [customer-account.​profile.​addresses.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-default#profile-page-default-targets-)
* [customer-account.​profile.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-default#announcement-)
* [customer-account.​profile.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-default#profile-block-)
* [customer-account.​profile.​company-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-b2b#profile-page-b2b-targets-)
* [customer-account.​profile.​company-location-addresses.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-b2b#company-location-addresses-render-after-)
* [customer-account.​profile.​company-location-payment.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-b2b#company-location-payment-render-after-)
* [customer-account.​profile.​company-location-staff.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-b2b#company-location-staff-render-after-)
* customer-account.​profile.​payment.​render-after

#### Use cases

* **Icon labels:** Describe the purpose of icon-only buttons so customers understand what each action does.
* **Term definitions:** Clarify unfamiliar terms, abbreviations, or statuses inline without adding permanent text.
* **Supplementary details:** Surface secondary information like estimated delivery dates or status explanations on demand.
* **Accessible descriptions:** Provide text alternatives for visual elements that screen readers can announce.

***

## Properties

Configure the following properties on the Tooltip component.

* **id**

  **string**

  A unique identifier for the component. Use this to target the component in scripts or stylesheets, or to distinguish it from other instances of the same component.

***

## Examples

### Add context to an icon

Attach a tooltip to an info icon to provide supplementary information on hover. This example shows a tooltip triggered by a pressable icon that explains why contact information is needed.

## Add context to an icon

![A tooltip providing context about contact information next to a question icon.](https://shopify.dev/assets/assets/images/templated-apis-screenshots/checkout-ui-extensions/2025-07/tooltip-default-CThGL7LT.png)

## Add context to an icon

##### React

```tsx
import {
  reactExtension,
  Icon,
  Pressable,
  Tooltip,
} from '@shopify/ui-extensions-react/customer-account';

export default reactExtension(
  'customer-account.page.render',
  () => <Extension />,
);

function Extension() {
  return (
    <Pressable
      overlay={
        <Tooltip>
          In case we need to contact you about
          your order
        </Tooltip>
      }
    >
      <Icon source="questionFill" />
    </Pressable>
  );
}
```

##### JS

```js
import {
  extension,
  Icon,
  Pressable,
  Tooltip,
} from '@shopify/ui-extensions/customer-account';

export default extension('customer-account.page.render', (root) => {
  const tooltipFragment = root.createFragment();
  const tooltip = root.createComponent(
    Tooltip,
    {},
    'In case we need to contact you about your order',
  );
  tooltipFragment.appendChild(tooltip);
  const pressable = root.createComponent(
    Pressable,
    {overlay: tooltipFragment},
    [root.createComponent(Icon, {source: 'questionFill'})],
  );

  root.appendChild(pressable);
});
```

### Describe icon buttons

Add tooltips to icon-only elements to clarify their purpose and provide an accessible description. This example shows tooltips on delivery tracking and help icons.

## Describe icon buttons

##### React

```tsx
import {
  reactExtension,
  Icon,
  InlineStack,
  Pressable,
  Tooltip,
} from '@shopify/ui-extensions-react/customer-account';

export default reactExtension(
  'customer-account.order-status.block.render',
  () => <Extension />,
);

function Extension() {
  return (
    <InlineStack spacing="base">
      <Pressable
        overlay={
          <Tooltip>Track your delivery</Tooltip>
        }
      >
        <Icon source="delivery" />
      </Pressable>
      <Pressable
        overlay={
          <Tooltip>Get help with this order</Tooltip>
        }
      >
        <Icon source="questionFill" />
      </Pressable>
    </InlineStack>
  );
}
```

##### JS

```js
import {
  extension,
  Icon,
  InlineStack,
  Pressable,
  Tooltip,
} from '@shopify/ui-extensions/customer-account';

export default extension(
  'customer-account.order-status.block.render',
  (root) => {
    const tooltip1Fragment = root.createFragment();
    const tooltip1 = root.createComponent(
      Tooltip,
      {},
      'Track your delivery',
    );
    tooltip1Fragment.appendChild(tooltip1);

    const tooltip2Fragment = root.createFragment();
    const tooltip2 = root.createComponent(
      Tooltip,
      {},
      'Get help with this order',
    );
    tooltip2Fragment.appendChild(tooltip2);

    const stack = root.createComponent(
      InlineStack,
      {spacing: 'base'},
      [
        root.createComponent(
          Pressable,
          {overlay: tooltip1Fragment},
          [root.createComponent(Icon, {source: 'delivery'})],
        ),
        root.createComponent(
          Pressable,
          {overlay: tooltip2Fragment},
          [root.createComponent(Icon, {source: 'questionFill'})],
        ),
      ],
    );

    root.appendChild(stack);
  },
);
```

### Explain a status badge

Wrap a badge in a pressable element with a tooltip to explain what a status means. This example shows a "Processing" badge with a tooltip that describes the next steps for the customer.

## Explain a status badge

##### React

```tsx
import {
  reactExtension,
  Badge,
  Pressable,
  Tooltip,
} from '@shopify/ui-extensions-react/customer-account';

export default reactExtension(
  'customer-account.order-status.block.render',
  () => <Extension />,
);

function Extension() {
  return (
    <Pressable
      overlay={
        <Tooltip>
          Your order is being prepared and will
          ship within 1–2 business days
        </Tooltip>
      }
    >
      <Badge tone="info">Processing</Badge>
    </Pressable>
  );
}
```

##### JS

```js
import {
  extension,
  Badge,
  Pressable,
  Tooltip,
} from '@shopify/ui-extensions/customer-account';

export default extension(
  'customer-account.order-status.block.render',
  (root) => {
    const tooltipFragment = root.createFragment();
    const tooltip = root.createComponent(
      Tooltip,
      {},
      'Your order is being prepared and will ship within 1\u20132 business days',
    );
    tooltipFragment.appendChild(tooltip);
    const pressable = root.createComponent(
      Pressable,
      {overlay: tooltipFragment},
      [root.createComponent(Badge, {tone: 'info'}, 'Processing')],
    );

    root.appendChild(pressable);
  },
);
```

***

## Best practices

* **Reserve tooltips for non-essential information:** The component works best for supplementary details that enhance understanding without being critical. Never hide essential information, errors, or required instructions in tooltips.
* **Add tooltips to icon-only elements:** Icon buttons need tooltips to clarify what they do. Include the element's action to help customers work efficiently.
* **Keep tooltip content brief and clear:** Aim for a short sentence or phrase. Long tooltip content is hard to read and suggests the information might need a more prominent placement in the UI.
* **Reconsider your design if many tooltips are needed:** If you're adding many tooltips to explain your interface, the design itself might be unclear. Improve labels, layout, or information architecture instead.
* **Design for touch-device fallbacks:** If the information is important enough to need a tooltip, consider making it visible by default on mobile.

***

## Limitations

* Tooltips only appear on devices with a mouse or trackpad. They don't work on touch devices like phones and tablets, which limits their usefulness for mobile customers.
* Tooltips can't contain interactive elements like links or buttons. They dismiss when the user moves away, making interaction impossible.
* The component doesn't provide built-in positioning controls. Tooltip placement is automatic and might not always appear in the ideal location for complex layouts.

***