Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use web components, native UI elements with built-in accessibility, better performance, and consistent styling with Shopify's design system. Check out the migration guide to upgrade your extension.

Choose a version:

URLField

The URLField component provides a text input optimized for URL entry. It displays a URL-appropriate virtual keyboard on mobile devices and supports autocomplete hints for web addresses.

For general text input, use TextField.

Support

Targets (46)

Supported targets

Anchor to PropertiesProperties

Props for the URLField component, a text input optimized for entering URLs. It extends standard input props with min/max length constraints and autocomplete support for URL-related fields.

Anchor to label label string required: The text content to display as the field's label. This label is always required for accessibility as it tells users what information the field expects. The label is rendered visually above the field.
Anchor to autocomplete autocomplete | AutocompleteField | `${} ${AutocompleteField}` | `${} ${AutocompleteField}` | `${} ${} ${AutocompleteField}` | boolean: A hint to the browser about the expected content of the field, used to offer autofill suggestions.

true: The field supports autofill, but no specific content type is specified.

false: The field contains sensitive or ephemeral data that should not be autofilled, such as one-time codes.

An AutocompleteField token (such as 'email' or 'street-address'): Tells the browser exactly what data to suggest for this field.

Learn more about the supported autocomplete values.
Anchor to defaultValue defaultValue string | string[]: The initial value of the field when it isn't controlled by state. Use this instead of value when you don't need to manage the field's state yourself. The component tracks its own value internally and reports changes through onChange.
Anchor to disabled disabled boolean Default: false: Whether the field is disabled. When true, the field can't be edited by the user, won't receive focus, and won't be submitted with the form. Use this for fields that aren't relevant in the current context.
Anchor to error error string: An error message to display below the field. When set, the field receives a specific stylistic treatment (typically a red border) to communicate problems that have to be resolved immediately. The string value is displayed as the error message.

Pass undefined or omit this prop to clear the error state.
Anchor to id id string: A unique identifier for the field.
Anchor to maxLength maxLength number: The maximum number of characters the user can enter. If the current value exceeds this limit, then the field will be in an error state. This doesn't prevent the user from typing beyond the limit. Use the error prop to communicate the constraint.
Anchor to minLength minLength number: The minimum number of characters required for a valid input. If the current value is shorter than this limit, then the field will be in a validation error state. This doesn't prevent the user from submitting a shorter value. Use the error prop to communicate the constraint.
Anchor to name name string: An identifier for the field that is unique within the nearest containing Form component.
Anchor to onBlur onBlur () => void: A callback fired when the field loses focus. This is useful for triggering validation after the user finishes interacting with the field, or for tracking which fields have been "touched" in a form.
Anchor to onChange onChange (value: string) => void: A callback that fires when the user finishes editing the field, typically on blur. Only fires if the value changed. Update your state in this callback and pass the new value back through the value prop.

This doesn't fire on every keystroke. Use onInput for real-time responses like clearing validation errors as the user types. Don't use onInput to control value because that can cause issues on lower-powered devices due to asynchronous rendering.
Anchor to onFocus onFocus () => void: A callback fired when the field receives focus. This is useful for clearing errors, showing helper text, or tracking user interaction with form fields.
Anchor to onInput onInput (value: string) => void: A callback that fires on every change the user makes in the field, including each keystroke. The callback receives the current value.

Use onInput for immediate responses like clearing validation errors as the user types. Don't use it to control the field's value prop. Use onChange for that instead.
Anchor to placeholder placeholder string: A short hint displayed inside the field when it's empty. Use placeholder text to show an example of the expected value (such as "100" or "Search by name"). Don't use placeholder text as a substitute for the label as it disappears after the user starts typing.
Anchor to readOnly readOnly boolean Default: false: Whether the field is read-only. Unlike disabled, a read-only field can still receive focus and its value is included when the form is submitted. Use this when the value should be visible and selectable but not editable, such as a computed total.
Anchor to required required boolean: Whether the field needs a value. This requirement adds semantic value to the field, but it won't cause an error to appear automatically. If you want to present an error when this field is empty, you can do so with the error prop.
Anchor to value value T: The current value for the field. If omitted, then the field will be empty. You should update this value in response to the onChange callback.

AutocompleteSection

A section prefix that scopes autofill data to a specific area of the page. Use this when the same page contains multiple groups of fields that share the same autocomplete tokens, such as two separate shipping address forms. The value must follow the pattern `section-${name}`, for example `"section-shipping-1"`.

