CounterBadge

Components/Feedback

Interactive docs page: https://wix-pages.com/design-system-documentation/#/component/counterbadge

Overview

Copy

A counter badge is a numeric indicator that shows the count of pending or unseen items that require user attention.

Do

  • Use to display a numeric count of unseen or pending items that require user attention, like unread messages or queued tasks.
  • Use to reflect real-time changes in count, like items added to a cart or new errors detected.

Don't

  • Don't use to show the status of an item or function. Use <Badge/> instead.
  • Don't use to label or categorize content. Use <Tag/> instead.

Feature examples

Size

Adjust the component size using the size prop. It supports 2 sizes:

  • medium
  • small
Copy

Skin

Control the skin of a component with skin prop. Is support 10 skins:

  • general - use it as the default emphasis
  • danger - use it to highlight a destructive or critical value
  • urgent - use it to draw immediate attention to a value
  • standard - use it as the primary branded emphasis
  • warning - use it to highlight a value that can have an unexpected impact
  • warningLight - use it when warning needs reduced emphasis
  • success - use it to highlight confirmed or completed values
  • light - use it on dark backgrounds
  • neutralStandard - use it when the counter needs neutral emphasis
  • neutralLight - use it when the counter needs minimal emphasis on light backgrounds
Copy

Shadow

Use the showShadow prop to add a drop shadow to the counter badge.

Copy

Custom node

A counter badge can also display a custom node as its content, like an icon or a short text label, instead of a number.

Copy

Common use case examples

Counting items in a cart

Attach a counter badge to an icon button to show the number of items in a cart, updating as items are added or removed.

Copy

Prioritizing by urgency

Use a counter badge to show the number of items in each category, making it easy to identify where attention is needed most.

Copy

New feature or item

By displaying a custom node inside a counter badge, you can highlight non-numeric information — like a "New!" label to draw attention to a recently added feature or item.

Copy

Code

Copy

Props

NameTypeDefaultDescription
childrenReactNode—Any element to be rendered inside.
dataHookstring—Applied as data-hook HTML attribute that can be used in the tests.
locale"th" | "tr" | "id" | "fr" | "no" | "en" | "en-US" | "en-GB" | "en-AU" | "en-CA" | "ar" | "bg" | "ca" | "zh" | "zh-TW" | "zh-HK" | "zh-MO" | "cs" | "da" | "nl" | "fi" | "fr-CA" | "fr-CH" | "fr-BE" | "de" | "de-CH" | "de-AT" | "el" | "he" | "hi" | "hu" | "it" | "ja" | "ko" | "lt" | "ms" | "nb" | "nn" | "pl" | "pt-BR" | "pt" | "ro" | "ru" | "sk" | "sl" | "es" | "es-419" | "es-AR" | "es-MX" | "es-US" | "sv" | "tl" | "uk" | "vi"—Sets locale and formats the number according to it.
onMouseEnterMouseEventHandler—Callback fired when the mouse pointer enters the component.
onMouseLeaveMouseEventHandler—Callback fired when the mouse pointer leaves the component.
showShadow (required)boolean—Makes the card have a box-shadow style.
size (required)"small" | "tiny" | "medium"—The component's size. Can be tiny, small or medium.
skin (required)"warning" | "standard" | "light" | "success" | "general" | "danger" | "neutralLight" | "warningLight" | "urgent" | "neutralStandard"—The component's colors.
truncate (required)booleantrueControl whether values greater than 99 should be truncated.
type (required)"solid" | "outlined"'solid'The component's visual style.

Testkit

Import the driver matching your test environment:

Copy

Driver methods

MethodDescription
getContentTextGets CounterBadge content text if children are text based
getLocaleGets passed locale
mouseEnterTriggers a mouseEnter event
mouseLeaveTriggers a mouseLeave event
existsChecks whether the component found with the given data hook.
elementGets the component root element.
clickClicks on the component root element.
baseReturns UniDriver for the base element.

Changelog

  • 1.340.0 (2026-10-21) — maintenance release, no component-specific changes
  • 1.339.0 (2026-10-19) — maintenance release, no component-specific changes
  • 1.338.0 (2026-10-15) — maintenance release, no component-specific changes
  • 1.330.0 (2026-09-28) — maintenance release, no component-specific changes
  • 1.329.0 (2026-09-24) — maintenance release, no component-specific changes
  • 1.328.0 (2026-09-22) — maintenance release, no component-specific changes
  • 1.327.0 (2026-09-21) — maintenance release, no component-specific changes
  • 1.325.0 (2026-09-17) — maintenance release, no component-specific changes
  • 1.310.0 (2026-08-10) — maintenance release, no component-specific changes
  • 1.299.0 (2026-07-17) — maintenance release, no component-specific changes
  • 1.295.0 (2026-07-03) — feat: add tiny size (#16468) — has visual changes
  • 1.292.0 (2026-06-22) — maintenance release, no component-specific changes
  • 1.285.0 (2026-06-05) — feat: add onMouseEnter and onMouseLeave callbacks (#16336)
  • 1.285.0 (2026-06-05) — feat: add type prop with solid and outlined styles (#16337) — has visual changes
  • 1.267.0 (2026-04-09) — maintenance release, no component-specific changes
  • 1.266.0 (2026-04-07) — maintenance release, no component-specific changes
  • 1.260.0 (2026-03-17) — maintenance release, no component-specific changes
  • 1.257.0 (2026-02-19) — breaking: streched out counter badge (#15935)
  • 1.254.0 (2026-02-03) — maintenance release, no component-specific changes
  • 1.239.0 (2025-12-12) — maintenance release, no component-specific changes
  • 1.220.0 (2025-09-29) — maintenance release, no component-specific changes
  • 1.203.0 (2025-07-01) — maintenance release, no component-specific changes
  • 1.138.1 (2024-10-30) — maintenance release, no component-specific changes
  • 1.104.1 (2024-05-14) — maintenance release, no component-specific changes
  • 1.103.1 (2024-04-24) — maintenance release, no component-specific changes
  • 1.102.0 (2024-04-16) — maintenance release, no component-specific changes
  • 1.95.0 (2024-02-15) — feat: add new color: neutral (#13311)
  • 1.93.0 (2024-02-08) — maintenance release, no component-specific changes
  • 1.92.1 (2024-02-05) — maintenance release, no component-specific changes

Last updated: 22 October 2026

Did this help?