Migrate Link from Polaris React
Replace Polaris React Link with s-link. Keep a real href so browser navigation, modified clicks, copying, and link announcements continue to work.
Anchor to Migrate an inline linkMigrate an inline link
Migrating links in content
Polaris web components
<s-text>Review the <s-link href="/app/products">products requiring attention</s-link>.</s-text>Polaris React
import {Link, Text} from '@shopify/polaris';
<Text as="p">
Review the <Link url="/app/products">products requiring attention</Link>.
</Text>Preview
Anchor to Replace Link propertiesReplace Link properties
| Polaris React | Polaris web components | Migration notes |
|---|---|---|
url | href | Preserve internal query strings and fragments. |
external | target="_blank" when the destination leaves the embedded app | Don't open internal app routes in a new tab. |
download | download | Keep href and verify response headers and filename. |
onClick | onClick only for navigation-related instrumentation or guards | Don't replace href with a client-side click handler. |
accessibilityLabel | accessibilityLabel only when visible text is insufficient | Prefer descriptive visible link text. |
monochrome and removeUnderline | Remove | Let context and the destination component own link appearance. |
dataPrimaryLink | Put the explicit resource link in the primary content | Don't make an entire row ambiguously clickable. |
Use s-button when the control mutates data, submits, or changes local UI without navigating. Text such as Click here or Learn more needs surrounding context to be meaningful; prefer link text that names the destination.
For navigation inside an embedded app, keep the app route in href and verify App Bridge routing, browser history, and unsaved-change protection. Before programmatic navigation with dirty state, use the Save Bar API's leave confirmation.
Anchor to Test the migrationTest the migration
- Open internal links normally and with modified or middle clicks.
- Verify external links and downloads use the intended target and response.
- Use browser back and forward navigation inside the embedded app.
- Check link purpose out of context with a screen reader.
- Confirm unsaved forms block or allow navigation according to product rules.
Anchor to Remove Polaris ReactRemove Polaris React
Remove Link, client-router adapters used only by Polaris, and click handlers that duplicated native navigation. Remove @shopify/polaris only after no other route in scope imports it.