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

In the example below, we're rendering a basic `CountBadge` with its `default` and `inverse`
variants. The `inverse` variant is intended for darker backgrounds to create more contrast.

<ExampleCodeBlock code={Basic} />

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

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

#### Notes on accessibility for the example below

- `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-how-to-customize-styles--docs).

## Component API

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