Migrate Tooltip from Polaris React
Replace Polaris React Tooltip with s-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.
Migrating an icon-button tooltip
Polaris web components
<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
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>Preview
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.
Anchor to Replace Tooltip propertiesReplace 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.
Anchor to Test the migrationTest 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.
Anchor to Remove Polaris ReactRemove 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.