Status

View source on GitHub
See recent changes on GitHub

Status is a graphic indicator of an element’s state.

also known as Status Indicator, Signal, System Feedback

Figma:
Ready
Responsive:
Ready
Adaptive:
N/A

Props

Component props
Name
Type
Default
type
Required
"unstarted"
| "queued"
| "inProgress"
| "halted"
| "locked"
| "ok"
| "problem"
| "canceled"
| "warning"
-

The type of status to display.

accessibilityLabel
string
-

If not using title, provide an accessibility label to give the user context about the icon. Be sure to localize the label.

subtext
string
-

Additional contextual information around the status. Only for use with title. See localization to learn more.

title
string | ReactElement
-

A label to reinforce the meaning of the status icon. See localization to learn more.

Usage guidelines

When to use
  • To describe the status of an individual element, such an an item in a list or a row in a table.
When not to use
  • To describe surface-level errors. Use BannerCallout instead.
  • To describe whether a numeric value is going up or down. Use Datapoint instead.

Best practices

Do

Use Status to communicate a step in a workflow or the state of an item.

Don't

Use SVGs or images that resemble the Status’ symbols to denote status.

Do

Place Status close to its subject to provide context and reference. It can be placed as an inline element or paired side by side as needed.

Don't

Place Status far away from its subject.

Do

Use title when the status it represents is unique, specific and critical for the user to know.

Don't

Use Status' subText to display extraneous messaging.

Accessibility

Icons are a great way to help users who have difficulties with reading, focus attention, and low vision impairments. For such use cases, Status can be used without accompanying title text.

ARIA attributes

If Status appears without title text, accessibilityLabel should be used to provide a text description for screen readers to announce and communicate the represented icon, as shown in the first example.

Avoid using the generic words like "image" or "icon"; instead, use verbs that describe the meaning of the icon, for example: "Upload in progress".

If using title to describe what the icon represents, accessibilityLabel does not need to be provided, as shown in the second example.

import { Box, Flex, Status, Text } from 'gestalt';

export default function Example() {
  return (
    <Box
      alignItems="center"
      display="flex"
      height="100%"
      justifyContent="center"
      padding={8}
    >
      <Flex gap={{ column: 0, row: 1 }}>
        <Status accessibilityLabel="This item has a problem" type="problem" />
        <Text size="300" weight="bold">
          Dynamic re-targeting
        </Text>
      </Flex>
    </Box>
  );
}


import { Box, Flex, Status, Text } from 'gestalt';

export default function Example() {
  return (
    <Box
      alignItems="center"
      display="flex"
      height="100%"
      justifyContent="center"
      padding={8}
    >
      <Flex alignItems="end" direction="column" gap={{ column: 1, row: 0 }}>
        <Status title="This item has a problem" type="problem" />
        <Text align="center" weight="bold">
          Dynamic re-targeting
        </Text>
      </Flex>
    </Box>
  );
}

Localization

Be sure to localize all text strings. Note that localization can lengthen text by 20 to 30 percent.

Variants

Title

The title prop accepts either a string or Text. Use a string for simple text without any visual style. Status will handle the message style and adherence to design guidelines. If a message with more complex style is required, such as inline links, use Text to wrap your message with any additional Text or Link components contained within.

Simple message string
import { Box, Flex, Status } from 'gestalt';

export default function Example() {
  return (
    <Box
      alignItems="center"
      display="flex"
      height="100%"
      justifyContent="center"
      padding={8}
    >
      <Flex direction="column" gap={{ column: 4, row: 0 }}>
        <Status title="Unstarted" type="unstarted" />
        <Status title="Queued" type="queued" />
        <Status title="In progress" type="inProgress" />
        <Status title="Halted" type="halted" />
        <Status title="Locked" type="locked" />
        <Status title="OK" type="ok" />
        <Status title="Canceled" type="canceled" />
        <Status title="Warning" type="warning" />
        <Status title="Problem" type="problem" />
      </Flex>
    </Box>
  );
}
Rich message with Text or Link component
function _optionalChain(ops) {
  let lastAccessLHS = undefined;
  let value = ops[0];
  let i = 1;
  while (i < ops.length) {
    const op = ops[i];
    const fn = ops[i + 1];
    i += 2;
    if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) {
      return undefined;
    }
    if (op === 'access' || op === 'optionalAccess') {
      lastAccessLHS = value;
      value = fn(value);
    } else if (op === 'call' || op === 'optionalCall') {
      value = fn((...args) => value.call(lastAccessLHS, ...args));
      lastAccessLHS = undefined;
    }
  }
  return value;
}
import { Box, Flex, Heading, Link, Status, Text } from 'gestalt';

export default function Example() {
  return (
    <Box
      alignItems="center"
      display="flex"
      height="100%"
      justifyContent="center"
      padding={8}
    >
      <Flex direction="column" gap={4}>
        <Heading accessibilityLevel="none" size="400">
          Health dashboard
        </Heading>
        <Flex direction="column" gap={2}>
          <Text weight="bold">Merchant status</Text>
          <Status
            title={
              <Text>
                <Link
                  accessibilityLabel="Your merchant account needs attention"
                  display="inline"
                  href=""
                  onClick={({ event, dangerouslyDisableOnNavigation }) => {
                    _optionalChain([
                      dangerouslyDisableOnNavigation,
                      'optionalCall',
                      (_) => _(),
                    ]);
                    event.preventDefault();
                  }}
                >
                  Needs attention
                </Link>
              </Text>
            }
            type="unstarted"
          />
        </Flex>
        <Flex direction="column" gap={2}>
          <Text weight="bold">Shopify</Text>
          <Status
            title={
              <Text>
                <Link
                  accessibilityLabel="Your Shoppify account is connected"
                  display="inline"
                  href=""
                  onClick={({ event, dangerouslyDisableOnNavigation }) => {
                    _optionalChain([
                      dangerouslyDisableOnNavigation,
                      'optionalCall',
                      (_2) => _2(),
                    ]);
                    event.preventDefault();
                  }}
                >
                  Connected
                </Link>
              </Text>
            }
            type="queued"
          />
        </Flex>
        <Flex direction="column" gap={2}>
          <Text weight="bold">Conversions API</Text>
          <Status
            title={
              <Text>
                <Link
                  accessibilityLabel="Your API is correctly set up"
                  display="inline"
                  href=""
                  onClick={({ event, dangerouslyDisableOnNavigation }) => {
                    _optionalChain([
                      dangerouslyDisableOnNavigation,
                      'optionalCall',
                      (_3) => _3(),
                    ]);
                    event.preventDefault();
                  }}
                >
                  Good setup
                </Link>
              </Text>
            }
            type="inProgress"
          />
        </Flex>
      </Flex>
    </Box>
  );
}

Subtext

Subtext
import { Box, Status } from 'gestalt';

export default function Example() {
  return (
    <Box
      alignItems="center"
      display="flex"
      height="100%"
      justifyContent="center"
      padding={8}
    >
      <Status subtext="Updated 2 days ago" title="Warning" type="warning" />
    </Box>
  );
}

Component quality checklist

Component quality checklist
Quality item
Status
Status description
Figma Library
Ready
Component is available in Figma for web and mobile web.
Responsive Web
Ready
Component responds to changing viewport sizes in web and mobile web.

Icon
Icon should be used to display a symbol that does not represent the state or status of an item.

Badge
Use Badge to label or mark an item with a designation or category.

BannerCallout
Use BannerCallout to communicate page-level status, such as an error, and to provide actionable next steps.

Edit page on GitHub