Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use web components, native UI elements with built-in accessibility, better performance, and consistent styling with Shopify's design system. Check out the migration guide to upgrade your extension.

Choose a version:

Badge

Use badges to highlight contextual information, like a label or a status, about an object. An object can be anything that has a status or label attributed to it, like an order or subscription.

Badges are compact, read-only indicators that support multiple tones to convey different levels of importance, with optional icons to reinforce meaning and improve scannability. For prominent, dismissible messages that require customer action, use Banner instead.

Support

Targets (25)

Supported targets

Anchor to PropertiesProperties

Configure the following properties on the Badge component.

Anchor to accessibilityLabel accessibilityLabel string: A label that describes the purpose or contents of the element. When set, it will be announced to users using assistive technologies and will provide them with more context. When set, any children or label supplied won't be announced to screen readers.
Anchor to accessibilityVisibility accessibilityVisibility: Controls the visibility of the element to assistive technologies. Set to 'hidden' to hide the element from assistive technologies while keeping it visually visible.
Anchor to icon icon: An icon displayed inside the badge to provide additional visual context or reinforce the badge's meaning.
Anchor to iconPosition iconPosition 'start' | 'end' Default: 'start': The position of the icon relative to the badge text.

start: Places the icon before the text.

end: Places the icon after the text.
Anchor to size size 'small' | 'base' Default: 'base': The size of the badge.

base: The default size, suitable for most use cases.

small: A smaller badge for compact layouts.
Anchor to tone tone Default: 'default': The semantic meaning and color treatment of the badge.
Anchor to visibility visibility: Controls the visual visibility of the element. Set to 'hidden' to visually hide the element while keeping it accessible to assistive technologies.

AccessibilityVisibility

Controls the visibility of an element to assistive technologies. - `hidden`: Hides the element from assistive technologies while keeping it visually visible.

'hidden'

IconSource

The name of the icon to display. Each value maps to a specific pictogram from the icon set.

'arrowLeft' | 'arrowRight' | 'arrowUp' | 'arrowUpRight' | 'arrowDown' | 'bag' | 'bullet' | 'calendar' | 'camera' | 'caretDown' | 'cart' | 'cashDollar' | 'categories' | 'checkmark' | 'chevronLeft' | 'chevronRight' | 'chevronUp' | 'chevronDown' | 'clipboard' | 'clock' | 'close' | 'creditCard' | 'critical' | 'delete' | 'delivered' | 'delivery' | 'disabled' | 'discount' | 'email' | 'error' | 'errorFill' | 'external' | 'filter' | 'geolocation' | 'gift' | 'giftFill' | 'grid' | 'hamburger' | 'hollowCircle' | 'horizontalDots' | 'image' | 'info' | 'infoFill' | 'list' | 'lock' | 'magnify' | 'map' | 'marker' | 'minus' | 'mobile' | 'note' | 'orderBox' | 'pen' | 'plus' | 'profile' | 'question' | 'questionFill' | 'reorder' | 'reset' | 'return' | 'savings' | 'settings' | 'star' | 'starFill' | 'starHalf' | 'store' | 'success' | 'truck' | 'upload' | 'verticalDots' | 'warning' | 'warningFill'

Tone

The available tone values for the badge. - `default`: General information without specific intent. - `critical`: Urgent problems or destructive actions requiring immediate attention. - `subdued`: Reduced visual emphasis for less prominent badges.

'default' | 'critical' | 'subdued'

Visibility

Controls the visual visibility of an element. - `hidden`: Visually hides the element while keeping it accessible to assistive technologies. The element does not occupy visual space.

'hidden'

Anchor to ExamplesExamples

Anchor to Show an order statusShow an order status

Display a simple badge to communicate a status. This example renders a default-toned badge with a single word label.

Show an order status

Show an order status

import {

reactExtension,

Badge,

} from '@shopify/ui-extensions-react/customer-account';

export default reactExtension(

'customer-account.page.render',

() => <Extension />,

);

function Extension() {

return <Badge>Available</Badge>;

}

import {extension, Badge} from '@shopify/ui-extensions/customer-account';

export default extension('customer-account.page.render', (root) => {

const badge = root.createComponent(Badge, undefined, 'Available');

root.appendChild(badge);

});

React

import {
  reactExtension,
  Badge,
} from '@shopify/ui-extensions-react/customer-account';

export default reactExtension(
  'customer-account.page.render',
  () => <Extension />,
);

function Extension() {
  return <Badge>Available</Badge>;
}

JS

import {extension, Badge} from '@shopify/ui-extensions/customer-account';

export default extension('customer-account.page.render', (root) => {
  const badge = root.createComponent(Badge, undefined, 'Available');

  root.appendChild(badge);
});

Anchor to Indicate a subscription statusIndicate a subscription status

Place a badge alongside related content to provide status context. This example shows a "Paused" badge with a subdued tone next to subscription details.

Indicate a subscription status

A subscription card with a Paused badge in a subdued tone.

Indicate a subscription status

import {

reactExtension,

Badge,

BlockStack,

Text,

} from '@shopify/ui-extensions-react/customer-account';

export default reactExtension(

'customer-account.page.render',

() => <Extension />,

);

function Extension() {

return (

<BlockStack

border="base"

padding="large200"

spacing="base"

borderRadius="large"

Subscription

</Text>

<Text>Mini garden seeds</Text>

</BlockStack>

<BlockStack

spacing="none"

inlineAlignment="start"

$35.00 monthly

</Text>

<Badge tone="subdued">Paused</Badge>

</BlockStack>

);

}

