# Counter Badge

Badge that displays a numerical count.

## Default

Source: CoreAI.

[Download source](/coreai-design-system/source/examples/components-badge-counter-badge--default.tsx)

```tsx
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.

import type { JSXElement } from "@coreai-ds/react-components";
import { CounterBadge } from "@coreai-ds/react-components";
import * as React from 'react';

export const Default = (): JSXElement => <CounterBadge count={5}/>;

export default Default;
```

## API

Generated CoreAI prop summaries, not replacement type declarations. Most native DOM/event and ARIA props are omitted. `?` means optional; JSDoc shows defaults, deprecations, and conditional requirements. Defaults assume the standard CoreAI provider.

### CounterBadge API

Define a styled CounterBadge, using the `useCounterBadge_unstable` hook.

```ts
interface CounterBadgeProps {
  /**
   * A Badge can have different appearances that emphasize certain parts of it:
   *  - filled: The default appearance if one is not specified.
   *    The badge background is filled with color with a contrasting foreground text to match.
   *  - ghost: The badge background is transparent, with the foreground text taking color to emphasize it.
   * @default filled
   */
  appearance?: "filled" | "ghost";

  as?: "div";

  children?: any;

  className?: string;

  /**
   * Semantic colors for a counter badge
   * @default brand
   */
  color?: "brand" | "danger" | "important" | "informative";

  /**
   * Value displayed by the Badge
   * @default 0
   */
  count?: number;

  /**
   * If a dot should be displayed without the count
   * @default false
   */
  dot?: boolean;

  icon?: WithSlotShorthandValue<{ as?: "span"; } & Omit<Omit<DetailedHTMLProps<HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, "ref"> & { ref?: ((instance: HTMLSpanElement | null) => void) | RefObject<HTMLSpanElement> | null; }, "children"> & { children?: any; }> | null | undefined;

  /**
   * A Badge can position the icon before or after the content.
   */
  iconPosition?: "before" | "after";

  /**
   * Max number to be displayed
   * @default 99
   */
  overflowCount?: number;

  ref?: Ref<HTMLDivElement>;

  /**
   * A Badge can be circular or rounded
   * @default circular
   */
  shape?: "circular" | "rounded";

  /**
   * If the badge should be shown when count is 0
   * @default false
   */
  showZero?: boolean;

  /**
   * A Badge can be on of several preset sizes.
   */
  size?: "small" | "medium" | "large" | "extra-large" | "tiny" | "extra-small";

  style?: CSSProperties;
}
```

## Implementation

CoreAI 0.12.0; Fluent 9.74.9.

[Setup and dependencies](/coreai-design-system/guides/Package.md).

Import components from `@coreai-ds/react-components`. CoreAI guidance above takes precedence over API demonstration examples.

Note: Storybook-only layout decorators are omitted. Examples use the documentation preview spacing instead.

## Appearance

Source: Fluent, adapted for CoreAI.

A counter badge can have a `ghost` or `filled` appearance. The default is `filled`.

[Download source](/coreai-design-system/source/examples/components-badge-counter-badge--appearance.tsx)

```tsx
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.

import type { JSXElement } from "@coreai-ds/react-components";
import { CounterBadge } from "@coreai-ds/react-components";
import * as React from 'react';

export const Appearance = (): JSXElement => {
    return (<>
      <CounterBadge count={5} appearance="filled"/>
      <CounterBadge count={5} appearance="ghost"/>
    </>);
};

export default Appearance;
```

## Color

Source: Fluent, adapted for CoreAI.

A counter badge can be different colors. The available colors are `brand`, `danger`, `important`, `informative`, `severe`, `severe`, `success` or `warning`. The default is `brand`. Information conveyed by color should also be communicated in another way to meet [accessibility requirements](https://w3c.github.io/wcag/guidelines/22/#use-of-color).

[Download source](/coreai-design-system/source/examples/components-badge-counter-badge--color.tsx)

```tsx
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.

import type { JSXElement } from "@coreai-ds/react-components";
import { CounterBadge } from "@coreai-ds/react-components";
import * as React from 'react';

export const Color = (): JSXElement => {
    return (<>
      <CounterBadge appearance="filled" color="brand" count={5}/>
      <CounterBadge appearance="filled" color="danger" count={5}/>
      <CounterBadge appearance="filled" color="important" count={5}/>
      <CounterBadge appearance="filled" color="informative" count={5}/>
    </>);
};

export default Color;
```

## Dot

Source: Fluent, adapted for CoreAI.

A counter badge can display a small dot.

[Download source](/coreai-design-system/source/examples/components-badge-counter-badge--dot.tsx)

```tsx
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.

import type { JSXElement } from "@coreai-ds/react-components";
import { CounterBadge } from "@coreai-ds/react-components";
import * as React from 'react';

export const Dot = (): JSXElement => <CounterBadge count={0} dot/>;

export default Dot;
```

## Shapes

Source: Fluent, adapted for CoreAI.

A counter badge can have a `rounded` or `circular` shape. The default is `circular`.

[Download source](/coreai-design-system/source/examples/components-badge-counter-badge--shapes.tsx)

```tsx
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.

import type { JSXElement } from "@coreai-ds/react-components";
import { CounterBadge } from "@coreai-ds/react-components";
import * as React from 'react';

export const Shapes = (): JSXElement => {
    return (<>
      <CounterBadge count={5} shape="circular"/>
      <CounterBadge count={5} shape="rounded"/>
    </>);
};

export default Shapes;
```

## Sizes

Source: Fluent, adapted for CoreAI.

A counter badge supports `tiny`, `extra-small`, `small`, `medium`, `large`, and `extra-large` sizes. The default is `medium`.

[Download source](/coreai-design-system/source/examples/components-badge-counter-badge--sizes.tsx)

```tsx
// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.

import type { JSXElement } from "@coreai-ds/react-components";
import { CounterBadge } from "@coreai-ds/react-components";
import * as React from 'react';

export const Sizes = (): JSXElement => {
    return (<>
      <CounterBadge count={5} size="tiny"/>
      <CounterBadge count={5} size="extra-small"/>
      <CounterBadge count={5} size="small"/>
      <CounterBadge count={5} size="medium"/>
      <CounterBadge count={5} size="large"/>
      <CounterBadge count={5} size="extra-large"/>
    </>);
};

export default Sizes;
```