Skip to contentSkip to navigationSkip to topbar
Figma
Star

Status

The status pattern informs the user of the dynamic state or condition of an object.

Product
Console
Flex
SendGrid
Segment

Component preview theme
<Box display="flex">
<ProcessSuccessIcon
color="colorTextIconSuccess"
decorative={false}
title="success" />
<Text marginLeft="space20">Success</Text>
</Box>

Ingredients

Ingredients page anchor

Icon

// import all components for Status patterns

import {​ Text } from "@twilio-paste/core/text";
import { Box } from "@twilio-paste/core/box";
import { ProcessDisabledIcon } from "@twilio-paste/icons/esm/ProcessDisabledIcon";
import { ProcessDraftIcon } from "@twilio-paste/icons/esm/ProcessDraftIcon";
import { ProcessErrorIcon } from "@twilio-paste/icons/esm/ProcessErrorIcon";
import { ProcessInProgressIcon } from "@twilio-paste/icons/esm/ProcessInProgressIcon";
import { ProcessNeutralIcon } from "@twilio-paste/icons/esm/ProcessNeutralIcon";
import { ProcessSuccessIcon } from "@twilio-paste/icons/esm/ProcessSuccessIcon";
import { ProcessWarningIcon } from "@twilio-paste/icons/esm/ProcessWarningIcon";

General usage

General usage page anchor

A Status is used to communicate the dynamic state of an object to a user. Use them to help the user identify something that requires their attention and often, their action. When a status is used to indicate to the user that they need to take action, be sure to provide clear controls to take that action (e.g. a “Try again” button).

Statuses are:

  • Always related to an object. For example, a SIM can have a status, but a step in a wizard flow cannot.
  • Not used for static attributes. For example, “SMS-capable” is not a status on a phone number.
  • Different from notification and feedback messaging, which is in direct response to a user action.
  • Different from alert messaging, which is from the system.
  • Used to draw a user’s attention to important information. Use plain text statuses when the status is not critical information for a user to know.

Non-text status indicators (such as icons or status dots) should be paired with text whenever possible and should always be given a title to give context and meaning to the icon or shape. Check out the icon usage guidelines for more detailed accessibility information.

Process statuses indicate an object’s progress through a certain set of stages. There are generally 3 or more stages in a given process, which may be considered “good”, “bad”, or “neutral”. Process statuses are composed of a status Icon and Text.

Process icons should be paired with text whenever possible. When using process icons, try to limit the number of icons used to 3 or 4 of the most important statuses. For statuses that are not as critical to a user’s workflow, consider plain text statuses.

Component preview theme
<Box display="flex" columnGap="space80" rowGap="space60" flexWrap="wrap">
<Box display="flex">
<ProcessErrorIcon
color="colorTextIconError"
decorative={false}
title="error" />
<Text marginLeft="space20">Error</Text>
</Box>
<Box display="flex">
<ProcessWarningIcon
color="colorTextIconWarning"
decorative={false}
title="warning" />
<Text marginLeft="space20">Warning</Text>
</Box>
<Box display="flex">
<ProcessSuccessIcon
color="colorTextIconSuccess"
decorative={false}
title="success" />
<Text marginLeft="space20">Success</Text>
</Box>
<Box display="flex">
<ProcessNeutralIcon
color="colorTextIconNeutral"
decorative={false}
title="neutral" />
<Text marginLeft="space20">Neutral</Text>
</Box>
<Box display="flex">
<ProcessInProgressIcon
color="colorTextIconNeutral"
decorative={false}
title="In-progress" />
<Text marginLeft="space20">In-progress</Text>
</Box>
<Box display="flex">
<ProcessDisabledIcon
color="colorTextIcon"
decorative={false}
title="disabled" />
<Text marginLeft="space20">Disabled</Text>
</Box>
<Box display="flex">
<ProcessDraftIcon
color="colorTextIcon"
decorative={false}
title="draft" />
<Text marginLeft="space20">Draft</Text>
</Box>
</Box>

Icon and token pairings