`section-${string}`

AutocompleteGroup

The contact information group the autocomplete data should be sourced from. - `shipping`: Autofill with the user's shipping address information. - `billing`: Autofill with the user's billing address information.

'shipping' | 'billing'

Anchor to ExamplesExamples

Anchor to Set external product source URLSet external product source URL

Record an external product source URL and save it from an action modal. This example uses URLField to capture the address, with a Button that saves the source URL.

Set external product source URL

Record an external product source URL and save it from an action modal. This example uses `URLField` to capture the address, with a [Button](/docs/api/admin-extensions/2025-07/ui-components/actions/button) that saves the source URL.

Set external product source URL

import {useState} from 'react';

import {reactExtension, useApi, URLField, Button, BlockStack, Text} from '@shopify/ui-extensions-react/admin';

function App() {

const {data, close} = useApi('admin.product-details.action.render');

const productId = data.selected[0]?.id;

const [url, setUrl] = useState('');

return (

<Text fontWeight="bold">External product source</Text>

<URLField

label="Source URL"

name="sourceUrl"

value={url}

onChange={setUrl}

<Button

variant="primary"

onPress={async () => {

await fetch('/api/products/source', {

method: 'POST',

headers: {'Content-Type': 'application/json'},

body: JSON.stringify({productId, sourceUrl: url}),

});

close();

}}

Save source URL

</Button>

</BlockStack>

);

}

export default reactExtension(

'admin.product-details.action.render',

() => <App />,

);

import {extension, URLField, Button, BlockStack, Text} from '@shopify/ui-extensions/admin';

