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

Use s-badge for system-generated status. If a Badge acts as a filter, removable tag, or control, migrate it to s-chip, s-clickable-chip, or another control that matches the interaction.

Migrating Badge to s-badge

export function ProductStatus() {

return (

<s-badge

tone="success"

color="strong"

icon="enabled"

size="large"

Active

</s-badge>

);

}

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

export function ProductStatus() {

return (

Active

</Badge>

);

}

Polaris web components

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

Polaris React

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

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

Preview

Anchor to Updated propertiesUpdated properties

The following properties are different in the Polaris badge component.

Anchor to tonetone

The supported 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.

Anchor to sizesize

The 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".

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 and validate each replacement. Custom React icon components can't be passed to s-badge.

Anchor to Removed propertiesRemoved properties

Anchor to progressprogress

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"`.

Anchor to toneAndProgressLabelOverridetoneAndProgressLabelOverride

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 and apply accessibilityLabel to the box.

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

Anchor to New propertiesNew properties

The Polaris badge component introduces the following properties and values:

New property or value	Description
`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.

Anchor to Test the migrationTest 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.

Anchor to Related guidanceRelated guidance

Was this page helpful?