Icon and token pairings page anchor
IconIcon nameTokenUsage
ErrorProcessErrorIcon$color-text-icon-errorIndicates an error or that something went wrong.
WarningProcessWarningIcon$color-text-icon-warningIndicates a condition requiring corrective action.
SuccessProcessSuccessIcon$color-text-icon-successIndicates that something is stable, active, or successfully completed.
NeutralProcessNeutralIcon$color-text-icon-neutralIndicates a neutral / informative state. Can be used to fill any gaps that the more specific statuses don’t cover.
In-progressProcessInProgressIcon$color-text-icon-neutralIndicates that something is in progress, in review, or scheduled.
DisabledProcessDisabledIcon$color-text-iconIndicates that something is inactive, disabled, or paused.
DraftProcessDraftIcon$color-text-iconIndicates that something is a draft, unused, or not started.

Connectivity statuses are used to show if a user, object, or system is online or offline. Connectivity statuses are composed using a connectivity Icon and Text.

Connectivity statuses should almost always be paired with accompanying text, though Available and Offline can be used without text in cases where space is constrained, since there is a shape difference.

Component preview theme
<Box display="flex" columnGap="space90" flexWrap="wrap">
<Box display="inherit">
<ConnectivityAvailableIcon
color="colorTextIconAvailable"
decorative={false}
title="available"
/>
Available
</Box>
<Box display="inherit">
<ConnectivityBusyIcon
color="colorTextIconBusy"
decorative={false}
title="busy"
/>
Busy
</Box>
<Box display="inherit">
<ConnectivityUnavailableIcon
color="colorTextIconUnavailable"
decorative={false}
title="unavailable"
/>
Unavailable
</Box>
<Box display="inherit">
<ConnectivityNeutralIcon
color="colorTextIconNeutral"
decorative={false}
title="neutral"
/>
Neutral
</Box>
<Box display="inherit">
<ConnectivityOfflineIcon
color="colorTextIconOffline"
decorative={false}
title="offline"
/>
Offline
</Box>
</Box>

Connectivity icon and token pairings

Connectivity icon and token pairings page anchor
IconIcon nameTokenUsage
availableConnectivityAvailableIcon$color-text-icon-availableIndicates that a person or entity is available or online.
busyConnectivityBusyIcon$color-text-icon-busyIndicates that a person or entity is busy or away.
unavailableConnectivityUnavailableIcon$color-text-icon-unavailableIndicates that a person or entity is unavailable or at capacity.
neutralConnectivityNeutralIcon$color-text-icon-neutralIndicates that a person or entity is neutral.
offlineConnectivityOfflineIcon$color-text-icon-offlineIndicates that a person or entity is offline.
(information)

Connectivity statuses in Flex

Connectivity statuses are used heavily throughout Flex, where the circle indicators should retain the same color across the product on any background color (including the dark topmast).

Since icons must have high enough contrast with their background, Flex uses Box with a background color here instead of using an icon. This gives more flexibility to the number of backgrounds a connectivity status can be placed on.

In general, Connectivity statuses should use the icons and tokens documented in this pattern, but if you have a use case similar to Flex, you can follow their approach.

Not all statuses need icons or shapes. In fact, giving every status an icon or a shape can make it difficult for a user to find and focus on the most critical information. If some statuses—such as successes or failures—are highly critical, consider using plain text for the other statuses that a user may not need to identify as quickly.

The status icon or dot should most often be placed as a prefix, before the status text, though some page layouts may benefit from placing the icon as a suffix. A suffix icon is often beneficial when a status is right-aligned within a Card or List.

For process statuses, the icon should generally be the same size as the line-height of the status text (e.g. use $size-icon-20 for a status icon paired with text at $line-height-20) to ensure that the icon and the text are vertically aligned.

Component preview theme
<Stack orientation="vertical" spacing="space60">
<Box display="flex">
<ProcessErrorIcon
color="colorTextIconError"
decorative={false}
title="failed to process"
size="sizeIcon40"
/>
<Text
lineHeight="lineHeight40"
fontSize="fontSize40"
marginLeft="space30"
>
Failed to process
</Text>
</Box>
<Box display="flex">
<Text marginRight="space20">Failed to process</Text>
<ProcessErrorIcon
color="colorTextIconError"
decorative={false}
title="failed to process"
/>
</Box>
</Stack>