export default extension(

'admin.product-details.action.render',

(root, api) => {

const {data, close} = api;

const productId = data.selected[0]?.id;

let sourceUrl = '';

const stack = root.createComponent(BlockStack);

const heading = root.createComponent(

Text,

{fontWeight: 'bold'},

'External product source',

);

const field = root.createComponent(URLField, {

label: 'Source URL',

onChange: (value) => {

sourceUrl = value;

});

const saveButton = root.createComponent(

Button,

{

variant: 'primary',

onPress: async () => {

await fetch('/api/products/source', {

method: 'POST',

headers: {'Content-Type': 'application/json'},

body: JSON.stringify({productId, sourceUrl}),

});

close();

'Save source URL',

);

stack.appendChild(heading);

stack.appendChild(field);

stack.appendChild(saveButton);

root.appendChild(stack);

);

React

import {useState} from 'react';
import {reactExtension, useApi, URLField, Button, BlockStack, Text} from '@shopify/ui-extensions-react/admin';

function App() {
  const {data, close} = useApi('admin.product-details.action.render');
  const productId = data.selected[0]?.id;
  const [url, setUrl] = useState('');

  return (
    <BlockStack>
      <Text fontWeight="bold">External product source</Text>
      <URLField
        label="Source URL"
        name="sourceUrl"
        value={url}
        onChange={setUrl}
      />
      <Button
        variant="primary"
        onPress={async () => {
          await fetch('/api/products/source', {
            method: 'POST',
            headers: {'Content-Type': 'application/json'},
            body: JSON.stringify({productId, sourceUrl: url}),
          });
          close();
        }}
      >
        Save source URL
      </Button>
    </BlockStack>
  );
}

export default reactExtension(
  'admin.product-details.action.render',
  () => <App />,
);

TS

import {extension, URLField, Button, BlockStack, Text} from '@shopify/ui-extensions/admin';

export default extension(
  'admin.product-details.action.render',
  (root, api) => {
    const {data, close} = api;
    const productId = data.selected[0]?.id;
    let sourceUrl = '';

    const stack = root.createComponent(BlockStack);

    const heading = root.createComponent(
      Text,
      {fontWeight: 'bold'},
      'External product source',
    );

    const field = root.createComponent(URLField, {
      label: 'Source URL',
      name: 'sourceUrl',
      onChange: (value) => {
        sourceUrl = value;
      },
    });

    const saveButton = root.createComponent(
      Button,
      {
        variant: 'primary',
        onPress: async () => {
          await fetch('/api/products/source', {
            method: 'POST',
            headers: {'Content-Type': 'application/json'},
            body: JSON.stringify({productId, sourceUrl}),
          });
          close();
        },
      },
      'Save source URL',
    );

    stack.appendChild(heading);
    stack.appendChild(field);
    stack.appendChild(saveButton);
    root.appendChild(stack);
  },
);

Anchor to Validate webhook endpoint protocolValidate webhook endpoint protocol

Validate that a webhook endpoint uses HTTPS using the error prop and required attribute. This example checks the URL protocol on each keystroke and displays an inline error for non-HTTPS URLs, so merchants can only register secure webhook endpoints.

Validate webhook endpoint protocol

import {useState} from 'react';

import {reactExtension, useApi, URLField, Button, BlockStack} from '@shopify/ui-extensions-react/admin';

function App() {

const {close} = useApi('admin.product-details.action.render');

const [endpoint, setEndpoint] = useState('');

const [error, setError] = useState(undefined);

return (

<URLField

label="Webhook endpoint URL"

name="webhookEndpoint"

required

value={endpoint}

error={error}

onChange={(value) => {

setEndpoint(value);

setError(

value && !value.startsWith('https://')

? 'Webhook endpoints must use HTTPS'

: undefined,

);

}}

<Button

variant="primary"

onPress={async () => {

if (endpoint.startsWith('https://')) {

await fetch('/api/webhooks/register', {

method: 'POST',

headers: {'Content-Type': 'application/json'},

body: JSON.stringify({endpoint}),

});

close();

}

}}

</Button>

</BlockStack>

);

}

export default reactExtension(

'admin.product-details.action.render',

() => <App />,

);

import {extension, URLField, Button, BlockStack} from '@shopify/ui-extensions/admin';

export default extension(

'admin.product-details.action.render',

(root, api) => {

const {close} = api;

let endpoint = '';

const stack = root.createComponent(BlockStack);

const field = root.createComponent(URLField, {

label: 'Webhook endpoint URL',

required: true,

onChange: (value) => {

endpoint = value;

if (value && !value.startsWith('https://')) {

field.updateProps({error: 'Webhook endpoints must use HTTPS'});

} else {

field.updateProps({error: undefined});

}

});

const saveButton = root.createComponent(

Button,

{

variant: 'primary',

onPress: async () => {

if (endpoint.startsWith('https://')) {

await fetch('/api/webhooks/register', {

method: 'POST',

headers: {'Content-Type': 'application/json'},

body: JSON.stringify({endpoint}),

});

close();

}

'Register webhook',

);

stack.appendChild(field);

stack.appendChild(saveButton);

root.appendChild(stack);

);

React

import {useState} from 'react';
import {reactExtension, useApi, URLField, Button, BlockStack} from '@shopify/ui-extensions-react/admin';

function App() {
  const {close} = useApi('admin.product-details.action.render');
  const [endpoint, setEndpoint] = useState('');
  const [error, setError] = useState(undefined);

  return (
    <BlockStack>
      <URLField
        label="Webhook endpoint URL"
        name="webhookEndpoint"
        required
        value={endpoint}
        error={error}
        onChange={(value) => {
          setEndpoint(value);
          setError(
            value && !value.startsWith('https://')
              ? 'Webhook endpoints must use HTTPS'
              : undefined,
          );
        }}
      />
      <Button
        variant="primary"
        onPress={async () => {
          if (endpoint.startsWith('https://')) {
            await fetch('/api/webhooks/register', {
              method: 'POST',
              headers: {'Content-Type': 'application/json'},
              body: JSON.stringify({endpoint}),
            });
            close();
          }
        }}
      >
        Register webhook
      </Button>
    </BlockStack>
  );
}

export default reactExtension(
  'admin.product-details.action.render',
  () => <App />,
);

TS

import {extension, URLField, Button, BlockStack} from '@shopify/ui-extensions/admin';

export default extension(
  'admin.product-details.action.render',
  (root, api) => {
    const {close} = api;
    let endpoint = '';

    const stack = root.createComponent(BlockStack);

    const field = root.createComponent(URLField, {
      label: 'Webhook endpoint URL',
      name: 'webhookEndpoint',
      required: true,
      onChange: (value) => {
        endpoint = value;
        if (value && !value.startsWith('https://')) {
          field.updateProps({error: 'Webhook endpoints must use HTTPS'});
        } else {
          field.updateProps({error: undefined});
        }
      },
    });

    const saveButton = root.createComponent(
      Button,
      {
        variant: 'primary',
        onPress: async () => {
          if (endpoint.startsWith('https://')) {
            await fetch('/api/webhooks/register', {
              method: 'POST',
              headers: {'Content-Type': 'application/json'},
              body: JSON.stringify({endpoint}),
            });
            close();
          }
        },
      },
      'Register webhook',
    );

    stack.appendChild(field);
    stack.appendChild(saveButton);
    root.appendChild(stack);
  },
);

Anchor to Pre-fill product storefront linkPre-fill product storefront link

Pre-populate a URL field with the product's storefront address using data.selected and the readOnly prop. This example shows the product storefront URL as a reference alongside an editable field for the external catalog link.

Pre-fill product storefront link

import {reactExtension, useApi, URLField, BlockStack, Text} from '@shopify/ui-extensions-react/admin';

function App() {

const {data} = useApi('admin.product-details.block.render');

const productId = data.selected[0]?.id;

const numericId = productId?.split('/').pop();

return (

<Text fontWeight="bold">Product links</Text>

<URLField

label="Storefront URL"

name="storefrontUrl"

value={`https://your-store.myshopify.com/products/${numericId}`}

readOnly

</BlockStack>

);

}

export default reactExtension(

'admin.product-details.block.render',

() => <App />,

);

import {extension, URLField, BlockStack, Text} from '@shopify/ui-extensions/admin';

export default extension(

'admin.product-details.block.render',

(root, api) => {

const {data} = api;

const productId = data.selected[0]?.id;

const numericId = productId?.split('/').pop();

const stack = root.createComponent(BlockStack);

const heading = root.createComponent(

Text,

{fontWeight: 'bold'},

'Product links',

);

const storefrontField = root.createComponent(URLField, {

label: 'Storefront URL',

value: `https://your-store.myshopify.com/products/${numericId}`,

readOnly: true,

});

const externalField = root.createComponent(URLField, {

label: 'External catalog URL',

});

stack.appendChild(heading);

stack.appendChild(storefrontField);

stack.appendChild(externalField);

root.appendChild(stack);

);

React

import {reactExtension, useApi, URLField, BlockStack, Text} from '@shopify/ui-extensions-react/admin';

function App() {
  const {data} = useApi('admin.product-details.block.render');
  const productId = data.selected[0]?.id;
  const numericId = productId?.split('/').pop();

  return (
    <BlockStack>
      <Text fontWeight="bold">Product links</Text>
      <URLField
        label="Storefront URL"
        name="storefrontUrl"
        value={`https://your-store.myshopify.com/products/${numericId}`}
        readOnly
      />
      <URLField label="External catalog URL" name="externalUrl" />
    </BlockStack>
  );
}

export default reactExtension(
  'admin.product-details.block.render',
  () => <App />,
);

TS

import {extension, URLField, BlockStack, Text} from '@shopify/ui-extensions/admin';

export default extension(
  'admin.product-details.block.render',
  (root, api) => {
    const {data} = api;
    const productId = data.selected[0]?.id;
    const numericId = productId?.split('/').pop();

    const stack = root.createComponent(BlockStack);

    const heading = root.createComponent(
      Text,
      {fontWeight: 'bold'},
      'Product links',
    );

    const storefrontField = root.createComponent(URLField, {
      label: 'Storefront URL',
      name: 'storefrontUrl',
      value: `https://your-store.myshopify.com/products/${numericId}`,
      readOnly: true,
    });

    const externalField = root.createComponent(URLField, {
      label: 'External catalog URL',
      name: 'externalUrl',
    });

    stack.appendChild(heading);
    stack.appendChild(storefrontField);
    stack.appendChild(externalField);
    root.appendChild(stack);
  },
);

Anchor to Best practicesBest practices

Use URLField instead of TextField for URLs: URLField triggers a URL-optimized keyboard on mobile devices that includes quick access to common characters like "/", ".", and ".com".
Provide a helpful placeholder: Use a placeholder like "https://example.com" to communicate the expected format without replacing the label.
Validate URL format on blur: Use the onBlur callback to check the URL format and set the error prop with a clear message like "Enter a valid URL starting with https://".

Anchor to LimitationsLimitations

URLField doesn't perform built-in URL validation. You must validate the format yourself and set the error prop accordingly.
The component doesn't automatically prepend "https://" to entered values. If you need a protocol prefix, validate and transform the value in your onChange handler.
URLField doesn't provide a clickable link preview or a way to test the entered URL. For URL verification, consider adding a separate Link or Button that opens the URL.

Was this page helpful?