Migrate AccountConnection from Polaris React

The account connection pattern 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.

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

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

Anchor to Updated propertiesUpdated properties

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

Anchor to titletitle

Render title as an s-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.

Anchor to detailsdetails

Render supporting status or account details with s-text or s-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.

Anchor to termsOfServicetermsOfService

Render termsOfService below the account information and action row. Preserve links with s-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.

Anchor to accountNameaccountName

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.

Anchor to avatarUrlavatarUrl

When an avatar helps identify the connected account, render s-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.

Anchor to Removed propertiesRemoved properties

Anchor to connectedconnected

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

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.

Anchor to actionaction

Replace the Action descriptor object with an explicit s-button or s-link.

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.

Anchor to New responsibilitiesNew 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.

Anchor to Test the migrationTest 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.

Anchor to Related guidanceRelated guidance

• Account connection pattern
• Avatar component
• Modal component
• Migrate from Polaris React