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:

EmailField

The EmailField component provides a text input optimized for email addresses. It displays an email-appropriate virtual keyboard on mobile devices and supports email-specific autocomplete hints.

For general text input, use TextField.

Support

Targets (46)

Supported targets

Anchor to PropertiesProperties

Props for the EmailField component, a text input optimized for email addresses. It inherits common input props (like label, value, onChange, and error) from InputProps, length validation from MinMaxLengthProps, and browser autofill hints from AutocompleteProps.

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 Collect notification emailCollect notification email

Set a low-stock notification email address and save it. This example uses EmailField to capture the address, with a Button that saves the notification email.

Collect notification email

Set a low-stock notification email address and save it. This example uses `EmailField` to capture the address, with a [Button](/docs/api/admin-extensions/2025-07/ui-components/actions/button) that saves the notification email.

Collect notification email

import {useState} from 'react';

import {reactExtension, useApi, EmailField, 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 [email, setEmail] = useState('');

return (

<Text fontWeight="bold">Notification settings</Text>

<EmailField

label="Low stock notification email"

name="notificationEmail"

value={email}

onChange={setEmail}

<Button

variant="primary"

onPress={async () => {

await fetch('/api/notifications/email', {

method: 'POST',

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

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

});

close();

}}

Save notification email

</Button>

</BlockStack>

);

}

export default reactExtension(

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

() => <App />,

);