It is strongly recommended that status icons be paired with text, especially for statuses that are important for a user to understand.

Use the StatusBadge component to compose a status icon with a text label, usually when a status is shown outside of a Table. Common placements are near avatars (particularly for connectivity statuses), in cards, and in lists.

Component preview theme
<Box display="flex" flexDirection="column" rowGap="space40">
<Box display="flex" columnGap="space40" rowGap="space40" flexWrap="wrap">
<StatusBadge as="span" variant="ProcessSuccess">
Success
</StatusBadge>
<StatusBadge as="span" variant="ProcessError">
Error
</StatusBadge>
<StatusBadge as="span" variant="ProcessWarning">
Warning
</StatusBadge>
<StatusBadge as="span" variant="ProcessNeutral">
Neutral
</StatusBadge>
<StatusBadge as="span" variant="ProcessInProgress">
In-progress
</StatusBadge>
<StatusBadge as="span" variant="ProcessDisabled">
Disabled
</StatusBadge>
<StatusBadge as="span" variant="ProcessDraft">
Draft
</StatusBadge>
</Box>
<Box display="flex" columnGap="space40">
<StatusBadge as="span" variant="ConnectivityAvailable">
Available
</StatusBadge>
<StatusBadge as="span" variant="ConnectivityUnavailable">
Unavailable
</StatusBadge>
<StatusBadge as="span" variant="ConnectivityBusy">
Busy
</StatusBadge>
<StatusBadge as="span" variant="ConnectivityNeutral">
Neutral
</StatusBadge>
<StatusBadge as="span" variant="ConnectivityOffline">
Offline
</StatusBadge>
</Box>
</Box>

Statuses are most often used in tables across our products. Placement of the status in the table should depend on the importance of the status to the given user flow and should be tested with users.

Component preview theme
<>
<Heading as="h2" variant="heading20">
Exports
</Heading>
<Table>
<THead>
<Tr>
<Th>Status</Th>
<Th>Export name</Th>
</Tr>
</THead>
<TBody>
<Tr>
<Td>
<Box display="inline-flex" columnGap="space20">
<ProcessSuccessIcon
color="colorTextIconSuccess"
decorative={false}
title="success"
/>
<Box>
<Text as="div">Successfully exported</Text>
<Text as="div" color="colorTextWeak">Tuesday, January 2, 2021</Text>
</Box>
</Box>
</Td>
<Td>
<strong>Contacts who did not click</strong>
</Td>
</Tr>
<Tr>
<Td>
<Box display="inline-flex" columnGap="space20">
<ProcessSuccessIcon
color="colorTextIconSuccess"
decorative={false}
title="success"
/>
<Box>
<Text as="div">Successfully exported</Text>
<Text as="div" color="colorTextWeak">Tuesday, February 2, 2021</Text>
</Box>
</Box>
</Td>
<Td>
<strong>All contacts</strong>
</Td>
</Tr>
</TBody>
</Table>
<Box marginTop="space110">
<Heading as="h2" variant="heading20">
IDs
</Heading>
</Box>
<Table>
<THead>
<Tr>
<Th>ID</Th>
<Th>Unique name</Th>
<Th>Region</Th>
<Th>Status</Th>
<Th>Order Date</Th>
</Tr>
</THead>
<TBody>
<Tr>
<Td>90294808908109537</Td>
<Td>WE902990c21gjioGasd</Td>
<Td>North America</Td>
<Td>
<StatusBadge variant="ProcessSuccess">Active</StatusBadge>
</Td>
<Td>2020-10-15</Td>
</Tr>
<Tr>
<Td>90294808908872345</Td>
<Td>WE928471c21gjioGasd</Td>
<Td>North America</Td>
<Td>
<StatusBadge variant="ProcessNeutral">Ready</StatusBadge>
</Td>
<Td>2020-10-15</Td>
</Tr>
</TBody>
</Table>
</>

Pairing process statuses with plain text statuses

Pairing process statuses with plain text statuses page anchor

Using plain text statuses for non-critical information and process statuses for critical information is a great way to highlight information that is most important for a user to know.

