---
title: Badge
description: >-
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.
api_version: 2025-07
api_name: customer-account-ui-extensions
source_url:
html: >-
https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/feedback-and-status-indicators/badge
md: >-
https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/feedback-and-status-indicators/badge.md
---
Migrate to Polaris
Version 2025-07 is the last API version to support React-based UI components. Later versions use [web components](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/polaris-web-components), native UI elements with built-in accessibility, better performance, and consistent styling with [Shopify's design system](https://shopify.dev/docs/apps/design). Check out the [migration guide](https://shopify.dev/docs/apps/build/customer-accounts/migrate-to-web-components) 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.
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](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/feedback-and-status-indicators/banner) instead.
### Support Targets (25)
### Supported targets
* CustomerAccount::KitchenSink
* [customer-account.footer.render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/footer#footer-render-after-)
* [customer-account.order-index.announcement.render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-index#order-index-targets)
* [customer-account.order-index.block.render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-index#order-index-block-)
* [customer-account.order-status.announcement.render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#order-status-announcement-)
* [customer-account.order-status.block.render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#order-status-block-)
* [customer-account.order-status.cart-line-item.render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#cart-line-item-render-after-)
* [customer-account.order-status.cart-line-list.render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#cart-line-list-render-after-)
* [customer-account.order-status.customer-information.render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#customer-information-render-after-)
* [customer-account.order-status.fulfillment-details.render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/fulfillment-status#fulfillment-status-targets)
* [customer-account.order-status.payment-details.render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/payments-and-returns#payments-and-returns-targets)
* [customer-account.order-status.return-details.render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/payments-and-returns#return-details-render-after-)
* [customer-account.order-status.unfulfilled-items.render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/fulfillment-status#unfulfilled-items-render-after-)
* [customer-account.order.action.menu-item.render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-actions#order-action-menu-item-)
* [customer-account.order.action.render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-actions#order-action-)
* [customer-account.order.page.render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/full-page#order-specific-full-page-)
* [customer-account.page.render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/full-page#customer-account-full-page-)
* [customer-account.profile.addresses.render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-default#profile-page-default-targets-)
* [customer-account.profile.announcement.render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-default#announcement-)
* [customer-account.profile.block.render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-default#profile-block-)
* [customer-account.profile.company-details.render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-b2b#profile-page-b2b-targets-)
* [customer-account.profile.company-location-addresses.render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-b2b#company-location-addresses-render-after-)
* [customer-account.profile.company-location-payment.render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-b2b#company-location-payment-render-after-)
* [customer-account.profile.company-location-staff.render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-b2b#company-location-staff-render-after-)
* customer-account.profile.payment.render-after
#### Use cases
* **Order and fulfillment statuses**: Communicate states like "Delivered", "In transit", or "Canceled" so customers can scan their order list quickly.
* **Subscription states**: Indicate whether a subscription is active, paused, or expiring soon.
* **Membership tiers**: Label loyalty or rewards tiers alongside customer account information.
* **Product availability**: Surface stock or availability labels like "Available" or "Sold out".
***
## Properties
Configure the following properties on the Badge component.
* **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.
* **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.
* **icon**
**IconSource**
An icon displayed inside the badge to provide additional visual context or reinforce the badge's meaning.
* **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.
* **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.
* **tone**
**Tone**
**Default: 'default'**
The semantic meaning and color treatment of the badge.
* **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.
```ts
'hidden'
```
### IconSource
The name of the icon to display. Each value maps to a specific pictogram from the icon set.
```ts
'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.
```ts
'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.
```ts
'hidden'
```
***
## Examples
### Show 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
##### React
```tsx
import {
reactExtension,
Badge,
} from '@shopify/ui-extensions-react/customer-account';
export default reactExtension(
'customer-account.page.render',
() => ,
);
function Extension() {
return Available;
}
```
##### JS
```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);
});
```
### Indicate 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
## Indicate a subscription status
##### React
```tsx
import {
reactExtension,
Badge,
BlockStack,
Text,
} from '@shopify/ui-extensions-react/customer-account';
export default reactExtension(
'customer-account.page.render',
() => ,
);
function Extension() {
return (
Subscription
Mini garden seeds
$35.00 monthly
Paused
);
}
```
##### JS
```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);
});
```
### Highlight 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
##### React
```tsx
import {
reactExtension,
Badge,
InlineStack,
} from '@shopify/ui-extensions-react/customer-account';
export default reactExtension(
'customer-account.page.render',
() => ,
);
function Extension() {
return (
Action required
Expiring soon
);
}
```
##### JS
```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);
});
```
***
## Best 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.
***
## Limitations
* 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.
***