Badge

View source on GitHub
See recent changes on GitHub

Badge is a label that indicates status or importance. Badges should provide quick recognition.

also known as Lozenge, Label, Stamp, Flag

Figma:
Ready
Responsive:
Ready
Adaptive:
N/A

Props

Component props
Name
Type
Default
text
Required
string
-

Text displayed inside of the Badge. Sentence case is preferred.

dataTestId
string
-

Available for testing purposes, if needed. Consider better queries before using this prop.

position
"middle" | "top"
"middle"

Badge position relative to its parent element. See the positioning variant to learn more.

tooltip
{
  accessibilityLabel?: string;
  idealDirection?: "up" | "right" | "down" | "left";
  text: string;
  zIndex?: Indexable;
}
-

Adds a Tooltip on hover/focus of the Badge. To convey the interaction, it also displays an Icon. See the type variant to learn more.

type
"info"
| "error"
| "warning"
| "success"
| "neutral"
| "recommendation"
| "darkWash"
| "lightWash"
"info"

Determines the style of the badge. See the type variant to learn more.

Usage guidelines

When to use
  • Labeling and bringing awareness to a specific element or feature (e.g., something is new or required).
When not to use
  • Providing feedback at the element level (e.g., displaying error messages). Use inline text instead.
  • Requiring interaction from users since Badges are always static and non-interactive.

Best practices

Do

Use established color patterns so users can quickly scan and identify sentiment. However, the badge text should always clearly indicate the sentiment, so color is not the sole indicator of information.

Don't

Use colored badges over media. Instead use the dark or light wash.

Do

Align the badge to the top of large accompanying text (anything larger than 16px). Center align for standard size text.

Don't

Use complex or verbose language. Instead use a single, scannable word. For example: 'New'.

Accessibility

The badge text is read out by assistive technologies like screen readers so all users can access the meaning of the badge in context. Text should demonstrate the sentiment clearly enough to be understood immediately without relying on color alone.

Localization

Be sure to localize all text strings. Note that localization can lengthen text by 20 to 30 percent.

import { Badge, Flex } from 'gestalt';

export default function Example() {
  return (
    <Flex
      alignItems="center"
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <Badge
        text="คุณลักษณะใหม่"
        tooltip={{
          text: 'ภาพตัดปะเป็นคุณลักษณะใหม่สำหรับผู้ใช้เบต้า',
          idealDirection: 'up',
        }}
      />
    </Flex>
  );
}

Variants

Type

Badge is available in five styles. Each type represents a messaging sentiment.

  1. Info (default)
    Communicates helpful information or an important attribute. For example, 'New' or 'Help'.

  2. Success
    Indicates a constructive or successful state. For example, 'Available', 'Completed', 'Approved' or 'Added'.

  3. Warning
    Communicates cautionary or time-sensitive information to the user. For example, 'Busy', 'Missing' or 'Warning'.

  4. Error
    Informs the user of problems or errors that require potential action to correct. For example, 'Deleted' or 'Cancelled'.

  5. Neutral
    Indicates a general, non-critical status update. For example, 'Unavailable' or 'Not started'.

  6. Recommendation
    Highlights a suggestion that will improve the experience and achieve better results. For example, 'Recommended for you'.

import { Badge, Flex, Table, Text } from 'gestalt';

export default function Example() {
  return (
    <Flex
      alignItems="center"
      gap={4}
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <Table accessibilityLabel="Type examples">
        <Table.Header>
          <Table.Row>
            {['Type', 'Example'].map((header) => (
              <Table.HeaderCell key={header}>
                <Text weight="bold">{header}</Text>
              </Table.HeaderCell>
            ))}
          </Table.Row>
        </Table.Header>

        <Table.Body>
          <Table.Row>
            <Table.Cell>
              <Text>Info</Text>
            </Table.Cell>
            <Table.Cell>
              <Flex direction="column" gap={2}>
                <Text size="300">
                  Ads & Campaigns <Badge text="New" type="info" />
                </Text>
                <Text size="300">
                  Ads & Campaigns{' '}
                  <Badge
                    text="New"
                    tooltip={{
                      text: 'Collages is a new feature',
                      idealDirection: 'up',
                    }}
                    type="info"
                  />
                </Text>
              </Flex>
            </Table.Cell>
          </Table.Row>

          <Table.Row>
            <Table.Cell>
              <Text>Success</Text>
            </Table.Cell>
            <Table.Cell>
              <Flex direction="column" gap={2}>
                <Text size="300">
                  Ads & Campaigns <Badge text="Completed" type="success" />
                </Text>
                <Text size="300">
                  Ads & Campaigns{' '}
                  <Badge
                    text="Completed"
                    tooltip={{
                      text: 'Your onboarding is almost completed',
                      idealDirection: 'up',
                    }}
                    type="success"
                  />
                </Text>
              </Flex>
            </Table.Cell>
          </Table.Row>

          <Table.Row>
            <Table.Cell>
              <Text>Warning</Text>
            </Table.Cell>
            <Table.Cell>
              <Flex direction="column" gap={2}>
                <Text size="300">
                  Ads & Campaigns{' '}
                  <Badge text="Needs attention" type="warning" />
                </Text>
                <Text size="300">
                  Ads & Campaigns{' '}
                  <Badge
                    text="Needs attention"
                    tooltip={{
                      text: 'Your account needs attention',
                      idealDirection: 'up',
                    }}
                    type="warning"
                  />
                </Text>
              </Flex>
            </Table.Cell>
          </Table.Row>

          <Table.Row>
            <Table.Cell>
              <Text>Error</Text>
            </Table.Cell>
            <Table.Cell>
              <Flex direction="column" gap={2}>
                <Text size="300">
                  Ads & Campaigns <Badge text="Failed" type="error" />
                </Text>
                <Text size="300">
                  Ads & Campaigns{' '}
                  <Badge
                    text="Failed"
                    tooltip={{
                      text: 'Your uploading failed',
                      idealDirection: 'up',
                    }}
                    type="error"
                  />
                </Text>
              </Flex>
            </Table.Cell>
          </Table.Row>

          <Table.Row>
            <Table.Cell>
              <Text>Neutral</Text>
            </Table.Cell>
            <Table.Cell>
              <Flex direction="column" gap={2}>
                <Text size="300">
                  Ads & Campaigns <Badge text="Not started" type="neutral" />
                </Text>{' '}
                <Text size="300">
                  Ads & Campaigns{' '}
                  <Badge
                    text="Not started"
                    tooltip={{
                      text: 'Your campaign has not started',
                      idealDirection: 'up',
                    }}
                    type="neutral"
                  />
                </Text>{' '}
              </Flex>
            </Table.Cell>
          </Table.Row>

          <Table.Row>
            <Table.Cell>
              <Text>Recommendation</Text>
            </Table.Cell>
            <Table.Cell>
              <Flex direction="column" gap={2}>
                <Text size="300">
                  Ads & Campaigns{' '}
                  <Badge text="Recommended for you" type="recommendation" />
                </Text>{' '}
                <Text size="300">
                  Ads & Campaigns{' '}
                  <Badge
                    text="Recommended for you"
                    tooltip={{
                      text: 'This business product is recommended for you',
                      idealDirection: 'up',
                    }}
                    type="recommendation"
                  />
                </Text>
              </Flex>
            </Table.Cell>
          </Table.Row>
        </Table.Body>
      </Table>
    </Flex>
  );
}

