# Badge

A badge is a visual indicator that communicates a status or description of an associated component.

## Best practices

### Do

- Use badges to highlight status, notifications, or key information.
- Choose the appropriate badge appearance, such as status or severity, to match its meaning.
- Use clear, concise text within the badge.
- Place the badge in proximity to the item that it relates to.
- Use badge color coding consistently.

### Don't

- Use badges for purely decorative purposes.
- Overuse badges, as this can dilute their impact.
- Use excessively long text within a badge.
- Rely solely on color to convey meaning. Use text or icons as well.

## Behavior and states

- Badges don’t have a built-in maximum width and will keep growing.
- By default, badges don’t receive focus.
- If you build interaction into a badge, like including a tooltip for more context, make sure to include focus.
- They use short text, color, and icons for quick recognition and are placed near the relevant content.

## Default

Source: CoreAI.

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

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

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

export const Default = (props: BadgeProps): JSXElement => <Badge {...props}/>;

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.

### Badge API

Define a styled Badge, using the `useBadge_unstable` hook.

```ts
interface BadgeProps {
  /**
   * A Badge can be filled, outline, ghost, inverted
   */
  appearance?: "filled" | "ghost" | "outline" | "tint";

  as?: "div";

  children?: any;

  className?: string;

  /**
   * A Badge can be one of preset colors
   */
  color?: "brand" | "success" | "warning" | "danger" | "important" | "informative" | "severe" | "subtle";

  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";

  ref?: Ref<HTMLDivElement>;

  /**
   * A Badge can be square, circular or rounded.
   */
  shape?: "circular" | "rounded" | "square";

  /**
   * 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 badge can have a `filled`, `ghost`, `outline`, or `tint` appearance. The default is `filled`.

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

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

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

export const Appearance = (): JSXElement => {
    return (<>
      <Badge appearance="filled">999+</Badge>
      <Badge appearance="ghost">999+</Badge>
      <Badge appearance="outline">999+</Badge>
      <Badge appearance="tint">999+</Badge>
    </>);
};

export default Appearance;
```

## Color

Source: Fluent, adapted for CoreAI.

A badge can have different colors. The available colors are `brand`, `danger`, `important`, `informative`, `severe`, `subtle`, `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-badge--color.tsx)

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

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

export const Color = (): JSXElement => {
    return (<>
      <Badge appearance="filled" color="brand">
        999+
      </Badge>
      <Badge appearance="filled" color="danger">
        999+
      </Badge>
      <Badge appearance="filled" color="important">
        999+
      </Badge>
      <Badge appearance="filled" color="informative">
        999+
      </Badge>
      <Badge appearance="filled" color="severe">
        999+
      </Badge>
      <Badge appearance="filled" color="subtle">
        999+
      </Badge>
      <Badge appearance="filled" color="success">
        999+
      </Badge>
      <Badge appearance="filled" color="warning">
        999+
      </Badge>
    </>);
};

export default Color;
```

## Color And Appearance

Source: Fluent, adapted for CoreAI.

`ghost-subtle` and `outline-subtle` are intended only for use on a branded background — the boxed "On brand background:" examples above demonstrate the intended usage context.

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

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

import type { JSXElement } from "@coreai-ds/react-components";
import { makeStyles } from "@coreai-ds/react-components";
import { tokens } from "@coreai-ds/react-components";
import type { BadgeProps } from "@coreai-ds/react-components";
import { Badge } from "@coreai-ds/react-components";
import { ClipboardPasteRegular as PasteIcon } from "@fluentui/react-icons";
import * as React from 'react';

const useStyles = makeStyles({
    example: {
        display: 'flex',
        flexDirection: 'column',
        gap: tokens.spacingVerticalS,
    },
    badge: {
        display: 'flex',
        alignItems: 'center',
        gap: tokens.spacingHorizontalS,
    },
    brand: {
        display: 'flex',
        alignItems: 'center',
        gap: tokens.spacingHorizontalS,
        backgroundColor: tokens.colorBrandBackground,
        padding: `${tokens.spacingVerticalS} ${tokens.spacingHorizontalM}`,
        borderRadius: tokens.borderRadiusMedium,
    },
    brandLabel: {
        color: tokens.colorNeutralForegroundOnBrand,
        fontFamily: tokens.fontFamilyBase,
        fontSize: tokens.fontSizeBase200,
        lineHeight: tokens.lineHeightBase200,
        fontWeight: tokens.fontWeightSemibold,
    },
});

const Badges = (props: BadgeProps) => {
    const styles = useStyles();
    const { appearance } = props;
    const colors: BadgeProps['color'][] = [
        'brand',
        'danger',
        'important',
        'informative',
        'severe',
        'subtle',
        'success',
        'warning',
    ];
    const isSubtleOnBrandOnly = appearance === 'ghost' || appearance === 'outline';
    return (<div className={styles.badge}>
      {colors.map(color => {
            // `ghost-subtle` and `outline-subtle` are only meant to be used on a branded background,
            // so they are rendered within an explicit "brand surface" demo container instead of the
            // ambient story background.
            if (color === 'subtle' && isSubtleOnBrandOnly) {
                return (<div key={`${appearance}-${color}`} className={styles.brand}>
              <span className={styles.brandLabel}>On brand background:</span>
              <Badge appearance={appearance} color={color} icon={<PasteIcon />}>
                999+
              </Badge>
            </div>);
            }
            return (<Badge key={`${appearance}-${color}`} appearance={appearance} color={color} icon={<PasteIcon />}>
            999+
          </Badge>);
        })}
    </div>);
};

export const ColorAndAppearance = (): JSXElement => {
    const styles = useStyles();
    return (<div className={styles.example}>
      <h3>Filled</h3>
      <Badges appearance="filled"/>
      <h3>Ghost</h3>
      <Badges appearance="ghost"/>
      <h3>Outline</h3>
      <Badges appearance="outline"/>
      <h3>Tint</h3>
      <Badges appearance="tint"/>
    </div>);
};

export default ColorAndAppearance;
```

## Icon

Source: Fluent, adapted for CoreAI.

A badge can display an icon. If the icon is meaningful, then either the icon must have a label or the parent control's label must include the information conveyed by the icon.

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

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

import type { JSXElement } from "@coreai-ds/react-components";
import { Badge } from "@coreai-ds/react-components";
import { ClipboardPasteRegular as PasteIcon } from "@fluentui/react-icons";
import * as React from 'react';

export const Icon = (): JSXElement => {
    return <Badge size="medium" icon={<PasteIcon />}/>;
};

export default Icon;
```

## Shapes

Source: Fluent, adapted for CoreAI.

A badge can have `square`, `rounded` or `circular` shape. The default is `circular`.

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

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

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

export const Shapes = (): JSXElement => {
    return (<>
      <Badge shape="square"/>
      <Badge shape="rounded"/>
      <Badge shape="circular"/>
    </>);
};

export default Shapes;
```

## Sizes

Source: Fluent, adapted for CoreAI.

A 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-badge--sizes.tsx)

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

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

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

export default Sizes;
```

## Resources

- [Figma component](https://www.figma.com/design/eXfSQrRg3poHRgmr0ivN5V/CoreAI-Figma-Library?node-id=151708-5234)
- [Fluent guidance](https://fluent2.microsoft.design/components/web/react/core/badge/usage)