Badge

A Badge is a visual text label that describes an attribute of an object.

<Box display="flex" columnGap="space40" rowGap="space60" flexWrap="wrap">
  <Badge as="span" variant="neutral">
    Neutral
  </Badge>
  <Badge as="span" variant="warning">
    Warning
  </Badge>
  <Badge as="span" variant="error">
    Error
  </Badge>
  <Badge as="span" variant="success">
    Success
  </Badge>
  <Badge as="span" variant="new">
    New
  </Badge>
  <Badge as="span" variant="subaccount">
    Subaccount
  </Badge>
  <Badge as="span" variant="decorative10">
    Decorative 10
  </Badge>
  <Badge as="span" variant="decorative20">
    Decorative 20
  </Badge>
  <Badge as="span" variant="decorative30">
    Decorative 30
  </Badge>
  <Badge as="span" variant="decorative40">
    Decorative 40
  </Badge>
  <Badge as="span" variant="brand10">
    Brand 10
  </Brand>
  <Badge as="span" variant="brand20">
    Brand 20
  </Brand>
  <Badge as="span" variant="brand30">
    Brand 30
  </Brand>
  <Badge as="span" variant="neutral_counter">
    1
  </Badge>
  <Badge as="span" variant="error_counter">
    1
  </Badge>
  <Badge as="span" variant="notification_counter">
    100
  </Badge>
</Box>

Guidelines

About Badge

A Badge can be used to label a piece of UI for quick identification. It can be used in a wide variety of situations, such as labeling Beta product features or an attribute such as “Inbound” or “Outbound”. A Badge can also be used to show a count, such as the number of new messages.

A Badge should contain text content and can optionally contain an Icon. Text length should be kept short, generally 1-3 words.

Accessibility

Ensure that Badge text can be understood immediately, so the user does not have to rely on color to communicate meaning.
For Status Badges, it's recommended to include an icon to reinforce meaning.

Examples

Variants

Use Badge variants such as success and warning when the Badge is intended to communicate a specific, semantic attribute, such as “warning” or “new”. These Badges should generally have an Icon that should be prefixed before the text.

Neutral

Use the neutral Badge to highlight neutral attributes of an object. An information icon is optional.

<Box display="flex" columnGap="space80">
  <Badge as="span" variant="neutral">
    Neutral
  </Badge>
  <Badge as="span" variant="neutral">
    <InformationIcon decorative />
    Neutral
  </Badge>
</Box>

Warning

Use the warning Badge to highlight attributes of an object that the user must be made aware of to avoid incurring an error. A warning icon is recommended.

<Box display="flex" columnGap="space80">
  <Badge as="span" variant="warning">
    Warning
  </Badge>
  <Badge as="span" variant="warning">
    <WarningIcon decorative />
    Warning
  </Badge>
</Box>

Error Badge

Use the error Badge to highlight attributes of an object that signal to the user that they object is in bad or broken state. An error icon is recommended.

Do not use an error Badge unless there is additional guidance elsewhere on the page that explains to the user how to fix the broken state.

For additional guidance on how to compose error messages, refer to the error state pattern.

<Box display="flex" columnGap="space80">
  <Badge as="span" variant="error">
    Error
  </Badge>
  <Badge as="span" variant="error">
    <ErrorIcon decorative />
    Error
  </Badge>
</Box>

Success Badge

Use the success Badge to highlight attributes of an object that were completed or are considered to be in a good state. A success icon is recommended.

<Box display="flex" columnGap="space80">
  <Badge as="span" variant="success">
    Success
  </Badge>
  <Badge as="span" variant="success">
    <SuccessIcon decorative />
    Success
  </Badge>
</Box>

New Badge

Use the new Badge to highlight an object that is new, beta, pilot, or experimental. A new icon is recommended.

<Box display="flex" columnGap="space80">
  <Badge as="span" variant="new">
    New
  </Badge>
  <Badge as="span" variant="new">
    <NewIcon decorative />
    New
  </Badge>
</Box>

Subaccount Badge

The subaccount Badge is reserved for specific use cases only. Consult with the Console team before implementing this variant. A users icon is recommended.

