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 component and is available as <s-badge> in API versions 2025-10 and newer.

Anchor to Updated propertiesUpdated properties

The following properties are different in the Polaris badge component.

Anchor to tonetone

Update tone values as follows:

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>;
}

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>;
}

Anchor to sizesize

The size property adds a new option:

For more on the scale system, see Scale.

Anchor to iconicon

If you use the icon property, then update icon names to their Polaris web component equivalents. Badge uses the same icon names as the Polaris icon component.

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>;
}

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>;
}

Anchor to Removed propertiesRemoved properties

Anchor to accessibilityLabelaccessibilityLabel

The Polaris badge component no longer supports accessibilityLabel directly. To provide an accessibility label, wrap the badge in s-box and set accessibilityLabel on the box.

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>
  );
}

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>;
}

Anchor to accessibilityVisibilityaccessibilityVisibility

The Polaris badge component no longer supports accessibilityVisibility directly. To control accessibility visibility, wrap the badge in s-box and set 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.

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>
  );
}

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>;
}

Anchor to visibilityvisibility

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.

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>
  );
}

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>;
}

Anchor to New propertiesNew properties

The Polaris badge component introduces the following new properties:

Anchor to colorcolor

Use the color property to control the intensity of the badge.