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

# Migrate to the Polaris badge component

The Polaris badge component displays status information or indicates completed actions through compact visual indicators. It replaces the previous [`Badge`](https://shopify.dev/docs/api/checkout-ui-extensions/2025-07/ui-components/feedback-and-status-indicators/badge) component and is available as [`<s-badge>`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/feedback-and-status-indicators/badge) in API versions 2025-10 and newer.

***

## Updated properties

The following properties are different in the Polaris badge component.

### tone

Update [`tone`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/feedback-and-status-indicators/badge#properties-propertydetail-tone) values as follows:

| Previous value | New value |
| - | - |
| `'critical'` | `'critical'` |
| `'default'` | `'auto'` |
| `'subdued'` | `'auto'` + `color="subdued"` |

## Migrating tone values

##### Latest (Preact)

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

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

function Extension() {
  return <s-badge color="subdued">Low stock</s-badge>;
}
```

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

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

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

function Extension() {
  return <Badge tone="subdued">Low stock</Badge>;
}
```

### size

The [`size`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/feedback-and-status-indicators/badge#properties-propertydetail-size) property adds a new option:

| Previous value | New value | Migration notes |
| - | - | - |
| `'small'` | `'small'` or `'small-100'` | `'small'` is an alias for `'small-100'`. |
| `'base'` | `'base'` | No change is needed. |

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

### icon

If you use the [`icon`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/feedback-and-status-indicators/badge#properties-propertydetail-icon) property, then update icon names to their Polaris web component equivalents. Badge 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 values

##### Latest (Preact)

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

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

function Extension() {
  return <s-badge icon="check">Fulfilled</s-badge>;
}
```

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

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

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

function Extension() {
  return <Badge icon="checkmark">Fulfilled</Badge>;
}
```

***

## Removed properties

### accessibility​Label

The Polaris badge component no longer supports `accessibilityLabel` directly. To provide an accessibility label, wrap the badge in [`s-box`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/box) and set [`accessibilityLabel`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/box#properties-propertydetail-accessibilitylabel) on the box.

## 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-box accessibilityLabel="Order fulfilled">
      <s-badge>Fulfilled</s-badge>
    </s-box>
  );
}
```

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

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

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

function Extension() {
  return <Badge accessibilityLabel="Order fulfilled">Fulfilled</Badge>;
}
```

### accessibility​Visibility

The Polaris badge component no longer supports `accessibilityVisibility` directly. To control accessibility visibility, wrap the badge in `s-box` and set [`accessibilityVisibility`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/layout-and-structure/box#properties-propertydetail-accessibilityvisibility) on the box.

Use these values as needed:

* `visible`: the element is visible to all users.
* `hidden`: the element is removed from the accessibility tree but remains visible.
* `exclusive`: the element is visually hidden but remains in the accessibility tree.

## Migrating accessibilityVisibility

##### Latest (Preact)

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

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

function Extension() {
  return (
    <s-box accessibilityVisibility="hidden">
      <s-badge>Fulfilled</s-badge>
    </s-box>
  );
}
```

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

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

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

function Extension() {
  return <Badge accessibilityVisibility="hidden">Fulfilled</Badge>;
}
```

### visibility

The Polaris badge component no longer supports `visibility` directly. If you need to visually hide the badge while keeping it in the accessibility tree, wrap the badge in `s-box` and set `accessibilityVisibility="exclusive"` on the box.

## Migrating visibility

##### Latest (Preact)

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

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

function Extension() {
  return (
    <s-box accessibilityVisibility="exclusive">
      <s-badge>Fulfilled</s-badge>
    </s-box>
  );
}
```

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

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

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

function Extension() {
  return <Badge visibility="hidden">Fulfilled</Badge>;
}
```

***

## New properties

The Polaris badge component introduces the following new properties:

### color

Use the [`color`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/feedback-and-status-indicators/badge#properties-propertydetail-color) property to control the intensity of the badge.

| Value | Description |
| - | - |
| `'base'` | Uses the default badge color intensity. |
| `'subdued'` | Uses a softer badge color intensity. |

**Note:**

Set `color="subdued"` with `tone="auto"` to match the previous `tone="subdued"` appearance.

***