Migrate ColorPicker from Polaris React

Replace Polaris React ColorPicker with s-color-picker when visual selection is the task. Use s-color-field when a labelled color value belongs in a form or merchants should paste a value.

The value shape changes during this migration: Polaris React uses an HSB object, while the web components accept CSS color strings and emit hex values on change.

If the app renders this controlled field through React, upgrade to React 19 first. React 18 doesn't provide the custom-element property and event behavior this example relies on. If you can't upgrade yet, leave the controlled Polaris React field in place during this migration slice.

Anchor to Migrate a visual color pickerMigrate a visual color picker

Migrating an alpha-enabled color picker

<s-box padding="large" border="base" borderRadius="base">

<s-color-picker

value="#FF0000FF"

alpha

name="color-with-alpha"

></s-color-picker>

</s-box>

import {ColorPicker} from '@shopify/polaris';

export function BrandColor({color, setColor}) {

return (

<ColorPicker

id="brand-color"

color={color}

allowAlpha

fullWidth

onChange={setColor}

);

}

Polaris web components

<s-box padding="large" border="base" borderRadius="base">
  <s-color-picker
    value="#FF0000FF"
    alpha
    name="color-with-alpha"
  ></s-color-picker>
</s-box>

Polaris React

import {ColorPicker} from '@shopify/polaris';

export function BrandColor({color, setColor}) {
  return (
    <ColorPicker
      id="brand-color"
      color={color}
      allowAlpha
      fullWidth
      onChange={setColor}
    />
  );
}

Preview

Anchor to Replace ColorPicker propertiesReplace ColorPicker properties

Polaris React	Polaris web components	Migration notes
`color` HSB or HSBA object	`value` CSS color string	Normalize stored state to hex, RGB(A), or HSL(A).
`onChange(color)`	`onChange(event)`	Read `event.currentTarget.value`; change events emit hex format.
`allowAlpha`	`alpha`	Use an eight-digit hex value when transparency must round-trip.
`id`	`id` when app logic needs an element reference	Add `name` when the value submits with a form.
`fullWidth`	Containing layout	Let `s-grid`, `s-box`, or the page define available width.

Don't pass the old {hue, saturation, brightness, alpha} object to value. Convert existing saved data at the boundary or migrate the stored format. Test conversion in both directions before switching the form.

Polaris React alpha is a number from 0 to 1. An eight-digit hex color stores alpha as 00 through FF. Use a tested color conversion utility rather than hand-rolled rounding at each call site.

Anchor to Choose picker or fieldChoose picker or field

Use s-color-picker when seeing hue and saturation in context helps the merchant. It doesn't replace the surrounding field label and instructions; keep a visible heading or text that identifies the setting.

Use s-color-field for a normal settings form. It supports label, name, details, required, and error, and lets merchants type or paste supported CSS color formats. Add alpha only when the product and storage format support transparency.

Anchor to Validate and persist the valueValidate and persist the value

Treat an empty value emitted from invalid input as invalid. Preserve the merchant's draft, show an actionable field error, and don't save a fallback color silently.

If a backend expects HSB, convert the web component's normalized hex value once in the submit layer. If other surfaces consume the color, verify that they agree on alpha, gamut, capitalization, and shorthand expansion.

Anchor to Test the migrationTest the migration

Select hue, saturation, brightness, and alpha boundary values.
Type or paste every supported format when using s-color-field.
Round-trip existing stored colors through load, edit, submit, and reload.
Trigger invalid input and verify the previous saved value isn't overwritten.
Test keyboard operation, visible context, form reset, and narrow layout.

Anchor to Remove Polaris ReactRemove Polaris React

After every color workflow uses the new string format, remove ColorPicker, HSB-only state adapters, and @shopify/polaris color utilities with no remaining callers. Remove @shopify/polaris only after no other route in scope imports it.

Anchor to Related guidanceRelated guidance

Was this page helpful?