---
title: Migrate ColorPicker from Polaris React
description: >-
  Replace Polaris React ColorPicker with s-color-picker or s-color-field and
  migrate HSB state to a documented CSS color string.
source_url:
  html: >-
    https://shopify.dev/docs/apps/build/app-home/migrate-from-polaris-react/color-picker
  md: >-
    https://shopify.dev/docs/apps/build/app-home/migrate-from-polaris-react/color-picker.md
api_name: app-home
---

# Migrate Color​Picker from Polaris React

Replace Polaris React `ColorPicker` with [`s-color-picker`](https://shopify.dev/docs/api/app-home/web-components/forms/color-picker) when visual selection is the task. Use [`s-color-field`](https://shopify.dev/docs/api/app-home/web-components/forms/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.

***

## Migrate a visual color picker

## Migrating an alpha-enabled color picker

##### Polaris web components

```html
<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

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

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

***

## Replace Color​Picker 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.

***

## Choose 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.

***

## Validate 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.

***

## Test 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.

***

## Remove 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.

***

## Related guidance

* [Color picker component](https://shopify.dev/docs/api/app-home/web-components/forms/color-picker)
* [Color field component](https://shopify.dev/docs/api/app-home/web-components/forms/color-field)
* [Migrate Labelled from Polaris React](https://shopify.dev/docs/apps/build/app-home/migrate-from-polaris-react/labelled)

***