Badge

Display badge, pill or tag

Polymorphic

Polymorphic component

Source

LLM docs

Docs

PackageIcon

Usage

Badge

Variant

Color

Size

Radius

import { Badge } from '@mantine/core';

function Demo() {
  return <Badge color="blue">Badge</Badge>;
}

When the variant prop is set to gradient, you can control the gradient with the gradient prop, which accepts an object with from, to and deg properties. If thegradient prop is not set, Badge will use theme.defaultGradient which can be configured on the theme object. The gradient prop is ignored when variant is not gradient.

Note that variant="gradient" supports only linear gradients with two colors. If you need a more complex gradient, use the Styles API to modify Badge styles.

Gradient badge

Gradient from

Gradient to

Gradient degree

import { Badge } from '@mantine/core';

function Demo() {
  return (
    <Badge
      size="xl"
      variant="gradient"
      gradient={{ from: 'blue', to: 'cyan', deg: 90 }}
    >
      Gradient badge
    </Badge>
  );
}

Rounded

Set the circle prop to reduce horizontal padding and make the badge width equal to its height:

import { Badge, Group } from '@mantine/core';

function Demo() {
  return (
    <Group>
      <Badge size="xs" circle>
        1
      </Badge>
      <Badge size="sm" circle>
        7
      </Badge>
      <Badge size="md" circle>
        9
      </Badge>
      <Badge size="lg" circle>
        3
      </Badge>
      <Badge size="xl" circle>
        8
      </Badge>
    </Group>
  );
}

Left and right sections

With left section

With right section

import { Badge, Group } from '@mantine/core';
import { AtIcon } from '@phosphor-icons/react';

function Demo() {
  const icon = <AtIcon size={12} />;
  return (
    <Group>
      <Badge leftSection={icon}>With left section</Badge>
      <Badge rightSection={icon}>With right section</Badge>
    </Group>
  );
}

Full width

Set fullWidth to make the badge span the full width of its parent element:

Full width badge

import { Badge } from '@mantine/core';

function Demo() {
  return <Badge fullWidth>Full width badge</Badge>;
}

Customize variant colors

You can customize colors for Badge and other component variants by adding variantColorResolver to your theme.

Lime filled

Orange light

Danger

import { ImageIcon, FingerprintIcon, WarningIcon } from '@phosphor-icons/react';
import {
  Badge,
  Group,
  MantineProvider,
  defaultVariantColorsResolver,
  VariantColorsResolver,
  parseThemeColor,
  rgba,
  darken,
} from '@mantine/core';

const variantColorResolver: VariantColorsResolver = (input) => {
  const defaultResolvedColors = defaultVariantColorsResolver(input);
  const parsedColor = parseThemeColor({
    color: input.color || input.theme.primaryColor,
    theme: input.theme,
  });

  // Override some properties for variant
  if (parsedColor.isThemeColor && parsedColor.color === 'lime' && input.variant === 'filled') {
    return {
      ...defaultResolvedColors,
      color: 'var(--mantine-color-black)',
      hoverColor: 'var(--mantine-color-black)',
    };
  }

  // Completely override variant
  if (input.variant === 'light') {
    return {
      background: rgba(parsedColor.value, 0.1),
      hover: rgba(parsedColor.value, 0.15),
      border: `1px solid ${parsedColor.value}`,
      color: darken(parsedColor.value, 0.1),
    };
  }

  // Add new variants support
  if (input.variant === 'danger') {
    return {
      background: 'var(--mantine-color-red-9)',
      hover: 'var(--mantine-color-red-8)',
      color: 'var(--mantine-color-white)',
      border: 'none',
    };
  }

  return defaultResolvedColors;
};

function Demo() {
  return (
    <MantineProvider theme={{ variantColorResolver }}>
      <Group>
        <Badge color="lime.4" variant="filled">
          Lime filled
        </Badge>

        <Badge color="orange" variant="light">
          Orange light
        </Badge>

        <Badge variant="danger">
          Danger
        </Badge>
      </Group>
    </MantineProvider>
  );
}

autoContrast

Badge supports the autoContrast prop and theme.autoContrast. If autoContrast is set either on Badge or on the theme, the content color will be adjusted to have sufficient contrast with the value specified in the color prop.

Note that the autoContrast feature works only if you use the color prop to change the background color. autoContrast works only with the filled variant.

Default

Auto contrast

import { Badge, Group } from '@mantine/core';

function Demo() {
  return (
    <Group>
      <Badge size="lg" color="lime.4">
        Default
      </Badge>
      <Badge autoContrast size="lg" color="lime.4">
        Auto contrast
      </Badge>
    </Group>
  );
}

Styles API

Badge supports the Styles API; you can add styles to any inner element of the component with the classNames prop. Follow the Styles API documentation to learn more.

Badge component

Component Styles API

Hover over selectors to highlight corresponding elements

/*
 * Hover over selectors to apply outline styles
 *
 */

Polymorphic component

Badge is a polymorphic component – its default root element is div, but it can be changed to any other element or component with the component prop:

import { Badge } from '@mantine/core';

function Demo() {
  return <Badge component="a" />;
}

You can also use components in the component prop, for example, Next.js Link:

import Link from 'next/link';
import { Badge } from '@mantine/core';

function Demo() {
  return <Badge component={Link} href="/" />;
}

Polymorphic components with TypeScript
Note that polymorphic component prop types are different from regular components – they do not extend HTML element props of the default element. For example, BadgeProps does not extend React.ComponentProps'<'div'>' although div is the default element.
If you want to create a wrapper for a polymorphic component that is not polymorphic (does not support the component prop), then your component props interface should extend HTML element props, for example:
import type { BadgeProps, ElementProps } from '@mantine/core';

interface MyBadgeProps extends BadgeProps,
  ElementProps<'a', keyof BadgeProps> {}
If you want your component to remain polymorphic after wrapping, use the polymorphic function described in this guide.

BackgroundImage

Card