---
title: Migrate Link to the Polaris link component
description: >-
  Learn how to migrate the Link component to Polaris web components in checkout
  and customer account UI extensions.
source_url:
  html: 'https://shopify.dev/docs/apps/build/checkout/migrate-to-web-components/link'
  md: >-
    https://shopify.dev/docs/apps/build/checkout/migrate-to-web-components/link.md
---

# 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`](https://shopify.dev/docs/api/checkout-ui-extensions/2025-07/ui-components/actions/link) component and is available as [`<s-link>`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/actions/link) in API versions 2025-10 and newer.

***

## Updated properties

The following properties are different in the Polaris link component.

### to

The previous `Link` `to` prop is now called [`href`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/actions/link#properties-propertydetail-href).

[`target`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/actions/link#properties-propertydetail-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.

### language

The previous `Link` `language` prop is now called [`lang`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/actions/link#properties-propertydetail-lang).

### appearance

The previous `Link` `appearance` prop is now called [`tone`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/actions/link#properties-propertydetail-tone).

| Previous value | New value | Migration notes |
| - | - | - |
| `'monochrome'` | Removed | `monochrome` is no longer available and doesn't have a direct replacement. |
| N/A | `'auto'` | `auto` is a new tone value. The link color is contextualized based on where it's rendered, and it might appear monochrome in subdued text. |
| N/A | `'neutral'` | |

## Migrating appearance to tone

##### Latest (Preact)

```jsx
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>
  );
}
```

##### Pre-Polaris (2025-07)

```jsx
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>
  );
}
```

### on​Press

The previous `Link` `onPress` prop is now called [`onClick`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/actions/link#events-propertydetail-click).

## Migrating onPress to onClick

##### Latest (Preact)

```jsx
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>;
}
```

##### Pre-Polaris (2025-07)

```jsx
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>;
}
```

### external

The previous `Link` `external` prop has been replaced with [`target`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/actions/link#properties-propertydetail-target).

| Previous pattern | New pattern |
| - | - |
| `external={true}` | [`target`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/actions/link#properties-propertydetail-target)="\_blank" |
| `external={false}` or omitted | [`target`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/actions/link#properties-propertydetail-target)="auto" or omitted |

***

## New properties

The Polaris link component introduces the following new properties:

| New prop | Type | Description |
| - | - | - |
| [`command`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/actions/link#properties-propertydetail-command) | `'--auto'`, `'--toggle'`, `'--copy'`, `'--show'`, `'--hide'` | Sets the action to run when the link is activated. |
| [`commandFor`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/actions/link#properties-propertydetail-commandfor) | `string` | Sets the ID of the target component for the command. |
| [`interestFor`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/actions/link#properties-propertydetail-interestfor) | `string` | Sets the ID of the component that should respond to hover and focus. |
| [`target`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/actions/link#properties-propertydetail-target) | `'_blank'` \| `'auto'` | Controls where the link opens. |

***

## Removed properties

### activate​Action and activate​Target

The previous `Link` `activateAction` and `activateTarget` props have been replaced with [`command`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/actions/link#properties-propertydetail-command) and [`commandFor`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/actions/link#properties-propertydetail-commandfor).

| Previous pattern | New pattern | Migration notes |
| - | - | - |
| `activateAction="copy"` + `activateTarget="promo-code"` | [`command`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/actions/link#properties-propertydetail-command)="--copy" + [`commandFor`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/actions/link#properties-propertydetail-commandfor)="promo-code" | Copy behavior now uses the command pattern. |

## Migrating activateAction to command

##### Latest (Preact)

```jsx
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>
    </>
  );
}
```

##### Pre-Polaris (2025-07)

```jsx
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" />
    </>
  );
}
```

### overlay

The Polaris link component no longer supports `overlay` directly. To open a modal overlay, use [`commandFor`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/actions/link#properties-propertydetail-commandfor) with [`command`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/actions/link#properties-propertydetail-command) and target [`s-modal`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/overlays/modal).

## Migrating overlay to commandFor

##### Latest (Preact)

```jsx
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>
    </>
  );
}
```

##### Pre-Polaris (2025-07)

```jsx
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>
  );
}
```

### toggles

The previous `Link` `toggles` prop was used to expand or collapse content in `Disclosure`. In Polaris, use [`s-details`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/typography-and-content/details) with [`s-summary`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/typography-and-content/details#summary) for expandable content instead of a link trigger.

| Previous value | New pattern |
| - | - |
| `toggles="shipping-details"` | Use [`<s-details>`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/typography-and-content/details) with [`<s-summary>`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/typography-and-content/details#summary) and place the expandable content inside. |

## Migrating toggles to details

##### Latest (Preact)

```jsx
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>
  );
}
```

##### Pre-Polaris (2025-07)

```jsx
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>
  );
}
```

***