@workday/canvas-kit-docs/dist/mdx/react/badge/CountBadge.mdx

Documentation components of Canvas Kit components

import {ExampleCodeBlock, SymbolDoc} from '@workday/canvas-kit-docs';

import Basic from './examples/Basic';
import Emphasis from './examples/Emphasis';
import Inverse from './examples/Inverse';
import CustomLimit from './examples/CustomLimit';
import NotificationBadge from './examples/NotificationBadge';


# Canvas Kit Count Badge

`CountBadge` provides a quantity-based summary with dynamic values.

## Installation

```sh
yarn add @workday/canvas-kit-react
```

## Usage

The following section provides examples for common use cases. Please be sure to also read the
Accessibility section below.

### Basic

Use the default `CountBadge` variant for most situations. The default `high` emphasis is ideal for
drawing attention to important or primary information.

<ExampleCodeBlock code={Basic} />

### Emphasis

Select the `low` emphasis option for less prominent or secondary information. This is useful when
you want the badge to be visible but not distracting.

`high` emphasis is ideal for drawing attention to important or primary information.

<ExampleCodeBlock code={Emphasis} />

### Inverse

Apply the `inverse` variant when displaying the badge on dark or accent backgrounds to maintain
proper contrast and readability. This ensures the badge remains legible in visually dense or colored
areas. The same rules apply for `low` and `high` emphasis. Only use this combination on backgrounds with
[a token of 600 or greater](https://workday.github.io/canvas-tokens/?path=/docs/docs-base-tokens--docs)
to ensure sufficient contrast and accessibility.

<ExampleCodeBlock code={Inverse} />


### Custom Limit

By default, `CountBadge`'s limit is set to `1000`. Once the count reaches the limit, the badge will
format the number: `1000` becomes `999+`. The default limit is largely arbitrary and intended to
prevent unexpected overflow. You should choose a limit based on your specific use case and consider
the user's experience. For example, someone looking for a new job finds there are `99+` new
opportunities. Or perhaps someone returns from extended leave and is overwhelmed by `999+` unread
messages on their first day back.

<ExampleCodeBlock code={CustomLimit} />

### Accessibility

#### Notification Badge

Notifications are a major use case for `CountBadge`. When the `CountBadge` value is updated in
real-time, screen readers must be supported with an `AriaLiveRegion` that will automatically
describe the change in the number of notifications. If the web app only updates `CountBadge` as part
of another screen update, then this use of `AriaLiveRegion` is unnecessary and not recommended.

- `Tooltip` is set on the `SecondaryButton` automatically applying the `aria-label` to the button.
- `aria-describedby` property is conditionally set on the `SecondaryButton` when greater than zero
  referencing a unique `id` for the `CountBadge` value .
- `AriaLiveRegion` is used around the `CountBadge`, enabling screen readers to monitor changes in
  value.
- `aria-label` string is conditionally set on `AriaLiveRegion` when greater than zero, describing
  "New notification"

<ExampleCodeBlock code={NotificationBadge} />

### Custom Styles

Count Badge supports custom styling via the `cs` prop. For more information, check our
["How To Customize Styles"](https://workday.github.io/canvas-kit/?path=/docs/styling-guides-customizing-styles--docs).

## Component API

<SymbolDoc name="CountBadge" fileName="/react/" />