import {extension, EmailField, 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 email = '';

const stack = root.createComponent(BlockStack);

const heading = root.createComponent(

Text,

{fontWeight: 'bold'},

'Notification settings',

);

const field = root.createComponent(EmailField, {

label: 'Low stock notification email',

onChange: (value) => {

email = value;

});

const saveButton = root.createComponent(

Button,

{

variant: 'primary',

onPress: async () => {

await fetch('/api/notifications/email', {

method: 'POST',

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

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

});

close();

'Save notification email',

);

stack.appendChild(heading);

stack.appendChild(field);

stack.appendChild(saveButton);

root.appendChild(stack);

);

React

import {useState} from 'react';
import {reactExtension, useApi, EmailField, 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 [email, setEmail] = useState('');

  return (
    <BlockStack>
      <Text fontWeight="bold">Notification settings</Text>
      <EmailField
        label="Low stock notification email"
        name="notificationEmail"
        value={email}
        onChange={setEmail}
      />
      <Button
        variant="primary"
        onPress={async () => {
          await fetch('/api/notifications/email', {
            method: 'POST',
            headers: {'Content-Type': 'application/json'},
            body: JSON.stringify({productId, email}),
          });
          close();
        }}
      >
        Save notification email
      </Button>
    </BlockStack>
  );
}

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

TS

import {extension, EmailField, 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 email = '';

    const stack = root.createComponent(BlockStack);

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

    const field = root.createComponent(EmailField, {
      label: 'Low stock notification email',
      name: 'notificationEmail',
      onChange: (value) => {
        email = value;
      },
    });

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

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

Anchor to Validate email format inlineValidate email format inline

Validate email format on each keystroke using the error prop and required attribute. This example checks for the presence of an @ symbol as the merchant types and displays an inline error message, preventing invalid email addresses from being saved.

Validate email format inline

import {useState} from 'react';

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

function App() {

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

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

const [email, setEmail] = useState('');

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

return (

<EmailField

label="Supplier contact email"

name="supplierEmail"

required

value={email}

error={error}

onChange={(value) => {

setEmail(value);

setError(

value && !value.includes('@')

? 'Enter a valid email address'

: undefined,

);

}}

<Button

variant="primary"

onPress={async () => {

if (email.includes('@')) {

await fetch('/api/suppliers/contact', {

method: 'POST',

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

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

});

close();

}

}}

Save supplier contact

</Button>

</BlockStack>

);

}

export default reactExtension(

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

() => <App />,

);

import {extension, EmailField, Button, BlockStack} 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 supplierEmail = '';

const stack = root.createComponent(BlockStack);

const field = root.createComponent(EmailField, {

label: 'Supplier contact email',

required: true,

onChange: (value) => {

supplierEmail = value;

if (value && !value.includes('@')) {

field.updateProps({error: 'Enter a valid email address'});

} else {

field.updateProps({error: undefined});

}

});

const saveButton = root.createComponent(

Button,

{

variant: 'primary',

onPress: async () => {

if (supplierEmail.includes('@')) {

await fetch('/api/suppliers/contact', {

method: 'POST',

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

body: JSON.stringify({productId, email: supplierEmail}),

});

close();

}

'Save supplier contact',

);

stack.appendChild(field);

stack.appendChild(saveButton);

root.appendChild(stack);

);

React

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

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

  return (
    <BlockStack>
      <EmailField
        label="Supplier contact email"
        name="supplierEmail"
        required
        value={email}
        error={error}
        onChange={(value) => {
          setEmail(value);
          setError(
            value && !value.includes('@')
              ? 'Enter a valid email address'
              : undefined,
          );
        }}
      />
      <Button
        variant="primary"
        onPress={async () => {
          if (email.includes('@')) {
            await fetch('/api/suppliers/contact', {
              method: 'POST',
              headers: {'Content-Type': 'application/json'},
              body: JSON.stringify({productId, email}),
            });
            close();
          }
        }}
      >
        Save supplier contact
      </Button>
    </BlockStack>
  );
}

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

TS

import {extension, EmailField, Button, BlockStack} 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 supplierEmail = '';

    const stack = root.createComponent(BlockStack);

    const field = root.createComponent(EmailField, {
      label: 'Supplier contact email',
      name: 'supplierEmail',
      required: true,
      onChange: (value) => {
        supplierEmail = value;
        if (value && !value.includes('@')) {
          field.updateProps({error: 'Enter a valid email address'});
        } else {
          field.updateProps({error: undefined});
        }
      },
    });

    const saveButton = root.createComponent(
      Button,
      {
        variant: 'primary',
        onPress: async () => {
          if (supplierEmail.includes('@')) {
            await fetch('/api/suppliers/contact', {
              method: 'POST',
              headers: {'Content-Type': 'application/json'},
              body: JSON.stringify({productId, email: supplierEmail}),
            });
            close();
          }
        },
      },
      'Save supplier contact',
    );

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

Anchor to Pre-fill contact form fieldsPre-fill contact form fields

Pre-fill an email field with a default value using the value prop for edit workflows. This example combines an EmailField with a TextField to build a complete fulfillment contact form, with a primary email pre-populated and an optional CC field.

Pre-fill contact form fields

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

function App() {

return (

<Text fontWeight="bold">Fulfillment contact</Text>

<EmailField

label="Contact email"

name="contactEmail"

value="fulfillment@example.com"

</BlockStack>

);

}

export default reactExtension(

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

() => <App />,

);

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

export default extension(

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

(root) => {

const stack = root.createComponent(BlockStack);

const heading = root.createComponent(

Text,

{fontWeight: 'bold'},

'Fulfillment contact',

);

const nameField = root.createComponent(TextField, {

label: 'Contact name',

});

const emailField = root.createComponent(EmailField, {

label: 'Contact email',

value: 'fulfillment@example.com',

disabled: false,

});

const ccField = root.createComponent(EmailField, {

label: 'CC email (optional)',

});

stack.appendChild(heading);

stack.appendChild(nameField);

stack.appendChild(emailField);

stack.appendChild(ccField);

root.appendChild(stack);

);

React

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

function App() {

  return (
    <BlockStack>
      <Text fontWeight="bold">Fulfillment contact</Text>
      <TextField label="Contact name" name="contactName" />
      <EmailField
        label="Contact email"
        name="contactEmail"
        value="fulfillment@example.com"
      />
      <EmailField label="CC email (optional)" name="ccEmail" />
    </BlockStack>
  );
}

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

TS

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

export default extension(
  'admin.product-details.action.render',
  (root) => {

    const stack = root.createComponent(BlockStack);

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

    const nameField = root.createComponent(TextField, {
      label: 'Contact name',
      name: 'contactName',
    });

    const emailField = root.createComponent(EmailField, {
      label: 'Contact email',
      name: 'contactEmail',
      value: 'fulfillment@example.com',
      disabled: false,
    });

    const ccField = root.createComponent(EmailField, {
      label: 'CC email (optional)',
      name: 'ccEmail',
    });

    stack.appendChild(heading);
    stack.appendChild(nameField);
    stack.appendChild(emailField);
    stack.appendChild(ccField);
    root.appendChild(stack);
  },
);

Anchor to Best practicesBest practices

Use EmailField instead of TextField for email input: EmailField triggers an email-optimized keyboard on mobile devices and supports email-specific autocomplete, reducing input friction.
Validate on blur, not on every keystroke: Use the onBlur callback to trigger validation after the merchant finishes typing, rather than showing errors as they type.

Anchor to LimitationsLimitations

EmailField doesn't perform built-in email validation. The error prop is purely visual. You must validate the email format yourself and set the error prop accordingly.
The component doesn't support multiple email addresses in a single field. For multiple recipients, render multiple EmailField components or use a custom pattern.
EmailField doesn't display an email icon or prefix. It renders as a plain text input that differs from TextField only in its virtual keyboard and autocomplete behavior.

Was this page helpful?