---
title: Migrate AccountConnection from Polaris React
description: >-
  Learn how to migrate the Polaris React AccountConnection component to the
  Polaris web components account connection pattern.
source_url:
  html: >-
    https://shopify.dev/docs/apps/build/app-home/migrate-from-polaris-react/account-connection
  md: >-
    https://shopify.dev/docs/apps/build/app-home/migrate-from-polaris-react/account-connection.md
api_name: app-home
---

# Migrate Account​Connection from Polaris React

The [account connection pattern](https://shopify.dev/docs/api/app-home/patterns/compositions/account-connection) replaces the Polaris React `AccountConnection` component from `@shopify/polaris`. There isn't a single replacement component. Compose the connection status, account identity, terms, and actions with Polaris web components, and keep connection state in your app.

## Migrating AccountConnection

##### Polaris web components

```tsx
import {useState} from 'react';

export function AccountConnectionExample() {
  const [connected, setConnected] = useState(false);
  const accountName = connected ? 'Jane Appleseed' : '';
  const details = connected
    ? `Connected as ${accountName}`
    : 'No account connected';

  return (
    <s-section>
      <s-stack gap="base">
        <s-grid
          gridTemplateColumns="1fr auto"
          gap="base"
          alignItems="center"
        >
          <s-grid-item>
            <s-stack gap="small">
              <s-heading>Example App</s-heading>
              <s-text color="subdued">{details}</s-text>
            </s-stack>
          </s-grid-item>
          <s-grid-item>
            <s-button
              variant={connected ? 'secondary' : 'primary'}
              onClick={() => setConnected((value) => !value)}
            >
              {connected ? 'Disconnect' : 'Connect'}
            </s-button>
          </s-grid-item>
        </s-grid>
        {!connected && (
          <s-text>
            By clicking Connect, you agree to accept Sample App's{' '}
            <s-link href="/terms">terms and conditions</s-link>. You'll pay a
            commission rate of 15% on sales made through Sample App.
          </s-text>
        )}
      </s-stack>
    </s-section>
  );
}
```

##### Polaris React

```tsx
import {useCallback, useState} from 'react';
import {AccountConnection, Link} from '@shopify/polaris';

export function AccountConnectionExample() {
  const [connected, setConnected] = useState(false);
  const accountName = connected ? 'Jane Appleseed' : '';
  const handleAction = useCallback(() => {
    setConnected((value) => !value);
  }, []);
  const buttonText = connected ? 'Disconnect' : 'Connect';
  const details = connected
    ? 'Account connected'
    : 'No account connected';
  const terms = connected ? null : (
    <p>
      By clicking <strong>Connect</strong>, you agree to accept Sample App's{' '}
      <Link url="/terms">terms and conditions</Link>. You'll pay a commission
      rate of 15% on sales made through Sample App.
    </p>
  );

  return (
    <AccountConnection
      accountName={accountName}
      connected={connected}
      title="Example App"
      action={{content: buttonText, onAction: handleAction}}
      details={details}
      termsOfService={terms}
    />
  );
}
```

***

## Updated properties

The following `AccountConnection` properties move to elements in the account connection composition.

### title

Render `title` as an [`s-heading`](https://shopify.dev/docs/api/app-home/web-components/typography-and-content/heading) in the account-information column. If the previous value is a complex React node, preserve only content that belongs in the heading and move supporting content into the surrounding stack.

### details

Render supporting status or account details with [`s-text`](https://shopify.dev/docs/api/app-home/web-components/typography-and-content/text) or [`s-paragraph`](https://shopify.dev/docs/api/app-home/web-components/typography-and-content/paragraph). Use visible text such as **No account connected** or **Connected as <jane@example.com>** instead of relying on color or an avatar to communicate state.

### terms​Of​Service

Render `termsOfService` below the account information and action row. Preserve links with [`s-link`](https://shopify.dev/docs/api/app-home/web-components/actions/link), and keep the terms visible before the merchant connects.

Don't hide required terms in a tooltip or move them into an action's accessibility label.

### account​Name

`accountName` becomes app-owned data rather than a component property. Include it in visible connection details and use it to derive avatar initials or alternative text when an account identity is shown.

### avatar​Url

When an avatar helps identify the connected account, render [`s-avatar`](https://shopify.dev/docs/api/app-home/web-components/media-and-visuals/avatar) with `src`, `initials`, and meaningful `alt` text. Only render it when the account identity is known; don't use the avatar as the only indication that the account is connected.

***

## Removed properties

### connected

There is no `connected` property on the composition. Connection state controls the elements that render:

| Polaris React behavior | Polaris web components |
| - | - |
| `connected={false}` | Show disconnected status, the connect action, and any required terms. |
| `connected={true}` | Show the connected account identity, connected status, and disconnect action. |
| State changes | Update the composition from the result of the connection or disconnection operation. |

Don't optimistically show a connected state unless the operation can be rolled back safely. Keep pending and error state explicit, and restore the last confirmed state when an operation fails.

### action

Replace the `Action` descriptor object with an explicit [`s-button`](https://shopify.dev/docs/api/app-home/web-components/actions/button) or [`s-link`](https://shopify.dev/docs/api/app-home/web-components/actions/link).

| Polaris React `action` field | Polaris web components |
| - | - |
| `id` | `id` |
| `content` | Button or link text content |
| `accessibilityLabel` | `accessibilityLabel` |
| `url` | `href` on `s-link` |
| `external` or `target` | `target`, such as `target="_blank"` |
| `onAction` | `onClick` |
| `onMouseEnter` or `onTouchStart` | Keep a standard event handler only when the behavior is still required. |

Use a primary button for the initial connect action. Use a secondary button for disconnect. If disconnecting removes data, stops synchronization, or has another consequential result, [confirm it with a modal](https://shopify.dev/docs/api/app-home/patterns/compositions/account-connection#examples).

***

## New responsibilities

The Polaris React component arranged supplied content but didn't perform account operations. The migrated feature must continue to own:

* The confirmed connection state and connected account data.
* Pending state that prevents duplicate connect or disconnect requests.
* Error recovery when authentication, connection, or disconnection fails.
* Confirmation for consequential disconnection.
* Success feedback after the state is confirmed.

Keep these behaviors in the same feature slice as the rendered composition so the visible status can't drift from backend state.

***

## Test the migration

* Test disconnected, connecting, connected, disconnecting, and failed states.
* Confirm the account name and avatar identify the correct account.
* Verify terms remain visible and links retain normal browser navigation behavior.
* Test connect and disconnect actions with keyboard and screen-reader navigation.
* Verify a consequential disconnect requires confirmation and returns focus appropriately.
* Remove the `AccountConnection` import only after every call site uses the composition.

***

## Related guidance

* [Account connection pattern](https://shopify.dev/docs/api/app-home/patterns/compositions/account-connection)
* [Avatar component](https://shopify.dev/docs/api/app-home/web-components/media-and-visuals/avatar)
* [Modal component](https://shopify.dev/docs/api/app-home/web-components/overlays/modal)
* [Migrate from Polaris React](https://shopify.dev/docs/apps/build/app-home/migrate-from-polaris-react)

***