Badge

The badge component displays status information or indicates completed actions through compact visual indicators. Use badge to communicate object states, order statuses, or system-generated classifications that help users quickly understand item conditions.

Badges support multiple tones and sizes, with optional icons to reinforce status meaning and improve scannability in lists and tables. For user-created labels, categories, or tags, use chip instead.

Anchor to PropertiesProperties

A badge displayed next to an item in the picker to show status or progress. Use badges to highlight important item attributes or states that affect selection decisions.

Anchor to content content string required: The text content of the badge. Keep this short and descriptive (for example, "Draft", "Active", "Incomplete").
Anchor to progress progress: The progress indicator for the badge. Use this to show completion status for items that have progress states.
Anchor to tone tone: The visual tone indicating status or importance. Choose a tone that matches the badge's meaning.

Progress

The progress state for picker badges showing completion status. Use this to indicate how complete an item is: `'incomplete'` for not started, `'partiallyComplete'` for in progress, or `'complete'` for finished.

'incomplete' | 'partiallyComplete' | 'complete'

Tone

The visual tone for picker badges indicating status or importance. Use different tones to communicate urgency or state: `'info'` for neutral information, `'success'` for positive states, `'warning'` for caution, or `'critical'` for urgent issues.

'info' | 'success' | 'warning' | 'critical'

Anchor to SlotsSlots

The badge component supports slots for additional content placement within the component. Learn more about using slots.

Anchor to children children HTMLElement: The text label displayed within the badge component, typically a short status indicator or category label.

Anchor to ExamplesExamples

Anchor to Add status badges with tonesAdd status badges with tones

Create badges with different tones to represent statuses. This example shows the tones auto (implicit default), info, success, caution, warning, and critical.

Preview

html

<s-badge>Fulfilled</s-badge>

<s-badge tone="info">Draft</s-badge>

<s-badge tone="success">Active</s-badge>

<s-badge tone="caution">Open</s-badge>

<s-badge tone="warning">On hold</s-badge>

<s-badge tone="critical">Action required</s-badge>

Anchor to Add icons to status badgesAdd icons to status badges

Combine tones with icons to provide stronger visual cues. This example shows product and inventory status badges with icons that reinforce meaning.

Preview

html

<s-stack gap="base">

<s-stack direction="inline" gap="base">

<s-badge tone="success" icon="view">Active</s-badge>

<s-badge tone="warning" icon="clock">Scheduled</s-badge>

<s-badge tone="critical">Archived</s-badge>

</s-stack>

<s-stack direction="inline" gap="base">

<s-badge tone="success">In stock</s-badge>

<s-badge tone="warning" icon="alert-triangle">Low stock</s-badge>

<s-badge tone="critical">Out of stock</s-badge>

</s-stack>

Anchor to Display badges in a tableDisplay badges in a table

Place badges inside table cells to give merchants a scannable overview of status information. This example shows fulfillment and payment badges in an order table.

Preview

html

<s-table>

<s-table-header-row>

<s-table-header>Order</s-table-header>

<s-table-header>Fulfillment</s-table-header>

<s-table-header>Payment</s-table-header>

</s-table-header-row>

<s-table-body>

<s-table-row>

<s-table-cell>#1001</s-table-cell>

<s-table-cell>

<s-badge tone="success">Fulfilled</s-badge>

</s-table-cell>

<s-table-cell>

<s-badge tone="success">Paid</s-badge>

</s-table-cell>

</s-table-row>

</s-table-body>

</s-table>

Anchor to Control badge size for emphasisControl badge size for emphasis

Use the size property to create visual hierarchy between badges. This example shows the base size for standard usage and the large size for badges that need more prominence.

Preview

html

<s-stack direction="inline" gap="base">

<s-badge size="base">New</s-badge>

<s-badge size="large">Attention needed</s-badge>

</s-stack>

Anchor to Best practicesBest practices

Choose the right size: Use base size in table cells, list items, or when showing multiple badges together. Use large size for standalone badges that need emphasis, like a primary status indicator at the top of a page.
Keep labels to 1-2 words: Use concise labels like Fulfilled, Partially refunded, or Out of stock. Always use past tense for status labels: Refunded not Refund.
Use appropriate tones: Apply critical for errors or urgent issues needing action, warning for problems requiring attention, success for positive confirmations, and info for neutral statuses. Use consistent tones for the same status across your app.
Position in content flow: Place badges adjacent to the items they describe. In list items, position them near the title. In tables, place them in their own column for scannability.
Know when not to use badges: Badges are static, system-generated indicators. Don't use badges for merchant-created tags or removable items.

Anchor to LimitationsLimitations

Badge text truncates with an ellipsis when it exceeds the available width. Truncated text isn't accessible via tooltip, so keep labels concise.
Badge text never wraps to multiple lines. Long labels will truncate rather than expand the badge height.
Only specific predefined icons from the admin icon set are supported. Custom icons or images can't be used. The icon always appears to the left of the text and can't be repositioned.

Was this page helpful?