---
title: Migrate Tag to Polaris chip components
description: >-
  Learn how to migrate the Tag 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/tag'
  md: >-
    https://shopify.dev/docs/apps/build/checkout/migrate-to-web-components/tag.md
---

# Migrate Tag to Polaris chip components

Polaris chip components display compact labels or categorization markers. They replace the previous [`Tag`](https://shopify.dev/docs/api/checkout-ui-extensions/2025-07/ui-components/other/tag) component and are available as [`<s-chip>`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/typography-and-content/chip) and [`<s-clickable-chip>`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/actions/clickable-chip) in API versions 2025-10 and newer.

Choose the replacement based on how the `Tag` is used:

| Previous pattern | New component | Migration notes |
| - | - | - |
| Display-only `Tag` (no `onRemove`) | [`<s-chip>`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/typography-and-content/chip) | Use for non-interactive labels and categorization markers. |
| `Tag` with `onRemove`, or that needs to be clickable or navigable | [`<s-clickable-chip>`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/actions/clickable-chip) | Use for removable, clickable, or linkable tags. |

***

## Updated properties

### icon

The previous `Tag` `icon` prop has been replaced with a [`graphic`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/typography-and-content/chip#slots-propertydetail-graphic) slot. Place an [`<s-icon>`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/media-and-visuals/icon) inside the chip with `slot="graphic"`. Only `<s-icon>` is supported in this slot.

When you move the icon name to `<s-icon type="...">`, update it to its Polaris web component equivalent. The chip uses the same icon names as the Polaris [icon](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/media-and-visuals/icon) component.

**Note:**

This table lists only icon values that need more than a camelCase-to-kebab-case rename. If an icon isn't listed here, then convert its previous camelCase name to kebab-case. For example, `arrowLeft` becomes `arrow-left`.

| Previous icon | New icon |
| - | - |
| `'checkmark'` | `'check'` |
| `'close'` | `'x'` |
| `'critical'` | `'alert-circle'` |
| `'error'` | `'x-circle'` |
| `'errorFill'` | `'x-circle-filled'` |
| `'gift'` | `'gift-card'` |
| `'giftFill'` | `'gift-card'` |
| `'hamburger'` | `'menu'` |
| `'hollowCircle'` | `'circle'` |
| `'horizontalDots'` | `'menu-horizontal'` |
| `'infoFill'` | `'info-filled'` |
| `'list'` | `'list-bulleted'` |
| `'magnify'` | `'search'` |
| `'marker'` | `'location'` |
| `'orderBox'` | `'order'` |
| `'pen'` | `'edit'` |
| `'question'` | `'question-circle'` |
| `'questionFill'` | `'question-circle-filled'` |
| `'starFill'` | `'star-filled'` |
| `'success'` | `'check-circle'` |
| `'verticalDots'` | `'menu-vertical'` |
| `'warning'` | `'alert-triangle'` |
| `'warningFill'` | `'alert-triangle-filled'` |

## Migrating icon to the graphic slot

##### Latest (Preact)

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

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

function Extension() {
  return (
    <s-chip>
      <s-icon slot="graphic" type="discount"></s-icon>
      Free shipping
    </s-chip>
  );
}
```

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

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

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

function Extension() {
  return <Tag icon="discount">Free shipping</Tag>;
}
```

### on​Remove

The previous `Tag` `onRemove` prop is now supported on [`<s-clickable-chip>`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/actions/clickable-chip) only. Set the [`removable`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/actions/clickable-chip#properties-propertydetail-removable) prop to show the remove control, and listen for the [`remove`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/actions/clickable-chip#events-propertydetail-remove) event. In Preact, you still handle this with the `onRemove` prop, but the handler now receives an `Event` instead of being called with no arguments.

## Migrating onRemove

##### Latest (Preact)

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

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

function Extension() {
  const [removed, setRemoved] = useState(false);

  if (removed) return null;

  return (
    <s-clickable-chip
      removable
      onRemove={() => {
        setRemoved(true);
      }}
    >
      <s-icon slot="graphic" type="discount"></s-icon>
      SAVE20
    </s-clickable-chip>
  );
}
```

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

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

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

function Extension() {
  const [removed, setRemoved] = useState(false);

  if (removed) return null;

  return (
    <Tag
      icon="discount"
      onRemove={() => {
        setRemoved(true);
      }}
    >
      SAVE20
    </Tag>
  );
}
```

***

## New properties

[`<s-clickable-chip>`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/actions/clickable-chip) introduces the following new properties that weren't available on `Tag`:

| New prop | Type | Description |
| - | - | - |
| [`removable`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/actions/clickable-chip#properties-propertydetail-removable) | `boolean` | Shows a remove control. Fires the [`remove`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/actions/clickable-chip#events-propertydetail-remove) event when clicked. |
| [`href`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/actions/clickable-chip#properties-propertydetail-href) | `string` | Makes the chip navigate to a URL when activated. |
| [`disabled`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/actions/clickable-chip#properties-propertydetail-disabled) | `boolean` | Disables the chip and prevents interaction. |
| [`hidden`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/actions/clickable-chip#properties-propertydetail-hidden) | `boolean` | Hides the chip. Fires the [`afterhide`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/actions/clickable-chip#events-propertydetail-afterhide) event after the hide animation completes. |
| [`onClick`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/actions/clickable-chip#events-propertydetail-click) | function | Fires when the chip is activated. |

***