Skip to contentSkip to navigationSkip to topbar
Figma
Star

Badge

Version 8.1.0GithubStorybook

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

Component preview theme
<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="neutral_counter">
1
</Badge>
<Badge as="span" variant="error_counter">
1
</Badge>
</Box>

Guidelines

Guidelines page anchor

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

Accessibility page anchor
  • 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.

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

Neutral page anchor

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

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

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.

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

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.

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

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.

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

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

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

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

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

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.

Component preview theme
<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>

Use the counter Badge should be used to visually highlight a count in a UI. For example, the number of pending invitations or the number of errors. Counter Badges are limited to Neutral and Error variants, and the error variant should always include an error icon.

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

Badge with anchor functionality

Badge with anchor functionality page anchor

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

Component preview theme
<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

Badge with button functionality page anchor

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.

Component preview theme
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 />
)

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.

Component preview theme
<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>

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.

Call attention to attributes of table items

Call attention to attributes of table items page anchor
Component preview theme
<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

Identify an item as as a beta release page anchor
Component preview theme
<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>
Component preview theme
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"
minWidth="size100"
>
<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" minWidth="size60" 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

Show an invitation count page anchor
Component preview theme
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 />
)

BetaBeta
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 Badge componentNew 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.

    warningWarning
    Do

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

    warningWarning
    Don't

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

    successSuccess
    Do

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

    Successsuccess
    Don't

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

    errorToken missing
    Do

    Ensure badge text communicates the problem.

    errorToken
    Don't

    Don’t rely just on color to communicate meaning.


    yarn add @twilio-paste/badge - or - yarn add @twilio-paste/core
    
    import {Badge} from '@twilio-paste/core/badge';
    
    const BadgeExample = () => (
      <Badge as="span" variant="neutral">
        Default Badge
      </Badge>
    );
    
    Badge
    Badge page anchor
    PropTypeDescriptionDefault
    childrenNonNullable<React.ReactNode>null
    variantBadgeVariantsneutral, success, warning, error, new, subaccount, decorative10, decorative20, decorative30, decorative40, neutral_counter, error_counternull
    sizeBadgeSizesdefault, smalldefault
    asBadgeBaseElementsThe HTML tag to use as base - span, button, anull
    href?stringA 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?stringOverrides the default element name to apply unique styles with the Customization Provider'BADGE'