Migrate InlineError from Polaris React

Don't replace Polaris React InlineError with unassociated red text. Put a field-specific message on the destination field's error property so the component renders and associates it with the control. Use s-banner for an error that affects the complete form or request.

Anchor to Migrate a field errorMigrate a field error

Migrating field validation errors

<s-text-field

label="SKU"

value="TSHIRT-001"

autocomplete="off"

error="SKU 'TSHIRT-001' already exists. SKUs must be unique across all products."

></s-text-field>

import {InlineError, TextField} from '@shopify/polaris';

export function SkuField({sku, setSku, error}) {

return (

<div>

<TextField

id="sku"

label="SKU"

value={sku}

onChange={setSku}

autoComplete="off"

{error && <InlineError fieldID="sku" message={error} />}

</div>

);

}

Polaris web components

<s-text-field
  label="SKU"
  value="TSHIRT-001"
  autocomplete="off"
  error="SKU 'TSHIRT-001' already exists. SKUs must be unique across all products."
></s-text-field>

Polaris React

import {InlineError, TextField} from '@shopify/polaris';

export function SkuField({sku, setSku, error}) {
  return (
    <div>
      <TextField
        id="sku"
        label="SKU"
        value={sku}
        onChange={setSku}
        autoComplete="off"
      />
      {error && <InlineError fieldID="sku" message={error} />}
    </div>
  );
}

Preview

Anchor to Replace InlineError propertiesReplace InlineError properties

Polaris React	Polaris web components	Migration notes
`message`	`error` on the field component	Keep the message actionable and specific.
`fieldID`	Remove when the field owns `error`	The destination field creates the accessible relationship.

For a custom composite control, render a stable error element and connect it with the control's supported accessible-description mechanism. Use native aria-describedby only on elements that accept it. Test the resulting accessibility tree; proximity alone doesn't associate an error.

Don't use an error tone for instructions, warnings, or optional help. Use details for persistent field guidance and s-banner with the appropriate tone for a broader status.

Anchor to Handle submit errorsHandle submit errors

Keep field errors keyed by stable field names. Clear an error when it has been corrected or after the next authoritative validation response, not merely when the field receives focus.

For a failed submission with multiple invalid fields, show a concise form-level summary, preserve all values, and focus the first invalid field or summary. Keep the specific message on every affected control.

Anchor to Test the migrationTest the migration

Trigger each validation rule and verify the message describes how to recover.
Confirm the relevant field exposes the error in its accessible description.
Submit multiple invalid fields and verify focus moves predictably.
Correct, resubmit, fail at the server, and retry without losing values.
Verify errors remain legible at narrow widths and high zoom.

Anchor to Remove Polaris ReactRemove Polaris React

After all errors are field-owned or intentionally form-level, remove InlineError, errorTextID, and manual IDs used only by it. Remove @shopify/polaris only after no other route in scope imports it.

Anchor to Related guidanceRelated guidance

Was this page helpful?