Skip to main content
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.

Badge

The Badge component displays a small label that communicates the status of an object, such as an order, product, or payment. It supports multiple tones to convey meaning at a glance and can include an icon for additional visual context.

For prominent, dismissible messages with actions, use Banner.

Support
Targets (46)

Supported targets

Anchor to PropertiesProperties

Props for the Badge component. A badge can optionally include an icon (BadgeIconProps) or omit one (BadgeNoIconProps). This union ensures type safety so that iconPosition can only be set when icon is present.

BadgeBaseProps & (BadgeIconProps | BadgeNoIconProps)
Anchor to BadgeBaseProps

BadgeBaseProps

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 size
size
'base' | 'small-100'
Default: 'base'

The size of the badge.

  • small-100: A smaller badge, useful for compact layouts.
  • base: The standard badge size.
Anchor to tone
tone

The color and semantic tone of the badge. Use this to communicate the status or importance of the information the badge represents.

  • info: Neutral informational content with no implied urgency.
  • success: A positive outcome or completed action.
  • warning: Something that needs attention but isn't blocking.
  • critical: A serious problem that needs immediate action.
Anchor to BadgeIconProps

BadgeIconProps

Anchor to icon
icon
required

The name of the icon to display inside the badge. Use an icon to provide additional visual context alongside the badge text.

Anchor to iconPosition
iconPosition
'start' | 'end'
Default: 'start'

The position of the icon within the badge. Use 'end' to place the icon after the badge text instead of before it.

Requires icon to be set.

  • start: Icon appears before the text.
  • end: Icon appears after the text.
Anchor to BadgeNoIconProps

BadgeNoIconProps

Anchor to icon
icon
never

The name of the icon to display inside the badge. Typed as never on this variant because no icon is provided. Use the BadgeIconProps variant to set an icon.

Anchor to iconPosition
iconPosition
never

The position of the icon within the badge. Typed as never on this variant because no icon is provided. Set icon first to configure its position.

Anchor to ExamplesExamples

Anchor to Display order fulfillment statusDisplay order fulfillment status

Indicate fulfilled, partially fulfilled, and unfulfilled order states with color-coded labels. This example renders three Badge components using success, warning, and critical tones to visually distinguish each state.

Display order fulfillment status

Indicate fulfilled, partially fulfilled, and unfulfilled order states with color-coded labels. This example renders three `Badge` components using `success`, `warning`, and `critical` tones to visually distinguish each state.

Display order fulfillment status

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

function App() {

return (
<BlockStack>
<Text fontWeight="bold">Order status:</Text>
<Badge tone="success">Fulfilled</Badge>
<Badge tone="warning">Partially fulfilled</Badge>
<Badge tone="critical">Unfulfilled</Badge>
</BlockStack>
);
}

export default reactExtension(
'admin.product-details.block.render',
() => <App />,
);
import {extension, Badge, BlockStack, Text} from '@shopify/ui-extensions/admin';

export default extension(
'admin.product-details.block.render',
(root) => {

const stack = root.createComponent(BlockStack);

const label = root.createComponent(
Text,
{fontWeight: 'bold'},
'Order status:',
);

const fulfilled = root.createComponent(
Badge,
{tone: 'success'},
'Fulfilled',
);

const partial = root.createComponent(
Badge,
{tone: 'warning'},
'Partially fulfilled',
);

const unfulfilled = root.createComponent(
Badge,
{tone: 'critical'},
'Unfulfilled',
);

stack.appendChild(label);
stack.appendChild(fulfilled);
stack.appendChild(partial);
stack.appendChild(unfulfilled);
root.appendChild(stack);
},
);

Anchor to Add icons to stock alertsAdd icons to stock alerts

Pair a status icon with tone to create scannable inventory alerts in a block extension. This example renders badges with contextual icons like CircleTickMajor and DiamondAlertMajor, giving merchants a compact visual summary of product availability.

Add icons to stock alerts

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