<Box display="flex" columnGap="space80">
  <Badge as="span" variant="subaccount">
    Subaccount
  </Badge>
  <Badge as="span" variant="subaccount">
    <UsersIcon decorative />
    Subaccount
  </Badge>
</Box>

Decorative

Use the decorative Badge to highlight attributes that do not have a strictly semantic meaning (like warning, error, or success) but would benefit from the visual affordance of differently-colored Badges. Icons are optional, and should appear before the text.

<Box display="flex" columnGap="space80">
  <Badge as="span" variant="decorative10">
    <VoiceCapableIcon decorative />
    Voice
  </Badge>
  <Badge as="span" variant="decorative20">
    <SMSCapableIcon decorative />
    SMS
  </Badge>
  <Badge as="span" variant="decorative30">
    <MMSCapableIcon decorative />
    MMS
  </Badge>
  <Badge as="span" variant="decorative40">
    <FaxCapableIcon decorative />
    MMS
  </Badge>
</Box>

Brand

Use the brand Badge for cross-selling opportunities across platforms (e.g., Segment, SendGrid, Communications, Flex) and pricing plans. Use these sparingly.

<Box display="flex" columnGap="space80">
  <Badge as="span" variant="brand10">
    <ProductCommsIcon decorative />
    Twilio CPaaS
  </Badge>
  <Badge as="span" variant="brand20">
    <ProductSendGridIcon decorative />
    Twilio SendGrid
  </Badge>
  <Badge as="span" variant="brand30">
    <ProductSegmentIcon decorative />
    Twilio Segment CDP
  </Badge>
</Box>

Counter

Use the counter Badge to visually highlight a count in a UI, like the number of pending invitations or the number of errors.

Counter Badges have neutral, error, and notification variants. The error variant should always include an error icon. The notification variant informs users of new or unread items, such as messages, notifications, or updates.

<Box display="flex" columnGap="space80">
  <Badge as="span" variant="neutral_counter">
    100
  </Badge>
  <Badge as="span" variant="error_counter">
    100
  </Badge>
  <Badge as="span" variant="notification_counter">
    100
  </Badge>
</Box>

Badge with anchor functionality

A badge can link to other pages. To do so, add an href prop and set as="a" on the Badge.

<Box display="flex" columnGap="space40" rowGap="space60" flexWrap="wrap">
  <Badge as="a" href="https://www.twilio.com/docs" variant="neutral">
    <InformationIcon decorative/>
    Info
  </Badge>
</Box>

Badge with button functionality

A Badge can also be used to trigger an in-page action, such as showing a Popover or Modal. To do so, provide an onClick event handler and set as="button" on the Badge. Refer to the PopoverBadgeButton section of the Popover docs to add a Popover to a Badge.

const InteractiveTrigger = () => {
  // Modal properties
  const [isOpen, setIsOpen] = React.useState(false);
  const handleOpen = () => setIsOpen(true);
  const handleClose = () => setIsOpen(false);
  const modalHeadingID = useUID();

  return (
    <Box display="flex" columnGap="space80">
      <Badge as="button" variant="new" onClick={handleOpen}>
        <NewIcon decorative/>
        Beta
      </Badge>
      <Modal ariaLabelledby={modalHeadingID} isOpen={isOpen} onDismiss={handleClose} size="default">
        <ModalHeader>
          <ModalHeading as="h3" id={modalHeadingID}>
            Beta mode
          </ModalHeading>
        </ModalHeader>
        <ModalBody>

          <Paragraph marginBottom="space0">
            This product is in beta, which means we're still working out all the kinks. Let us know if you spot any bugs.
          </Paragraph>

        </ModalBody>
        <ModalFooter>
          <ModalFooterActions>
            <Button variant="primary" onClick={handleClose}>Got it</Button>
          </ModalFooterActions>
        </ModalFooter>
      </Modal>
      <PopoverContainer baseId="popover-example">
        <PopoverBadgeButton variant="new">
          <NewIcon decorative/>
          Beta
        </PopoverBadgeButton>
        <Popover aria-label="Popover">

        This product is in beta, which means we're still working out all the kinks. Let us know if you spot any bugs.

        </Popover>
      </PopoverContainer>
    </Box>
  );
};

