Badge | CoreAI design system

Default

Loading interactive example. Full source is available below.

View example source

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

Resources

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.

API referenceGenerated CoreAI prop and type summaries

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.

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.

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

Loading interactive example. Full source is available below.

Download source

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

Loading interactive example. Full source is available below.

Download source

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

Loading interactive example. Full source is available below.

Download source

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

Loading interactive example. Full source is available below.

Download source

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

Loading interactive example. Full source is available below.

Download source

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

Loading interactive example. Full source is available below.

Download source

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