Migrate to the Polaris text field components

The previous TextField component has been split into dedicated components based on the type prop. Each type now has its own Polaris web component, available in API versions 2025-10 and newer.

Anchor to Component mapping by typeComponent mapping by type

The type prop you previously set on TextField determines which new component to use:

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

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

function Extension() {
  return (
    <s-email-field
      label="Email address"
    />
  );
}

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

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

function Extension() {
  return (
    <TextField
      label="Email address"
      type="email"
    />
  );
}

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

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

function Extension() {
  return (
    <s-number-field
      label="Quantity"
    />
  );
}

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

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

function Extension() {
  return (
    <TextField
      label="Quantity"
      type="number"
    />
  );
}

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

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

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

function Extension() {
  return (
    <TextField
      label="Phone number"
      type="telephone"
    />
  );
}

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

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

function Extension() {
  return (
    <s-text-area
      label="Order notes"
      rows={3}
    />
  );
}

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

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

function Extension() {
  return (
    <TextField
      label="Order notes"
      multiline={3}
    />
  );
}

Anchor to Updated propertiesUpdated properties

The following table summarizes which new components support the icon prop and the accessory slot:

Anchor to readonlyreadonly

The previous TextField readonly prop is now called readOnly (camelCase) on all field components.

Anchor to accessoryaccessory

The previous TextField accessory prop has been replaced with the accessory slot on <s-text-field>, <s-email-field>, <s-number-field>, <s-phone-field>, and <s-url-field>. Place an element with slot="accessory" as a child of the field. The accessory slot isn't available on <s-text-area> — to position supplementary content next to a text area, use layout components.

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

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

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

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

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

function Extension() {
  return (
    <TextField
      label="Search products"
      accessory={<Icon source="info" />}
    />
  );
}

Anchor to iconicon

The icon prop is supported only on <s-text-field> and <s-number-field>. On those components, update icon names to their Polaris web component equivalents — they use the same icon names as the Polaris icon component. The icon prop isn't available on <s-email-field>, <s-phone-field>, or <s-url-field>. For a trailing icon (the previous icon={{source: '...', position: 'end'}}), use the accessory slot — it only renders at the end of the field. A leading-position icon (the previous default) has no direct equivalent on those components; place an icon next to the field using layout components, or omit it.

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

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

function Extension() {
  return (
    <s-text-field
      label="Search products"
      icon="search"
    />
  );
}

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

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

function Extension() {
  return (
    <TextField
      label="Search products"
      icon="magnify"
    />
  );
}

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

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

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

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

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

function Extension() {
  return (
    <TextField
      label="Email address"
      type="email"
      icon={{source: 'info', position: 'end'}}
    />
  );
}

Anchor to Removed propertiesRemoved properties

The following properties aren't supported on any of the new field components:

• type — no longer needed. Use the dedicated component for your input type instead.
• multiline — no longer supported. Use <s-text-area> instead.
• accessibilityDescription — no longer supported. Use the label prop to provide context.
• controlledValue — no longer supported. Use the standard value management pattern.

Anchor to New propertiesNew properties

The new field components introduce the following properties: