Status

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

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

Ingredients

Box

// 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";

Usage

General usage

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.

Accessibility

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.

Variations

Process status

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.

<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 name	Token	Usage
ProcessErrorIcon	$color-text-icon-error	Indicates an error or that something went wrong.
ProcessWarningIcon	$color-text-icon-warning	Indicates a condition requiring corrective action.
ProcessSuccessIcon	$color-text-icon-success	Indicates that something is stable, active, or successfully completed.
ProcessNeutralIcon	$color-text-icon-neutral	Indicates a neutral / informative state. Can be used to fill any gaps that the more specific statuses don’t cover.
ProcessInProgressIcon	$color-text-icon-neutral	Indicates that something is in progress, in review, or scheduled.
ProcessDisabledIcon	$color-text-icon	Indicates that something is inactive, disabled, or paused.
ProcessDraftIcon	$color-text-icon	Indicates that something is a draft, unused, or not started.

Connectivity status

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.

<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

Icon name	Token	Usage
ConnectivityAvailableIcon	$color-text-icon-available	Indicates that a person or entity is available or online.
ConnectivityBusyIcon	$color-text-icon-busy	Indicates that a person or entity is busy or away.
ConnectivityUnavailableIcon	$color-text-icon-unavailable	Indicates that a person or entity is unavailable or at capacity.
ConnectivityNeutralIcon	$color-text-icon-neutral	Indicates that a person or entity is neutral.
ConnectivityOfflineIcon	$color-text-icon-offline	Indicates 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.

Plain text status

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.

Composition

Icon and text placement

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.

<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.

Status badges

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.

<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>

Positioning in a table

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.

<>
  <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

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.

<>
  <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

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

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.

<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>

Other common placements

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

<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>

Dos and Don'ts

Status
Not Started
Archived
Error
In-progress
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
Archived
Error detected
In-progress
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.

Starter kits

Figma