render(
  <InteractiveTrigger />
)

Small Badges

Use a small Badge only when vertical density is a concern. The guidelines for using variants in a small Badge are the same as in their default size.

<Box display="flex" columnGap="space40" rowGap="space60" flexWrap="wrap">
  <Badge as="span" size="small" variant="neutral">
    Neutral
  </Badge>
  <Badge as="span" size="small" variant="warning">
    Warning
  </Badge>
  <Badge as="span" size="small" variant="error">
    Error
  </Badge>
  <Badge as="span" size="small" variant="success">
    Success
  </Badge>
  <Badge as="span" size="small" variant="new">
    New
  </Badge>
  <Badge as="span" size="small" variant="subaccount">
    Subaccount
  </Badge>
</Box>

Composition notes

Use a Badge when you want to add a label to a piece of UI for quick identification and navigation.

Badge labels should be 1-3 words and ideally less than 20 characters. Badge labels can also be numbers.

Use sentence case for Badge labels. Do not wrap Badge text to more than one line.

Use the same grammatical construction for a set of Badges. For example, if a set of Badges highlights statuses, make each Badge an adjective.

Use cases

Call attention to attributes of table items

<Table tableLayout="auto">
  <THead>
    <Tr>
      <Th>Call SID</Th>
      <Th>Direction</Th>
      <Th>Date</Th>
    </Tr>
  </THead>
  <TBody>
    <Tr>
      <Td>
        <Text fontFamily="fontFamilyCode" as="span">
          CA0yc4mxi6cn4z13bte7qmflc2drc85mlp
        </Text>
      </Td>
      <Td>
        <Badge variant="decorative20" as="span">
          Inbound
        </Badge>
      </Td>
      <Td>2020-09-17, 16:24:28 PDT</Td>
    </Tr>
    <Tr>
      <Td>
        <Text fontFamily="fontFamilyCode" as="span">
          CA0yc4mxi6cn4z13bte7qmflc2drc85mlp
        </Text>
      </Td>
      <Td>
        <Badge variant="decorative40" as="span">
          Outbound
        </Badge>
      </Td>
      <Td>2020-09-17, 16:24:28 PDT</Td>
    </Tr>
    <Tr>
      <Td>
        <Text fontFamily="fontFamilyCode" as="span">
          CA0yc4mxi6cn4z13bte7qmflc2drc85mlp
        </Text>
      </Td>
      <Td>
        <Badge variant="decorative40" as="span">
          Outbound
        </Badge>
      </Td>
      <Td>2020-09-17, 16:24:28 PDT</Td>
    </Tr>
    <Tr>
      <Td>
        <Text fontFamily="fontFamilyCode" as="span">
          CA0yc4mxi6cn4z13bte7qmflc2drc85mlp
        </Text>
      </Td>
      <Td>
        <Badge variant="decorative20" as="span">
          Inbound
        </Badge>
      </Td>
      <Td>2020-09-17, 16:24:28 PDT</Td>
    </Tr>
  </TBody>
</Table>

Identify an item as as a beta release

<Card>
  <Box display="flex" columnGap="space40">
    <Heading as="h3" variant="heading40">
      Emergency Calling
    </Heading>
    <Box height="min-content" display="inherit" columnGap="space30">
      <PopoverContainer baseId="popover-example">
        <PopoverBadgeButton variant="new">
          <NewIcon decorative/>
          Beta
        </PopoverBadgeButton>
        <Popover aria-label="Popover">

        This product is in beta, which means we're still working out all the kinks. Let us know if you spot any bugs.

        </Popover>
      </PopoverContainer>
    </Box>
  </Box>
  <Paragraph marginBottom="space0">
    Twilio’s Emergency Calling for SIP Trunking feature enables
    emergency call routing to Public Safety Answering Points (PSAPs) in
    the US, Canada, and the UK.
  </Paragraph>
</Card>

Highlight products

