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

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.

Support
Targets (50)

Supported targets

Anchor to BadgePropsBadgeProps

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.

Anchor to accessibilityLabel
accessibilityLabel
string

A label that describes the purpose or contents of the element. When set, it will announced to buyers using assistive technologies.

Anchor to accessibilityVisibility
accessibilityVisibility

Changes the visibility of the element to assistive technologies.

hidden hides the component from assistive technology (for example, a screen reader) but remains visually visible.

Anchor to icon
icon

The name of the icon to be displayed in the badge.

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

The position of the icon in relation to the text.

Anchor to size
size
'small' | 'base'
Default: 'base'

The size of the badge being rendered.

Anchor to tone
tone
Default: 'default'

The tone of the badge being rendered. Indicates its level of importance, where subdued provides the least emphasis, while critical indicates the highest level of urgency.

Anchor to visibility
visibility

Changes the visibility of the element.

hidden visually hides the component while keeping it accessible to assistive technology, such as screen readers. Hidden elements don't take any visual space contrary to CSS visibility: hidden;

Anchor to ExamplesExamples

Anchor to Basic BadgeBasic Badge

Basic Badge

Example

Basic Badge

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

export default reactExtension(
'purchase.checkout.block.render',
() => <Extension />,
);

function Extension() {
return <Badge>Available</Badge>;
}
import {extension, Badge} from '@shopify/ui-extensions/checkout';

export default extension('purchase.checkout.block.render', (root) => {
const badge = root.createComponent(Badge, undefined, 'Available');

root.appendChild(badge);
});

Anchor to Using the Badge component as a status indicatorUsing the Badge component as a status indicator

Using the Badge component as a status indicator

Example

Using the Badge component as a status indicator

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

export default reactExtension(
'purchase.checkout.block.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>
);
}
import {
extension,
Badge,
BlockStack,
Text,
} from '@shopify/ui-extensions/checkout';

export default extension('purchase.checkout.block.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 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 "Paid", "Free", "Expired", or "Processing" 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 buyers 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.

Was this page helpful?