Migrate Labelled from Polaris React

Polaris React Labelled combines a label, help text, validation, required state, and an optional action around a custom control. Prefer a Polaris web-component field that owns those relationships directly.

Anchor to Migrate labelled field contentMigrate labelled field content

Migrating labelled field guidance and errors

import {useState} from 'react';

export function BrandColor() {

const [color, setColor] = useState('#008060');

return (

<s-grid gridTemplateColumns="1fr auto" gap="small" alignItems="start">

<s-color-field

label="Brand color"

name="brandColor"

value={color}

details="Used for buttons and links"

required

onChange={(event) => setColor(event.currentTarget.value)}

></s-color-field>

<s-button variant="tertiary" onClick={() => setColor('#008060')}>

Reset

</s-button>

</s-grid>

);

}

import {useState} from 'react';

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

export function BrandColor() {

const [color, setColor] = useState('#008060');

return (

<Labelled

id="brand-color"

label="Brand color"

helpText="Used for buttons and links"

requiredIndicator

action={{content: 'Reset', onAction: () => setColor('#008060')}}

<TextField

label="Brand color value"

labelHidden

value={color}

onChange={setColor}

autoComplete="off"

</Labelled>

);

}

Polaris web components

import {useState} from 'react';

export function BrandColor() {
  const [color, setColor] = useState('#008060');

  return (
    <s-grid gridTemplateColumns="1fr auto" gap="small" alignItems="start">
      <s-color-field
        label="Brand color"
        name="brandColor"
        value={color}
        details="Used for buttons and links"
        required
        onChange={(event) => setColor(event.currentTarget.value)}
      ></s-color-field>
      <s-button variant="tertiary" onClick={() => setColor('#008060')}>
        Reset
      </s-button>
    </s-grid>
  );
}

Polaris React

import {useState} from 'react';
import {Labelled, TextField} from '@shopify/polaris';

export function BrandColor() {
  const [color, setColor] = useState('#008060');

  return (
    <Labelled
      id="brand-color"
      label="Brand color"
      helpText="Used for buttons and links"
      requiredIndicator
      action={{content: 'Reset', onAction: () => setColor('#008060')}}
    >
      <TextField
        label="Brand color value"
        labelHidden
        value={color}
        onChange={setColor}
        autoComplete="off"
      />
    </Labelled>
  );
}

Preview

Anchor to Replace Labelled propertiesReplace Labelled properties

Polaris React	Polaris web components	Migration notes
`label`	`label` on the field or choice list	Rewrite React-node labels as concise text.
`helpText`	`details` on the field or `s-text slot="details"` on a choice	Keep help with the value or option it describes.
`error`	`error` on the field or field group	Replace boolean-only errors with an actionable message.
`requiredIndicator`	`required` on the field	Keep indication and validation behavior together.
`labelHidden`	`labelAccessibilityVisibility="exclusive"` where supported	Keep the accessible label.
`disabled` and `readOnly`	`disabled` and `readOnly` on the field	Preserve which state the business rule requires.
`action`	A separate `s-button` beside the field	Keep the action outside the label and give it a self-contained name.
`id`	Remove unless app logic needs it	The field component owns its internal accessible relationships.
`children`	The destination field or complete custom composite	Don't wrap a labelled field with a second label.

For a label action such as Reset, use s-grid with the field and an adjacent button. The button should say what it resets, such as Reset brand color, in visible text or accessibilityLabel.

If no destination field fits, rebuild the custom composite with native fieldset and legend when it represents a group. Connect help and errors programmatically and verify the accessibility tree before removing Labelled.

Anchor to Test the migrationTest the migration

Verify label, details, and error are exposed with the intended control or group.
Exercise required, optional, disabled, read-only, valid, and invalid states.
Run the adjacent action and confirm it updates both the displayed and submitted value.
Test long translated labels, details, and errors at narrow widths.
Check focus order so label actions don't interrupt the control unexpectedly.

Anchor to Remove Polaris ReactRemove Polaris React

After each destination owns its field relationships, remove Labelled, errorID, helpTextID, and compatibility wrappers. Remove @shopify/polaris only after no other route in scope imports it.

Anchor to Related guidanceRelated guidance

Was this page helpful?