---
title: Migrate Tooltip from Polaris React
description: >-
  Replace Polaris React Tooltip with s-tooltip while keeping essential
  instructions and accessible names visible.
source_url:
  html: >-
    https://shopify.dev/docs/apps/build/app-home/migrate-from-polaris-react/tooltip
  md: >-
    https://shopify.dev/docs/apps/build/app-home/migrate-from-polaris-react/tooltip.md
api_name: app-home
---

# Migrate Tooltip from Polaris React

Replace Polaris React `Tooltip` with [`s-tooltip`](https://shopify.dev/docs/api/app-home/web-components/typography-and-content/tooltip) only for brief, supplementary information. Tooltips aren't available on touch devices, so don't put required instructions, errors, or the control's only accessible name in one.

***

## Migrate an icon-button tooltip

## Migrating an icon-button tooltip

##### Polaris web components

```html
<s-tooltip id="info-tooltip">View product details and inventory status</s-tooltip>
<s-button
  icon="info"
  interestFor="info-tooltip"
  accessibilityLabel="More information"
></s-button>
```

##### Polaris React

```tsx
import {Button, Tooltip} from '@shopify/polaris';
import {InfoIcon} from '@shopify/polaris-icons';

<Tooltip content="View product details and inventory status">
  <Button icon={InfoIcon} accessibilityLabel="More information" />
</Tooltip>
```

Render `s-tooltip` with a stable `id`, then set `interestFor` to that ID on the trigger. Keep `accessibilityLabel` on an icon-only button; the tooltip supplements the control rather than naming it.

***

## Replace Tooltip properties

| Polaris React | Polaris web components | Migration notes |
| - | - | - |
| `content` | Text content of `s-tooltip` | Keep it to a short phrase or sentence. |
| Wrapped child | Trigger with `interestFor="tooltip-id"` | The tooltip and trigger can be siblings. |
| `id` | `id` on `s-tooltip` | Make it unique in the document. |
| `dismissOnMouseOut` | Destination behavior | Don't add custom hover timers. |
| `preferredPosition`, `activatorWrapper`, and width props | Remove | Placement is automatic. |
| Rich or interactive content | Visible content, `s-popover`, or a help section | Tooltips can't contain links or buttons. |

Move field requirements to `details`, errors to `error`, and explanations needed on mobile to visible text. If removing the tooltip makes the interface unclear, improve the visible label first.

***

## Test the migration

* Trigger with mouse hover and keyboard focus, then move focus away.
* Verify the owning control remains understandable without the tooltip.
* Test touch layouts with the tooltip unavailable.
* Check long translations and high zoom; move long content visible when needed.
* Confirm icon-only buttons have an independent accessible name.

***

## Remove Polaris React

Remove `Tooltip`, wrapper elements used only as activators, and tooltip positioning props. Remove `@shopify/polaris` only after no other route in scope imports it.

***

## Related guidance

* [Tooltip component](https://shopify.dev/docs/api/app-home/web-components/typography-and-content/tooltip)
* [Migrate InlineError from Polaris React](https://shopify.dev/docs/apps/build/app-home/migrate-from-polaris-react/inline-error)

***