import {

extension,

Badge,

BlockStack,

Text,

} from '@shopify/ui-extensions/customer-account';

export default extension('customer-account.page.render', (root) => {

const container = root.createComponent(

BlockStack,

{

border: 'base',

padding: 'large200',

spacing: 'base',

borderRadius: 'large',

[

root.createComponent(BlockStack, {spacing: 'none'}, [

root.createComponent(

Text,

{size: 'large', emphasis: 'bold'},

'Subscription',

root.createComponent(Text, undefined, 'Mini garden seeds'),

]),

root.createComponent(

BlockStack,

{spacing: 'none', inlineAlignment: 'start'},

[

root.createComponent(Text, {emphasis: 'bold'}, '$35.00 monthly'),

root.createComponent(Badge, {tone: 'subdued'}, 'Paused'),

);

root.appendChild(container);

});

React

import {
  reactExtension,
  Badge,
  BlockStack,
  Text,
} from '@shopify/ui-extensions-react/customer-account';

export default reactExtension(
  'customer-account.page.render',
  () => <Extension />,
);

function Extension() {
  return (
    <BlockStack
      border="base"
      padding="large200"
      spacing="base"
      borderRadius="large"
    >
      <BlockStack spacing="none">
        <Text size="large" emphasis="bold">
          Subscription
        </Text>
        <Text>Mini garden seeds</Text>
      </BlockStack>
      <BlockStack
        spacing="none"
        inlineAlignment="start"
      >
        <Text emphasis="bold">
          $35.00 monthly
        </Text>
        <Badge tone="subdued">Paused</Badge>
      </BlockStack>
    </BlockStack>
  );
}

JS

import {
  extension,
  Badge,
  BlockStack,
  Text,
} from '@shopify/ui-extensions/customer-account';

export default extension('customer-account.page.render', (root) => {
  const container = root.createComponent(
    BlockStack,
    {
      border: 'base',
      padding: 'large200',
      spacing: 'base',
      borderRadius: 'large',
    },
    [
      root.createComponent(BlockStack, {spacing: 'none'}, [
        root.createComponent(
          Text,
          {size: 'large', emphasis: 'bold'},
          'Subscription',
        ),
        root.createComponent(Text, undefined, 'Mini garden seeds'),
      ]),

      root.createComponent(
        BlockStack,
        {spacing: 'none', inlineAlignment: 'start'},
        [
          root.createComponent(Text, {emphasis: 'bold'}, '$35.00 monthly'),
          root.createComponent(Badge, {tone: 'subdued'}, 'Paused'),
        ],
      ),
    ],
  );

  root.appendChild(container);
});

Anchor to Highlight a critical statusHighlight a critical status

Use the critical and warning tones to draw attention to statuses that require customer action. This example pairs a critical badge with an icon and a warning badge side by side.

Highlight a critical status

import {

reactExtension,

Badge,

InlineStack,

} from '@shopify/ui-extensions-react/customer-account';

export default reactExtension(

'customer-account.page.render',

() => <Extension />,

);

function Extension() {

return (

Action required

</Badge>

<Badge tone="warning">Expiring soon</Badge>

</InlineStack>

);

}

import {

extension,

Badge,

InlineStack,

} from '@shopify/ui-extensions/customer-account';

export default extension('customer-account.page.render', (root) => {

const container = root.createComponent(InlineStack, {spacing: 'base'}, [

root.createComponent(

Badge,

{tone: 'critical', icon: 'warning'},

'Action required',

root.createComponent(Badge, {tone: 'warning'}, 'Expiring soon'),

]);

root.appendChild(container);

});

React

import {
  reactExtension,
  Badge,
  InlineStack,
} from '@shopify/ui-extensions-react/customer-account';

export default reactExtension(
  'customer-account.page.render',
  () => <Extension />,
);

function Extension() {
  return (
    <InlineStack spacing="base">
      <Badge tone="critical" icon="warning">
        Action required
      </Badge>
      <Badge tone="warning">Expiring soon</Badge>
    </InlineStack>
  );
}

JS

import {
  extension,
  Badge,
  InlineStack,
} from '@shopify/ui-extensions/customer-account';

export default extension('customer-account.page.render', (root) => {
  const container = root.createComponent(InlineStack, {spacing: 'base'}, [
    root.createComponent(
      Badge,
      {tone: 'critical', icon: 'warning'},
      'Action required',
    ),
    root.createComponent(Badge, {tone: 'warning'}, 'Expiring soon'),
  ]);

  root.appendChild(container);
});

Anchor to Best practicesBest practices

Keep badge labels short: Aim for one word per badge. For complex states that require two words, use sentence case.
Use descriptive adjectives or past-tense verbs: Labels like "Available", "Complete", "Delivered", or "Delayed" communicate status clearly.
Match tone to urgency: subdued provides the least emphasis, while critical indicates the highest level of urgency. Reserve critical for statuses that require immediate attention.
Provide an accessibility label for context: Write a useful accessibilityLabel so that customers using assistive technology can access the full meaning of the badge. For critical badges, include urgency information like "Warning" or "Alert".
Always attribute badges to an object: A badge should appear alongside the item it describes, such as an order, subscription, or product.

Anchor to LimitationsLimitations

Badges are read-only indicators. They can't contain links, buttons, or other interactive elements.
Badge tones are limited to the predefined set (default, subdued, info, success, warning, critical). Custom colors aren't supported.
The badge icon position is relative to the text and can't be placed independently.

Was this page helpful?