Migrate Link to the Polaris link component

The Polaris link component makes text interactive for navigation and link-triggered actions. It replaces the previous Link component and is available as <s-link> in API versions 2025-10 and newer.

Anchor to Updated propertiesUpdated properties

The following properties are different in the Polaris link component.

Anchor to toto

The previous Link to prop is now called href.

target defaults to 'auto', which automatically opens external links in a new window so customers stay on the current page — no extra code needed. Set target="_blank" only when you want to force an internal link to open in a new window.

Anchor to languagelanguage

The previous Link language prop is now called lang.

Anchor to appearanceappearance

The previous Link appearance prop is now called tone.

import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default function extension() {
  render(<Extension />, document.body);
}

function Extension() {
  return (
    <s-link href="/terms" tone="auto">
      Terms and conditions
    </s-link>
  );
}

import {
  reactExtension,
  Link,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.block.render',
  () => <Extension />,
);

function Extension() {
  return (
    <Link to="/terms" appearance="monochrome">
      Terms and conditions
    </Link>
  );
}

Anchor to onPressonPress

The previous Link onPress prop is now called onClick.

import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default function extension() {
  render(<Extension />, document.body);
}

function Extension() {
  return <s-link onClick={() => console.log('Clicked')}>Learn more</s-link>;
}

import {
  reactExtension,
  Link,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.block.render',
  () => <Extension />,
);

function Extension() {
  return <Link onPress={() => console.log('Clicked')}>Learn more</Link>;
}

Anchor to externalexternal

The previous Link external prop has been replaced with target.

Anchor to New propertiesNew properties

The Polaris link component introduces the following new properties:

Anchor to Removed propertiesRemoved properties

Anchor to activateAction and activateTargetactivateAction and activateTarget

The previous Link activateAction and activateTarget props have been replaced with command and commandFor.

import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default function extension() {
  render(<Extension />, document.body);
}

function Extension() {
  return (
    <>
      <s-link command="--copy" commandFor="promo-code">
        Copy promo code
      </s-link>
      <s-clipboard-item id="promo-code" text="SAVE20"></s-clipboard-item>
    </>
  );
}

import {
  ClipboardItem,
  reactExtension,
  Link,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.block.render',
  () => <Extension />,
);

function Extension() {
  return (
    <>
      <Link activateAction="copy" activateTarget="promo-code">
        Copy promo code
      </Link>
      <ClipboardItem id="promo-code" text="SAVE20" />
    </>
  );
}

Anchor to overlayoverlay

The Polaris link component no longer supports overlay directly. To open a modal overlay, use commandFor with command and target s-modal.

import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default function extension() {
  render(<Extension />, document.body);
}

function Extension() {
  return (
    <>
      <s-link command="--show" commandFor="details-modal">
        View details
      </s-link>
      <s-modal id="details-modal" heading="Order details">
        <s-text>Your order includes free shipping on all items.</s-text>
      </s-modal>
    </>
  );
}

import {
  Link,
  Modal,
  Text,
  reactExtension,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.block.render',
  () => <Extension />,
);

function Extension() {
  return (
    <Link
      overlay={
        <Modal title="Order details">
          <Text>Your order includes free shipping on all items.</Text>
        </Modal>
      }
    >
      View details
    </Link>
  );
}

Anchor to togglestoggles

The previous Link toggles prop was used to expand or collapse content in Disclosure. In Polaris, use s-details with s-summary for expandable content instead of a link trigger.

import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default function extension() {
  render(<Extension />, document.body);
}

function Extension() {
  return (
    <s-details>
      <s-summary>View shipping details</s-summary>
      <s-text>Ships within 3 to 5 business days.</s-text>
    </s-details>
  );
}

import {
  reactExtension,
  Disclosure,
  Link,
  Text,
  View,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.block.render',
  () => <Extension />,
);

function Extension() {
  return (
    <Disclosure>
      <Link toggles="shipping-details">View shipping details</Link>
      <View id="shipping-details">
        <Text>Ships within 3 to 5 business days.</Text>
      </View>
    </Disclosure>
  );
}