---
title: Migrate Badge from Polaris React
description: >-
  Learn how to migrate the Polaris React Badge component to Polaris web
  components in an embedded app.
source_url:
  html: >-
    https://shopify.dev/docs/apps/build/app-home/migrate-from-polaris-react/badge
  md: >-
    https://shopify.dev/docs/apps/build/app-home/migrate-from-polaris-react/badge.md
api_name: app-home
---

# Migrate Badge from Polaris React

The Polaris badge component displays compact status information. It replaces the Polaris React `Badge` component from `@shopify/polaris` and is available as [`<s-badge>`](https://shopify.dev/docs/api/app-home/web-components/feedback-and-status-indicators/badge).

Use `s-badge` for system-generated status. If a `Badge` acts as a filter, removable tag, or control, migrate it to [`s-chip`](https://shopify.dev/docs/api/app-home/web-components/typography-and-content/chip), [`s-clickable-chip`](https://shopify.dev/docs/api/app-home/web-components/actions/clickable-chip), or another control that matches the interaction.

## Migrating Badge to s-badge

##### Polaris web components

```tsx
export function ProductStatus() {
  return (
    <s-badge
      tone="success"
      color="strong"
      icon="enabled"
      size="large"
    >
      Active
    </s-badge>
  );
}
```

##### Polaris React

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

export function ProductStatus() {
  return (
    <Badge tone="success-strong" progress="complete" size="large">
      Active
    </Badge>
  );
}
```

***

## Updated properties

The following properties are different in the Polaris badge component.

### tone

The supported [`tone`](https://shopify.dev/docs/api/app-home/web-components/feedback-and-status-indicators/badge#badge-propertydetail-tone) values have changed. Choose the new tone from the status meaning; don't use a value only to reproduce the previous color.

| Polaris React value | Polaris web components | Migration notes |
| - | - | - |
| Omitted | `"auto"` or omitted | The component chooses its default treatment. |
| `"info"` | `"info"` | No change is needed. |
| `"success"` | `"success"` | No change is needed. |
| `"warning"` | `"warning"` | No change is needed. |
| `"critical"` | `"critical"` | No change is needed. |
| `"attention"` | `"caution"` | Use for an advisory status that needs attention. |
| `"info-strong"` | `tone="info" color="strong"` | Move the emphasis to `color`. |
| `"success-strong"` | `tone="success" color="strong"` | Move the emphasis to `color`. |
| `"warning-strong"` | `tone="warning" color="strong"` | Move the emphasis to `color`. |
| `"critical-strong"` | `tone="critical" color="strong"` | Move the emphasis to `color`. |
| `"attention-strong"` | `tone="caution" color="strong"` | Rename the tone and move the emphasis to `color`. |
| `"new"`, `"magic"`, `"read-only"`, or `"enabled"` | No like-for-like value | Choose `"neutral"`, `"info"`, `"success"`, or another supported tone from the status meaning, and keep the status explicit in the badge text. |

### size

The [`size`](https://shopify.dev/docs/api/app-home/web-components/feedback-and-status-indicators/badge#badge-propertydetail-size) values use the Polaris web component scale.

| Polaris React value | Polaris web components | Migration notes |
| - | - | - |
| `"small"` | `"base"` | There is no smaller badge size. Verify the containing layout instead of shrinking the badge. |
| `"medium"` or omitted | `"base"` or omitted | `base` is the default size. |
| `"large"` | `"large"` | No change is needed. |

The new `"large-100"` value is available when the status needs more emphasis than `"large"`.

### icon

The `icon` property now accepts a documented icon name string. Replace imported Polaris React icon sources with their corresponding names, and remove the icon imports after every consumer is migrated.

Review the [`s-icon` icon names](https://shopify.dev/docs/api/app-home/web-components/media-and-visuals/icon) and validate each replacement. Custom React icon components can't be passed to `s-badge`.

***

## Removed properties

### progress

`s-badge` doesn't have a `progress` property. Keep progress explicit in the badge label and tone. Add a documented `icon` only when it reinforces the same meaning.

| Polaris React value | Migration |
| - | - |
| `"incomplete"` | Use a label such as **Not started** or **Unfulfilled** and choose a tone from the actual status severity. |
| `"partiallyComplete"` | Use a label such as **Partially fulfilled**. Don't rely on a partially filled pip. |
| `"complete"` | Use a completed-state label and, when useful, a supported icon such as `"enabled"`. |

### tone​And​Progress​Label​Override

`s-badge` doesn't have `toneAndProgressLabelOverride`. First make the visible badge text self-contained. If additional assistive-technology context is still required, wrap the badge in [`s-box`](https://shopify.dev/docs/api/app-home/web-components/layout-and-structure/box) and apply `accessibilityLabel` to the box.

Don't move status information into an accessibility-only label when all users need it.

***

## New properties

The Polaris badge component introduces the following properties and values:

| New property or value | Description |
| - | - |
| [`color`](https://shopify.dev/docs/api/app-home/web-components/feedback-and-status-indicators/badge#badge-propertydetail-color) | Sets `"base"` or `"strong"` emphasis independently from the semantic tone. |
| `tone="auto"` | Uses the default contextual treatment. |
| `tone="neutral"` | Communicates status without a positive, warning, or critical meaning. |
| `tone="caution"` | Communicates an advisory status that needs attention. |
| `size="large-100"` | Provides more emphasis than the previous large badge. |

***

## Test the migration

* Confirm every old tone now communicates the intended status meaning.
* Check labels that previously depended on `progress` or `toneAndProgressLabelOverride`.
* Verify long and translated labels don't hide essential status information.
* Confirm imported Polaris React icons and the `Badge` import are removed after their final consumers are migrated.

***

## Related guidance

* [Badge component](https://shopify.dev/docs/api/app-home/web-components/feedback-and-status-indicators/badge)
* [Badge best practices](https://shopify.dev/docs/api/app-home/web-components/feedback-and-status-indicators/badge#best-practices)
* [Migrate from Polaris React](https://shopify.dev/docs/apps/build/app-home/migrate-from-polaris-react)

***