> To build a Wix site agentically, or add Wix features like bookings or a store to a site you already have, follow https://www.wix.com/headless/skill.md
> 
> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - If a reference page seems to be missing its schema (parameters, return types, or type definitions), append `?schema=true` to its `.md` URL (e.g. `https://dev.wix.com/docs/contexts/contexts/stores/category-info/use-category-info-context.md?schema=true`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: CounterBadge Component

## Article: CounterBadge Component

## Article Link: https://dev.wix.com/docs/wix-design-system/components/feedback/counter-badge-component.md

## Article Content:

# CounterBadge

_Components/Feedback_

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

## Overview

```jsx
() => (
  <Box align="center" padding="SP4">
    <CounterBadge>8</CounterBadge>
  </Box>
);
```

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`

```jsx
() => (
  <Box direction="vertical" gap="12px">
    <CounterBadge size="medium">8</CounterBadge>
    <CounterBadge size="small">8</CounterBadge>
  </Box>
);
```

#### 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

```jsx
() => (
  <Box direction="vertical" gap="18px">
    <Box gap="12px" verticalAlign="middle">
      <CounterBadge skin="general">1</CounterBadge>
      <Text size="small">General</Text>
    </Box>
    <Box gap="12px" verticalAlign="middle">
      <CounterBadge skin="danger">1</CounterBadge>
      <Text size="small">Danger</Text>
    </Box>
    <Box gap="12px" verticalAlign="middle">
      <CounterBadge skin="urgent">1</CounterBadge>
      <Text size="small">Urgent</Text>
    </Box>
    <Box gap="12px" verticalAlign="middle">
      <CounterBadge skin="standard">1</CounterBadge>
      <Text size="small">Standard</Text>
    </Box>
    <Box gap="24px" verticalAlign="middle">
      <Box gap="12px" verticalAlign="middle">
        <CounterBadge skin="warning">1</CounterBadge>
        <Text size="small">Warning</Text>
      </Box>
      <Box gap="12px" verticalAlign="middle">
        <CounterBadge skin="warningLight">1</CounterBadge>
        <Text size="small">Warning light</Text>
      </Box>
    </Box>
    <Box gap="12px" verticalAlign="middle">
      <CounterBadge skin="success">1</CounterBadge>
      <Text size="small">Success</Text>
    </Box>
    <Box gap="12px" verticalAlign="middle">
      <CounterBadge skin="light">1</CounterBadge>
      <Text size="small">Light</Text>
    </Box>
    <Box gap="24px" verticalAlign="middle">
      <Box gap="12px" verticalAlign="middle">
        <CounterBadge skin="neutralStandard">1</CounterBadge>
        <Text size="small">Neutral standard</Text>
      </Box>
      <Box gap="12px" verticalAlign="middle">
        <CounterBadge skin="neutralLight">1</CounterBadge>
        <Text size="small">Neutral light</Text>
      </Box>
    </Box>
  </Box>
);
```

#### Shadow

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

```jsx
() => {
  return (
    <Layout cols={4}>
      <Cell span={1}>
        <CounterBadge skin="general" showShadow>
          1
        </CounterBadge>
      </Cell>
      <Cell span={1}>
        <CounterBadge skin="standard" showShadow>
          1
        </CounterBadge>
      </Cell>
      <Cell span={1}>
        <CounterBadge skin="neutralStandard" showShadow>
          1
        </CounterBadge>
      </Cell>
      <Cell span={1}>
        <CounterBadge skin="danger" showShadow>
          1
        </CounterBadge>
      </Cell>
      <Cell span={1}>
        <CounterBadge skin="warning" showShadow>
          1
        </CounterBadge>
      </Cell>
      <Cell span={1}>
        <CounterBadge skin="warningLight" showShadow>
          1
        </CounterBadge>
      </Cell>
      <Cell span={1}>
        <CounterBadge skin="urgent" showShadow>
          1
        </CounterBadge>
      </Cell>
      <Cell span={1}>
        <CounterBadge skin="success" showShadow>
          1
        </CounterBadge>
      </Cell>
      <Cell span={1}>
        <CounterBadge skin="light" showShadow>
          1
        </CounterBadge>
      </Cell>
      <Cell span={1}>
        <CounterBadge skin="neutralLight" showShadow>
          1
        </CounterBadge>
      </Cell>
    </Layout>
  );
};
```

#### 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.

```jsx
() => {
  return (
    <Layout cols={4}>
      <Cell span={1}>
        <CounterBadge>
          <Icons.Check />
        </CounterBadge>
      </Cell>
      <Cell span={1}>
        <CounterBadge>
          <Icons.More />
        </CounterBadge>
      </Cell>
      <Cell span={1}>
        <CounterBadge skin="danger">
          <Icons.HeartFilled />
        </CounterBadge>
      </Cell>
      <Cell span={1}>
        <CounterBadge skin="success">New!</CounterBadge>
      </Cell>
    </Layout>
  );
};
```

### 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.

```jsx
() => (
  <Box>
    <Card>
      <Box padding="30px 40px 30px" gap="24px">
        <span style={{ position: 'relative', display: 'inline-block' }}>
          <IconButton>
            <Icons.Cart />
          </IconButton>
          <div
            style={{
              position: 'absolute',
              top: '-10px',
              left: '25px',
              pointerEvents: 'none',
            }}
          >
            <CounterBadge>0</CounterBadge>
          </div>
        </span>
        <span style={{ position: 'relative', display: 'inline-block' }}>
          <IconButton>
            <Icons.Cart />
          </IconButton>
          <div
            style={{
              position: 'absolute',
              top: '-10px',
              left: '25px',
              pointerEvents: 'none',
            }}
          >
            <CounterBadge>21</CounterBadge>
          </div>
        </span>
        <span style={{ position: 'relative', display: 'inline-block' }}>
          <IconButton>
            <Icons.Cart />
          </IconButton>
          <div
            style={{
              position: 'absolute',
              top: '-10px',
              left: '25px',
              pointerEvents: 'none',
            }}
          >
            <CounterBadge>555</CounterBadge>
          </div>
        </span>
      </Box>
    </Card>
  </Box>
);
```

#### 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.

```jsx
() => {
  const [activeTab, setActiveTab] = React.useState(0);

  const tabs = [
    { id: 0, title: 'All orders' },
    {
      id: 1,
      title: (
        <Box gap="6px" verticalAlign="middle">
          <Text size="small">Pending</Text>
          <CounterBadge skin="warning" size="tiny">
            5
          </CounterBadge>
        </Box>
      ),
    },
    {
      id: 2,
      title: (
        <Box gap="6px" verticalAlign="middle">
          <Text size="small">Cancelled</Text>
          <CounterBadge skin="danger" size="tiny">
            3
          </CounterBadge>
        </Box>
      ),
    },
    {
      id: 3,
      title: (
        <Box gap="6px" verticalAlign="middle">
          <Text size="small">Completed</Text>
          <CounterBadge skin="success" size="tiny">
            24
          </CounterBadge>
        </Box>
      ),
    },
  ];

  return (
    <Box width="560px">
      <Card>
        <Card.Header
          title="Orders"
          subtitle="Manage and track your store orders"
        />
        <Card.Divider />
        <Tabs
          items={tabs}
          activeId={activeTab}
          onClick={({ id }) => setActiveTab(Number(id))}
        />
        <Box padding="0 0 20px" />
      </Card>
    </Box>
  );
};
```

#### 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.

```jsx
() => {
  const [hoveredId, setHoveredId] = React.useState(null);

  return (
    <Box width="460px">
      <Card>
        <Card.Header
          title="Tools"
          subtitle="Everything you need to grow your business"
        />
        <Card.Divider />
        <Card.Content>
          <div
            onMouseEnter={() => setHoveredId('1')}
            onMouseLeave={() => setHoveredId(null)}
            style={{
              cursor: 'pointer',
              margin: '-24px',
              padding: '24px',
              backgroundColor:
                hoveredId === '1' ? 'var(--wsr-color-D70)' : 'transparent',
              transition: 'background-color 0.1s ease',
            }}
          >
            <Box direction="vertical" gap="2px">
              <Text size="small">Email campaigns</Text>
              <Text size="tiny" secondary>
                Send newsletters to your contacts
              </Text>
            </Box>
          </div>
        </Card.Content>
        <Card.Divider />
        <Card.Content>
          <div
            onMouseEnter={() => setHoveredId('2')}
            onMouseLeave={() => setHoveredId(null)}
            style={{
              cursor: 'pointer',
              margin: '-24px',
              padding: '24px',
              backgroundColor:
                hoveredId === '2' ? 'var(--wsr-color-D70)' : 'transparent',
              transition: 'background-color 0.1s ease',
            }}
          >
            <Box direction="vertical" gap="2px">
              <Box gap="8px" verticalAlign="middle">
                <Text size="small">AI content writer</Text>
                <CounterBadge skin="success">New!</CounterBadge>
              </Box>
              <Text size="tiny" secondary>
                Generate copy for your site instantly
              </Text>
            </Box>
          </div>
        </Card.Content>
        <Card.Divider />
      </Card>
    </Box>
  );
};
```

## Code

```jsx
import { CounterBadge } from '@wix/design-system';
```

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | — | Any element to be rendered inside. |
| `dataHook` | `string` | — | 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. |
| `onMouseEnter` | `MouseEventHandler` | — | Callback fired when the mouse pointer enters the component. |
| `onMouseLeave` | `MouseEventHandler` | — | 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)* | `boolean` | `true` | Control 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:

```jsx
// UniDriver
import { CounterBadgeUniDriver } from '@wix/design-system/dist/testkit/unidriver';

// Vanilla
import { CounterBadgeTestkit } from '@wix/design-system/dist/testkit';

// Puppeteer
import { CounterBadgeTestkit } from '@wix/design-system/dist/testkit/puppeteer';

// Testing Library
import { CounterBadgeTestkit } from '@wix/design-system/dist/testkit/testing-library';
```

### Driver methods

| Method | Description |
| --- | --- |
| `getContentText` | Gets CounterBadge content text if children are text based |
| `getLocale` | Gets passed locale |
| `mouseEnter` | Triggers a mouseEnter event |
| `mouseLeave` | Triggers a mouseLeave event |
| `exists` | Checks whether the component found with the given data hook. |
| `element` | Gets the component root element. |
| `click` | Clicks on the component root element. |
| `base` | Returns 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](invalid-url)) — 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](invalid-url))
- **1.285.0** (2026-06-05) — feat: add type prop with solid and outlined styles ([#16337](invalid-url)) — 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](invalid-url))
- **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](invalid-url))
- **1.93.0** (2024-02-08) — maintenance release, no component-specific changes
- **1.92.1** (2024-02-05) — maintenance release, no component-specific changes