---
title: Migrate to the Polaris phone field component
description: >-
  Learn how to migrate the PhoneField 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/phone-field
  md: >-
    https://shopify.dev/docs/apps/build/checkout/migrate-to-web-components/phone-field.md
---

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

***

## Updated properties

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

### readonly

The previous `PhoneField` `readonly` prop is now called [`readOnly`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/forms/phone-field#properties-propertydetail-readonly) (camelCase).

### accessory

The previous `PhoneField` `accessory` prop has been replaced with the [`accessory`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/forms/phone-field#slots-propertydetail-accessory) slot. Place an element with `slot="accessory"` as a child of the phone field.

## Migrating accessory from prop to slot

##### Latest (Preact)

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

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

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

***

## Removed 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"`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/forms/phone-field#properties-propertydetail-labelaccessibilityvisibility). 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.

***

## New properties

The Polaris phone field component introduces the following new properties:

| New prop | Type | Description |
| - | - | - |
| [`defaultValue`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/forms/phone-field#properties-propertydetail-defaultvalue) | `string` | Initial value for uncontrolled usage. |
| [`labelAccessibilityVisibility`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/forms/phone-field#properties-propertydetail-labelaccessibilityvisibility) | `'visible'` \| `'exclusive'` | Controls visibility of the label. Default is `'visible'`. |
| [`type`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/forms/phone-field#properties-propertydetail-type) | `'mobile'` \| `''` | Phone number type hint for better formatting. |

***