---
title: Migrate to the Polaris icon component
description: >-
  Learn how to migrate the Icon component to Polaris web components in checkout
  and customer account UI extensions.
source_url:
  html: 'https://shopify.dev/docs/apps/build/checkout/migrate-to-web-components/icon'
  md: >-
    https://shopify.dev/docs/apps/build/checkout/migrate-to-web-components/icon.md
---

# Migrate to the Polaris icon component

The Polaris icon component displays small visual indicators and symbols. It replaces the previous [`Icon`](https://shopify.dev/docs/api/checkout-ui-extensions/2025-07/ui-components/media-and-visuals/icon) component and is available as [`<s-icon>`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/media-and-visuals/icon) in API versions 2025-10 and newer.

***

## Updated properties

The following properties are different in the Polaris icon component.

### source

The previous `Icon` `source` prop is now called [`type`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/media-and-visuals/icon#properties-propertydetail-type). Icon names have changed from camelCase to kebab-case, and some icons are renamed.

| Previous icon | New icon | Notes |
| - | - | - |
| `'arrowDown'` | `'arrow-down'` | |
| `'arrowLeft'` | `'arrow-left'` | |
| `'arrowRight'` | `'arrow-right'` | |
| `'arrowUp'` | `'arrow-up'` | |
| `'arrowUpRight'` | `'arrow-up-right'` | |
| `'bag'` | `'bag'` | |
| `'bullet'` | `'bullet'` | |
| `'calendar'` | `'calendar'` | |
| `'camera'` | `'camera'` | |
| `'caretDown'` | `'caret-down'` | |
| `'cart'` | `'cart'` | |
| `'cashDollar'` | `'cash-dollar'` | |
| `'categories'` | `'categories'` | |
| `'checkmark'` | `'check'` | Renamed. |
| `'chevronDown'` | `'chevron-down'` | |
| `'chevronLeft'` | `'chevron-left'` | |
| `'chevronRight'` | `'chevron-right'` | |
| `'chevronUp'` | `'chevron-up'` | |
| `'clipboard'` | `'clipboard'` | |
| `'clock'` | `'clock'` | |
| `'close'` | `'x'` | Renamed. |
| `'creditCard'` | `'credit-card'` | |
| `'critical'` | `'alert-circle'` | Renamed. |
| `'delete'` | `'delete'` | |
| `'delivered'` | `'delivered'` | |
| `'delivery'` | `'delivery'` | |
| `'disabled'` | `'disabled'` | |
| `'discount'` | `'discount'` | |
| `'email'` | `'email'` | |
| `'error'` | `'x-circle'` | Renamed. |
| `'errorFill'` | `'x-circle-filled'` | Renamed. |
| `'external'` | `'external'` | |
| `'filter'` | `'filter'` | |
| `'geolocation'` | `'geolocation'` | |
| `'gift'` | `'gift-card'` | Renamed. |
| `'giftFill'` | `'gift-card'` | No filled variant; maps to the same value as `'gift'`. |
| `'grid'` | `'grid'` | |
| `'hamburger'` | `'menu'` | Renamed. |
| `'hollowCircle'` | `'circle'` | Renamed. |
| `'horizontalDots'` | `'menu-horizontal'` | Renamed. |
| `'image'` | `'image'` | |
| `'info'` | `'info'` | |
| `'infoFill'` | `'info-filled'` | |
| `'list'` | `'list-bulleted'` | Renamed. |
| `'lock'` | `'lock'` | |
| `'magnify'` | `'search'` | Renamed. |
| `'map'` | `'map'` | |
| `'marker'` | `'location'` | Renamed. |
| `'minus'` | `'minus'` | |
| `'mobile'` | `'mobile'` | |
| `'note'` | `'note'` | |
| `'orderBox'` | `'order'` | Renamed. |
| `'pen'` | `'edit'` | Renamed. |
| `'plus'` | `'plus'` | |
| `'profile'` | `'profile'` | |
| `'question'` | `'question-circle'` | Renamed. |
| `'questionFill'` | `'question-circle-filled'` | Renamed. |
| `'reorder'` | `'reorder'` | |
| `'reset'` | `'reset'` | |
| `'return'` | `'return'` | |
| `'savings'` | `'savings'` | |
| `'settings'` | `'settings'` | |
| `'star'` | `'star'` | |
| `'starFill'` | `'star-filled'` | |
| `'starHalf'` | `'star-half'` | |
| `'store'` | `'store'` | |
| `'success'` | `'check-circle'` | Renamed. |
| `'truck'` | `'truck'` | |
| `'upload'` | `'upload'` | |
| `'verticalDots'` | `'menu-vertical'` | Renamed. |
| `'warning'` | `'alert-triangle'` | Renamed. |
| `'warningFill'` | `'alert-triangle-filled'` | Renamed. |

## Migrating source to type

##### Latest (Preact)

```tsx
import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default function extension() {
  render(<Extension />, document.body);
}

function Extension() {
  return (
    <>
      <s-icon type="check" />
      <s-icon type="arrow-left" />
    </>
  );
}
```

##### Pre-Polaris (2025-07)

```tsx
import {
  reactExtension,
  Icon,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.block.render',
  () => <Extension />,
);

function Extension() {
  return (
    <>
      <Icon source="checkmark" />
      <Icon source="arrowLeft" />
    </>
  );
}
```

### appearance

The previous `Icon` `appearance` prop is now called [`tone`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/media-and-visuals/icon#properties-propertydetail-tone).

| Previous value | New value | Migration notes |
| - | - | - |
| `'base'` | Removed | No direct replacement. `'auto'` adapts to the context where the icon is rendered. |
| `'subdued'` | Removed | No direct replacement. `'auto'` adapts to the context where the icon is rendered. |
| `'info'` | `'info'` | No change needed. |
| `'success'` | `'success'` | No change needed. |
| `'warning'` | `'warning'` | No change needed. |
| `'critical'` | `'critical'` | No change needed. |
| `'decorative'` | `'custom'` | Use `tone="custom"`. |
| `'interactive'` | Removed | No direct replacement. `'auto'` adapts to the context where the icon is rendered. |
| `'accent'` | Removed | No direct replacement. `'auto'` adapts to the context where the icon is rendered. |

## Migrating appearance to tone

##### Latest (Preact)

```tsx
import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default function extension() {
  render(<Extension />, document.body);
}

function Extension() {
  return <s-icon type="check" tone="success" />;
}
```

##### Pre-Polaris (2025-07)

```tsx
import {
  reactExtension,
  Icon,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.block.render',
  () => <Extension />,
);

function Extension() {
  return <Icon source="checkmark" appearance="success" />;
}
```

### size

The [`size`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/media-and-visuals/icon#properties-propertydetail-size) prop values have changed.

| Previous value | New value | Migration notes |
| - | - | - |
| `'extraSmall'` | `'small-200'` | Renamed. |
| `'small'` | `'small'` or `'small-100'` | `'small'` is an alias for `'small-100'`. |
| `'base'` | `'base'` | No change needed. |
| `'large'` | `'large'` or `'large-100'` | `'large'` is an alias for `'large-100'`. |
| `'fill'` | Removed | No equivalent in the Polaris icon component. |

For more on the scale system, see [Scale](https://shopify.dev/docs/api/checkout-ui-extensions/latest/using-polaris-components#scale).

***

## Removed properties

### accessibility​Label

The Polaris icon component no longer supports `accessibilityLabel` directly. To provide a screen-reader label, render a `<s-text accessibilityVisibility="exclusive">` next to the icon.

## Migrating accessibilityLabel

##### Latest (Preact)

```tsx
import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default function extension() {
  render(<Extension />, document.body);
}

function Extension() {
  return (
    <>
      <s-text accessibilityVisibility="exclusive">
        More information
      </s-text>
      <s-icon type="info" />
    </>
  );
}
```

##### Pre-Polaris (2025-07)

```tsx
import {
  reactExtension,
  Icon,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.block.render',
  () => <Extension />,
);

function Extension() {
  return <Icon source="info" accessibilityLabel="More information" />;
}
```

***