Over media

Badge may be used over media using two wash styles.

  1. Over media - Light wash
    The light wash badge should be used over media that is dark or utilizes a dark gradient overlay.

  2. Over media - Dark wash
    The dark wash badge should be used over media that is light or utilizes a light gradient overlay.

import { Badge, Box, Flex, Image, Mask } from 'gestalt';

export default function Example() {
  return (
    <Flex
      alignItems="center"
      gap={4}
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <Flex gap={{ column: 8, row: 4 }} wrap>
        <Mask height={150} rounding={2} width={280}>
          <Image
            alt="Botanical art in coral and green"
            fit="cover"
            naturalHeight={1}
            naturalWidth={1}
            src="https://i.ibb.co/cbjgZft/img-door.jpg"
          >
            <Box padding={4}>
              <Flex gap={2}>
                <Badge text="Light wash" type="lightWash" />
                <Badge
                  text="Light wash"
                  tooltip={{
                    text: 'Tooltip text',
                    idealDirection: 'up',
                  }}
                  type="lightWash"
                />
              </Flex>
            </Box>
          </Image>
        </Mask>
        <Mask height={150} rounding={2} width={280}>
          <Image
            alt="Botanical art in coral and green"
            fit="cover"
            naturalHeight={1}
            naturalWidth={1}
            src="https://i.ibb.co/7bQQYkX/stock2.jpg"
          >
            <Box padding={4}>
              <Flex gap={2}>
                <Badge text="Dark wash" type="darkWash" />
                <Badge
                  text="Dark wash"
                  tooltip={{
                    text: 'Tooltip text',
                    idealDirection: 'up',
                  }}
                  type="darkWash"
                />
              </Flex>
            </Box>
          </Image>
        </Mask>
      </Flex>
    </Flex>
  );
}

Positioning

By default, Badge is rendered inline within the parent element. However, the position prop can be used to adjust the alignment. Badges should align to the top of large accompanying text.

import { Badge, Flex, Text } from 'gestalt';

export default function Example() {
  return (
    <Flex
      alignItems="center"
      gap={4}
      height="100%"
      justifyContent="center"
      width="100%"
    >
      <Flex direction="column" gap={4}>
        <Text size="300">
          Ads & Campaigns <Badge text="New" />
        </Text>
        <Text size="600">
          Ads & Campaigns <Badge position="top" text="Beta" />
        </Text>
        <Text size="300">
          Ads & Campaigns{' '}
          <Badge
            text="New"
            tooltip={{
              text: 'This is a beta feature',
              idealDirection: 'up',
            }}
          />
        </Text>
        <Text size="600">
          Ads & Campaigns{' '}
          <Badge
            position="top"
            text="Beta"
            tooltip={{
              text: 'This is a beta feature',
              idealDirection: 'up',
            }}
          />
        </Text>
      </Flex>
    </Flex>
  );
}

Writing

Do
  • Use a single word to describe the status of an element. For example, “New” not “New post.”
  • Where applicable, describe the status in past tense. For example, “Archived” not “Archive.”
Don't
  • Use conflicting language with defined type sentiments. For example, the error badge should not say “Complete.”

Component quality checklist

Component quality checklist
Quality item
Status
Status description
Figma Library
Ready
Component is available in Figma for web and mobile web.
Responsive Web
Ready
Component responds to changing viewport sizes in web and mobile web.

Status
Status is a graphic indicator of an element’s state.

Tooltip
Tooltip is a floating text label that succinctly describes the function of an interactive element.

Edit page on GitHub