function App() {

return (
<BlockStack>
<Text fontWeight="bold">Inventory alerts</Text>
<Badge tone="success" icon="CircleTickMajor">In stock</Badge>
<Badge tone="warning" icon="DiamondAlertMajor">Low stock</Badge>
<Badge tone="critical" icon="DiamondAlertMajor">Out of stock</Badge>
</BlockStack>
);
}

export default reactExtension(
'admin.product-details.block.render',
() => <App />,
);
import {extension, Badge, BlockStack, Text} from '@shopify/ui-extensions/admin';

export default extension(
'admin.product-details.block.render',
(root) => {

const stack = root.createComponent(BlockStack);

const heading = root.createComponent(
Text,
{fontWeight: 'bold'},
'Inventory alerts',
);

const inStock = root.createComponent(
Badge,
{tone: 'success', icon: 'CircleTickMajor'},
'In stock',
);

const lowStock = root.createComponent(
Badge,
{tone: 'warning', icon: 'DiamondAlertMajor'},
'Low stock',
);

const outOfStock = root.createComponent(
Badge,
{tone: 'critical', icon: 'DiamondAlertMajor'},
'Out of stock',
);

stack.appendChild(heading);
stack.appendChild(inStock);
stack.appendChild(lowStock);
stack.appendChild(outOfStock);
root.appendChild(stack);
},
);

Anchor to Label product sales channelsLabel product sales channels

Display compact sales channel labels alongside product metadata. This example uses size="small-100" and renders multiple badges in an InlineStack, using tone to differentiate active channels from pending ones.

Label product sales channels

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

function App() {

return (
<BlockStack>
<Text fontWeight="bold">Sales channels</Text>
<InlineStack>
<Badge size="small-100" tone="success">Online Store</Badge>
<Badge size="small-100" tone="success">POS</Badge>
<Badge size="small-100" tone="info">Facebook — pending</Badge>
</InlineStack>
</BlockStack>
);
}

export default reactExtension(
'admin.product-details.block.render',
() => <App />,
);
import {extension, Badge, InlineStack, Text, BlockStack} from '@shopify/ui-extensions/admin';

export default extension(
'admin.product-details.block.render',
(root) => {

const stack = root.createComponent(BlockStack);

const heading = root.createComponent(
Text,
{fontWeight: 'bold'},
'Sales channels',
);

const channels = root.createComponent(InlineStack);

const online = root.createComponent(
Badge,
{size: 'small-100', tone: 'success'},
'Online Store',
);

const pos = root.createComponent(
Badge,
{size: 'small-100', tone: 'success'},
'POS',
);

const pending = root.createComponent(
Badge,
{size: 'small-100', tone: 'info'},
'Facebook — pending',
);

channels.appendChild(online);
channels.appendChild(pos);
channels.appendChild(pending);

stack.appendChild(heading);
stack.appendChild(channels);
root.appendChild(stack);
},
);

Anchor to Best practicesBest practices

  • Keep labels to one or two words: Use concise labels like Fulfilled, Pending, or Out of stock. Use past tense for completed actions: Refunded, not Refund.
  • Use tones consistently: Use the same tone for the same status across your entire extension. Don't mix warning and critical for the same severity level — merchants will lose trust in the signal if tones are inconsistent.
  • Position badges near the content they describe: In list items, place badges adjacent to the title. This makes them easy to scan without disrupting the reading flow.
  • Don't use badges for interactive elements: Badges are static, system-generated indicators. For removable tags or merchant-created labels, use a different pattern.
  • Use icons to reinforce meaning: When adding an icon, choose one that reinforces the badge's message.

Anchor to LimitationsLimitations

  • Badge supports only two sizes: small-100 and base.
  • Badge text doesn't wrap to multiple lines. Long labels will be clipped, so keep text concise.
  • Only icons from the Polaris icon set are supported through the icon prop. Custom icons or images can't be used inside a badge.
  • Badge isn't interactive. It doesn't support click handlers or navigation. For interactive status indicators, combine a badge with a Pressable or Button component.
Was this page helpful?