Migrate to the Polaris phone field component

The Polaris phone field component renders a phone number input with country code formatting. It replaces the previous PhoneField component and is available as <s-phone-field> in API versions 2025-10 and newer.

Anchor to Updated propertiesUpdated properties

The following properties are different in the Polaris phone field component.

Anchor to readonlyreadonly

The previous PhoneField readonly prop is now called readOnly (camelCase).

Anchor to accessoryaccessory

The previous PhoneField accessory prop has been replaced with the accessory slot. Place an element with slot="accessory" as a child of the phone field.

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

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

function Extension() {
  return (
    <s-phone-field label="Phone">
      <s-icon slot="accessory" type="info" />
    </s-phone-field>
  );
}

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

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

function Extension() {
  return (
    <PhoneField
      label="Phone"
      accessory={<Icon source="info" />}
    />
  );
}

Anchor to Removed propertiesRemoved properties

The following properties aren't supported:

• accessibilityDescription — no longer supported as a separate prop. If you used it to give the field a screen-reader-only descriptive name, set a more descriptive label and hide it visually with labelAccessibilityVisibility="exclusive". There's no direct replacement for adding a separate description alongside a visible label.
• icon — no longer supported as a prop. For a trailing icon (the previous icon={{source: '...', position: 'end'}}), use the accessory slot instead (see the accessory example above) — it only renders at the end of the field. A leading-position icon (the previous default) has no direct equivalent; place an icon next to the field using layout components, or omit it.
• maxLength — no longer supported.

Anchor to New propertiesNew properties

The Polaris phone field component introduces the following new properties: