Migrate UnstyledLink from Polaris React

Use a native a or s-clickable with a real href for navigation. Preserve modified-click and open-in-new-tab behavior.

Anchor to Choose the destinationChoose the destination

Polaris React	Polaris web components	Migration type
`UnstyledLink`	Native `a` or `s-clickable` with `href`	Native HTML

Anchor to Map unstyled-link behaviorMap unstyled-link behavior

Polaris React	Polaris web components	Migration notes
`url`	`href`	Keep a real URL so modified clicks, copied links, and browser history work.
`external`	`target="_blank"` only when required	Make the destination clear when opening a new tab could surprise users.
`onClick` used for routing and `accessibilityLabel`	Router-aware anchor behavior and descriptive link text	Don't cancel modified clicks or repeat ambiguous labels such as "Learn more".

Anchor to Migrate the call siteMigrate the call site

Choose the native element whose semantics match the UnstyledLink call site.
Rebuild its accessible name and relationships before adding layout or app-owned styling.
When the element is interactive or form-associated, connect its native events and form behavior to existing app state.
After verification, remove the UnstyledLink import and any Polaris-only state, wrappers, or helpers that no longer have a caller.

Anchor to Preserve these behaviorsPreserve these behaviors

Native semantics, accessible names, and document structure.
Keyboard and form behavior supplied by the browser, where applicable.
App state, validation, and responsive layout around the element.

Anchor to Test and remove Polaris ReactTest and remove Polaris React

Test the migrated UnstyledLink with browser and accessibility semantics in mind. Verify document structure, keyboard and form behavior where applicable, accessible relationships, and app-owned state changes.

Don't remove @shopify/polaris while another component still imports it. Once all call sites are migrated, remove the package and its provider-level setup, then run the app's full test suite.

Anchor to Migration exampleMigration example

Migrating UnstyledLink

export function UnstyledLinkMigrationExample() {

return (

<><a href="#">Custom link</a></>

);

}

import {UnstyledLink} from '@shopify/polaris';

export function UnstyledLinkMigrationExample() {

return (

<UnstyledLink url="#">Custom link</UnstyledLink>

);

}

Polaris web components

export function UnstyledLinkMigrationExample() {
  return (
    <><a href="#">Custom link</a></>
  );
}

Polaris React

import {UnstyledLink} from '@shopify/polaris';


export function UnstyledLinkMigrationExample() {

  return (
    <UnstyledLink url="#">Custom link</UnstyledLink>
  );
}

Preview

Was this page helpful?