Component preview theme
<>
<Heading as="h2" variant="heading20">
Reboots
</Heading>
<Table>
<THead>
<Tr>
<Th>Title</Th>
<Th>Media</Th>
<Th>Status</Th>
</Tr>
</THead>
<TBody>
<Tr>
<Td>Bewitched</Td>
<Td>Series</Td>
<Td>
<StatusBadge variant="ProcessWarning">Progress halted</StatusBadge>
</Td>
</Tr>
<Tr>
<Td>Mulan</Td>
<Td>Feature</Td>
<Td>Released</Td>
</Tr>
<Tr>
<Td>Little Women</Td>
<Td>Feature</Td>
<Td>Released</Td>
</Tr>
</TBody>
</Table>
</>

Providing additional information on a status

Providing additional information on a status page anchor

It can often be beneficial to provide additional information on a status. The best way to do this is to provide description text directly below the status. This makes the information easily discoverable and is the simplest way for screen reader users to access it.

Adding a link to a status page anchor

Linking out to additional information is a great way to add more context to a status and guide the user towards their next steps.

Anchors can be placed directly on status text or within help text below the status. Link-style buttons can be used when clicking the text performs an in-page action, such as opening a modal.

Component preview theme
<Box display="flex" columnGap="space80" rowGap="space60" flexWrap="wrap">
<Box display="flex">
<ProcessErrorIcon
color="colorTextIconError"
decorative={false}
title="error"
/>
<Anchor
marginLeft="space20"
href="#"
showExternal
>
Pre-registration needed
</Anchor>
</Box>
<Box display="inline-flex" columnGap="space20">
<ProcessErrorIcon
color="colorTextIconError"
decorative={false}
title="error"
/>
<Box>
<Text as="div">Pre-registration needed</Text>
<Box>
<Anchor
marginLeft="space20"
href="#"
showExternal
>
Fill out the registration form here
</Anchor>
</Box>
</Box>
</Box>
<Box display="inline-flex" columnGap="space20">
<ProcessErrorIcon
color="colorTextIconError"
decorative={false}
title="error"
/>
<Box>
<Text as="div">Pre-registration needed</Text>
<Box>
<Button
marginLeft="space20"
variant="link"
>
View details
</Button>
</Box>
</Box>
</Box>
</Box>


Statuses are not always placed in tables. Other common placements are near avatars (particularly for connectivity statuses), in cards, and in lists.

Component preview theme
<Stack orientation="vertical" spacing="space60">
<Box width="60%">
<Card>
<Box
as="span"
display="flex"
width="100%"
alignItems="center"
justifyContent="space-between"
marginBottom="space70"
>
<Heading as="h3" variant="heading40" marginBottom="space0">
Business Profile
</Heading>
<StatusBadge variant="ProcessSuccess">
Approved
</StatusBadge>
</Box>
<Paragraph marginBottom="space0">Information about your business</Paragraph>
</Card>
</Box>
<Box width="275px">
<Box
as="span"
display="flex"
width="100%"
alignItems="center"
justifyContent="space-between"
marginBottom="space30"
>
<Text fontWeight="fontWeightSemibold">Account Security</Text>
<StatusBadge variant="ProcessSuccess">
Connected
</StatusBadge>
</Box>
<Box
as="span"
display="flex"
width="100%"
alignItems="center"
justifyContent="space-between"
marginBottom="space30"
>
<Text fontWeight="fontWeightSemibold">Autopilot</Text>
<StatusBadge variant="ProcessSuccess">
Connected
</StatusBadge>
</Box>
<Box
as="span"
display="flex"
width="100%"
alignItems="center"
justifyContent="space-between"
>
<Text fontWeight="fontWeightSemibold">Carrier Network</Text>
<StatusBadge variant="ProcessWarning">
Intermittent
</StatusBadge>
</Box>
</Box>
</Stack>
Status
Not Started
Archived
error
Error
In-progress
In-progress
success
Success
Do

Use status icons to draw attention to the most important statuses. Try to limit a given set of statuses to 3–4 icons, and use plain text statuses for the rest. This helps users skim a dense set of data for the information that is most critical.

Status
not started
Not started
archived
Archived
error detected
Error detected
In-progress
In-progress
success
Success
Don't

Don't put a status icon or shape on every status if some statuses are more important than others. If all statuses are of equal importance, they can all have icons.