Skip to contentSkip to navigationSkip to topbar
Paste
Paste assistant Assistant
FigmaStar

Status

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

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

Usage

Usage page anchor

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.

Accessibility

Accessibility page anchor

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

Variations page anchor

Process status

Process status page anchor

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 status

Connectivity status page anchor

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.

Plain text status

Plain text status page anchor

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

Composition page anchor

Icon and text placement

Icon and text placement page anchor

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.

Status badges

Status badges page anchor

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>

Positioning in a table

Positioning in a table page anchor

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>


Other common placements

Other common placements page anchor

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>

Dos and Don'ts

Dos and Don'ts page anchor
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.

Starter kits

Starter kits page anchor
Related Discussions page anchor