const SettingsAndProducts = () => {
  const [callRecording, setCallRecording] = React.useState("always");

  const handleOnChange = React.useCallback(
    (newValue) => {
      setCallRecording(newValue);
    },
    [setCallRecording]
  );
  return (
    <Box
      display="flex"
      flexDirection="row"
      alignItems="flex-start"
      columnGap="space40"
    >
      <RadioGroup
        name="call-recording"
        value={callRecording}
        legend="Would you like to enable call recording?"
        helpText="Applies to all incoming and outbound calls."
        onChange={handleOnChange}
      >
        <Radio id="always" value="always">
          Always
        </Radio>
        <Radio id="never" value="never">
          Never
        </Radio>
      </RadioGroup>

      <Box display="flex" columnGap="space20">
        <Badge variant="decorative20" as="span">
          <ProductElasticSIPTrunkingIcon decorative size="sizeIcon10" />
          SIP Trunking
        </Badge>
        <Badge variant="decorative30" as="span">
          <ProductVoiceIcon decorative size="sizeIcon10" />
          Voice
        </Badge>
      </Box>
    </Box>
  );
};

render(
  SettingsAndProducts
)

Show an invitation count

const HorizontalTabsExample = () => {
  const selectedId = useUID();
  return (
    <Tabs selectedId={selectedId} baseId="horizontal-tabs-example">
      <TabList aria-label="Horizontal product tabs">
        <Tab id={selectedId}>Owl Inc.</Tab>
        <Tab>Out of Organization</Tab>
        <Tab>
          <Stack orientation="horizontal" spacing="space20">
            Invitations
            <Badge as="span" variant="neutral_counter">50</Badge>
          </Stack>
        </Tab>
      </TabList>
    </Tabs>
  );
};


render(
  <HorizontalTabsExample />
)

Do and don't

Beta

Do

Use Badge to highlight an attribute of an object for quick identification.

Beta

Don't

Don’t use Display Pill or Form Pill to highlight an attribute of an object for quick identification.

New Component

Do

Use 1-3 words and sentence case for Badge text.

This is some very long text inside a Badge that creates a very large Badge.

Don't

Don't use lengthy copy inside a Badge.

Inline Badge

Do

Set the Badge children to be inline.

This
is
not ideal

Don't

Don't use multiline Badge text.

Token expiring

Token Missing

Do

Use semantic variants, such as Error, Warning, and Success, in semantic ways.

Inbound

Outbound

Don't

Don’t use semantic variants for non-semantic use cases. Instead, use the Decorative variants.

Warning

Do

Match the icon to the Badge variant (when not using Decorative Badges).

Warning

Don't

Don’t use the wrong icon in the wrong Badge variant.

Success

Do

When using Icons in Badge, place the Icon before the label.

Success

Don't

When using Icons in Badge, don’t place the icon after the label.

Token missing

Do

Ensure badge text communicates the problem.

Token

Don't

Don’t rely just on color to communicate meaning.

Usage Guide

API

Installation

yarn add @twilio-paste/badge - or - yarn add @twilio-paste/core

Usage

import { Badge } from "@twilio-paste/core/badge";

const BadgeExample = () => (
  <Badge as="span" variant="neutral">
    Default Badge
  </Badge>
);

Props

Badge

Prop	Type	Description	Default
children	`NonNullable<React.ReactNode>`		`null`
variant	`BadgeVariants`	`neutral`, `success`, `warning`, `error`, `new`, `subaccount`, `decorative10`, `decorative20`, `decorative30`, `decorative40`, `neutral_counter`, `error_counter`	`null`
size	`BadgeSizes`	`default`, `small`	`default`
as	`BadgeBaseElements`	The HTML tag to use as base - `span`, `button`, `a`	`null`
href?	`string`	A URL to route to. Must use `as="a"` for this prop to work.	`undefined`
onClick?	`MouseEventHandler<HTMLButtonElement>`	React event handler. Must use `as="button"` for this prop to work.	`undefined`
element?	`string`	Overrides the default element name to apply unique styles with the Customization Provider	'BADGE'