Status Indicator

Status Indicators help the user quickly identify the status of a task, action, or page element.

GitHubStorybook
yarn add @workday/canvas-kit-preview-react
Sources
GitHubStorybook
Install
yarn add @workday/canvas-kit-preview-react

Status Indicator (Main) vs. Status Indicator (Preview)

We recommend you use the Status Indicator in the Preview package (@workday/canvas-kit-preview-react) documented here on this page. The Status Indicator in the Main package (@workday/canvas-kit-react) will eventually be replaced with the Status Indicator in the Preview package.

Status Indicator (Main) Documentation

Anatomy

Image of a Card with annotation markers.

  1. Text: Bold, single-line, title-case text is used to recognize a status quickly.
  2. Background: Color is used to help users quickly recognize the meaning of a status across applications. Each background has two emphasis variations to support both high and low emphasis contrast (see Variations below).
  3. System Icon: Optional visual to further emphasize and support status.

Usage Guidance

  • A Status Indicator is a way of making an element on the page stand out to inform the user that there is something special about it that warrants the user’s attention.
  • Status Indicators are non-interactive visual cues that highlight a change in the system or task. They are read-only, passive elements that should not take the place of an action or button.
  • Although Status Indicators are commonly used to signal validation feedback or notifications, they can also be used on their own, such as within a Table.
  • Status Indicators have a max-width of 200px so that users can easily scan and recognize status quickly. Status text should be short, direct, and preferable a single word.
  • Status Indicator text should not wrap.
  • In cases where truncation is necessary, an Overflow Tooltip can be used to reveal the full-text. In general, try to avoid relying on overflow solutions like tooltips - instead, keep text concise to avoid truncation from happening in the first place.
  • Combine background color variation with logical status text.
  • When competing with other visual labelling elements, status indicators can be distracting. Use them in moderation, and consider how many (if any) indicators should be used in your design.

When To Use

  • To attract user attention to a particular piece of content or UI element whose status has changed or may change in the future.
  • Use low-emphasis indicators in instances where they may dominate the screen, such as in a table when they appear alongside many other Indicators.
  • Use high-emphasis Status Indicators sparingly. Reserve these to pair with headers or page section titles.
  • Reserve transparent Status Indicators to communicate status on top of imagery and video.

When To Use Something Else

  • If one or two words is not enough to convey the status, consider using body text or a header with detail text to communicate the status.
  • If a status is less important to the user or task, consider using body text or a header to communicate the status.
  • Status Indicators are not interactive components. If a status needs to be interactive, consider using a Hyperlink or Tertiary Button.

Variations

Status Indicators have a background color to help users recognize the meaning of a status across applications. Each indicator background type has two variations, one to support both high and low emphasis indicators. Keep in mind that Status Indicators can increase the amount of visual noise or add unwanted emphasis when used repetitively. Take this into consideration when selecting your background variation.

The examples below outline the suggested purpose of each indicator color and variation.

Examples

Basic Example

StatusIndicator includes a container StatusIndicator component and the following subcomponents which can be composed in a variety of ways: StatusIndicator.Label and StatusIndicator.Icon.

A basic StatusIndicator with a StatusIndicator.Label will render text with a gray background and low emphasis.

Unpublished

Emphasis

Set the emphasis prop of StatusIndicator to adjust the contrast between the text and background color. Emphasis is typically used to convey more visual urgency.

emphasis accepts high or low.

High Emphasis
Low Emphasis

Icon

Use StatusIndicator.Icon to add an icon to the StatusIndicator as a visual decorator. The position of the icon may be adjusted depending on where you place it in the markup.

Unpublished
published

Overflow

We strongly discourage using text in a StatusIndicator which will cause it to exceed its maximum width of 200px. In situations where this cannot be avoided and text must be overflowed, we suggest wrapping StatusIndicator in an OverflowTooltip and applying tabIndex={0} to it so the overflowed text is accessible via keyboard and mouse. You may also override the default maxWidth of StatusIndicator via style props.

Your workbook is currently in process of saving

Variants

Set the variant prop of StatusIndicator to adjust its background color. variant accepts the following values:

  • gray
  • orange
  • blue
  • green
  • red
  • transparent

The background color dictated by the variant will be dark or light based on the emphasis.

Lorem ipsum dolor
Lorem ipsum dolor
Lorem ipsum dolor
Lorem ipsum dolor
Lorem ipsum dolor
Lorem ipsum dolor
Lorem ipsum dolor
Lorem ipsum dolor
Lorem ipsum dolor
Lorem ipsum dolor
Lorem ipsum dolor
Lorem ipsum dolor

Component API

StatusIndicator

Usage

StatusIndicator is a container component which renders an HStack under the hood to apply spacing evenly between its children. It has a default maximum width of 200px.

<StatusIndicator emphasis="low" variant="blue">
{/* Child components */}
</StatusIndicator>

Props

Undocumented props are spread to the underlying HStack.

NameTypeDefaultDescription
children*ReactNodeChildren of the `StatusIndicator`. Can contain a `StatusIndicator.Label` and optionally a `StatusIndicator.Icon`.
flexDirection"row" | "row-reverse" | undefined"row"sets the direction for the stack
emphasisStatusIndicatorEmphasis | undefined'low'Defines the emphasis of the `StatusIndicator`. `high` emphasis will create more contrast between the background and text colors. `low` emphasis will create less contrast between the background and text colors.
variantStatusIndicatorVariant | undefined'gray'Defines the color of the `StatusIndicator`.
refReact.Ref<any>Optional ref. If the component represents an element, this ref will be a reference to the real DOM element of the component. If `as` is set to an element, it will be that element. If `as` is a component, the reference will be to that component (or element if the component uses `React.forwardRef`).
model{ state: { emphasis: StatusIndicatorEmphasis; variant: StatusIndicatorVariant; }; events: {}; } | undefinedOptional model to pass to the component. This will override the default model created for the component. This can be useful if you want to access to the state and events of the model, or if you have nested components of the same type and you need to override the model provided by React Context.
elemPropsHook(<TProps>(model: { state: { emphasis: StatusIndicatorEmphasis; variant: StatusIndicatorVariant; }; events: {}; }, elemProps: TProps) => any) | undefinedOptional hook that receives the model and all props to be applied to the element. If you use this, it is your responsibility to return props, merging as appropriate. For example, returning an empty object will disable all elemProps hooks associated with this component. This allows finer control over a component without creating a new one.
as"symbol" | "object" | "small" | "a" | "abbr" | "address" | "area" | "article" | "aside" | "audio" | "b" | "base" | "bdi" | "bdo" | "big" | "blockquote" | "body" | "br" | "button" | ... 156 more ... | React.ComponentType<any>Optional override of the default element used by the component. Any valid tag or Component. If you provided a Component, this component should forward the ref using `React.forwardRef` and spread extra props to a root element.

StatusIndicator.Label

Usage

StatusIndicator.Label renders Text under the hood. It will apply an ellipsis if its contents exceed the component's maximum width.

<StatusIndicator.Label>{/*The text to be rendered*/}</StatusIndicator.Label>

Props

Undocumented props are spread to the underlying Text.

NameTypeDefaultDescription
typeLevel"body.small" | "body.large" | "body.medium" | "title.small" | "title.large" | "title.medium" | "heading.small" | "heading.large" | "heading.medium" | "subtext.small" | "subtext.large" | "subtext.medium" | undefinedType token as string with level and size separated by dot. These values map to our [Canvas type levels](https://canvas.workday.com/tokens/type#type-styles). @example ```tsx <Text typeLevel="body.small">Small body text</Text> ```
variantkeyof CanvasTypeVariants | undefinedType variant token names: `error`, `hint` or `inverse`. @example ```tsx <Text variant="error" typeLevel="subtext.large">Error text</Text> ```
refReact.Ref<any>Optional ref. If the component represents an element, this ref will be a reference to the real DOM element of the component. If `as` is set to an element, it will be that element. If `as` is a component, the reference will be to that component (or element if the component uses `React.forwardRef`).
as"symbol" | "object" | "small" | "a" | "abbr" | "address" | "area" | "article" | "aside" | "audio" | "b" | "base" | "bdi" | "bdo" | "big" | "blockquote" | "body" | "br" | "button" | ... 156 more ... | React.ComponentType<any>Optional override of the default element used by the component. Any valid tag or Component. If you provided a Component, this component should forward the ref using `React.forwardRef` and spread extra props to a root element.

StatusIndicator.Icon

Usage

StatusIndicator.Icon renders SystemIcon under the hood. It's used as a decorative element to visually support the StatusIndicator.Label text.

<StatusIndicator.Icon icon={uploadCloudIcon} />

Props

Undocumented props are spread to the underlying SystemIcon.

NameTypeDefaultDescription
icon*CanvasSystemIconThe icon to display from `@workday/canvas-system-icons-web`.
sizestring | number | undefinedThe size of the SystemIcon in `px`.
classNamestring | undefined
accentstring | undefinedThe accent color of the SystemIcon. This overrides `color`.
accentHoverstring | undefinedThe accent color of the SystemIcon on hover. This overrides `colorHover`.
backgroundstring | undefinedtransparentThe background color of the SystemIcon.
backgroundHoverstring | undefinedtransparentThe background color of the SystemIcon on hover.
colorstring | undefinediconColors.standardThe color of the SystemIcon. This defines `accent` and `fill`. `color` may be overriden by `accent` and `fill`.
colorHoverstring | undefinediconColors.hoverThe hover color of the SystemIcon. This defines `accentHover` and `fillHover`. `colorHover` may be overriden by `accentHover` and `fillHover`.
fillstring | undefinedThe fill color of the SystemIcon. This overrides `color`.
fillHoverstring | undefinedThe fill color of the SystemIcon on hover. This overrides `colorHover`.
shouldMirrorboolean | undefinedfalseIf set to `true`, transform the SVG's x-axis to mirror the graphic
stylesCSSObject | undefined
refReact.Ref<any>Optional ref. If the component represents an element, this ref will be a reference to the real DOM element of the component. If `as` is set to an element, it will be that element. If `as` is a component, the reference will be to that component (or element if the component uses `React.forwardRef`).
model{ state: { emphasis: StatusIndicatorEmphasis; variant: StatusIndicatorVariant; }; events: {}; } | undefinedOptional model to pass to the component. This will override the default model created for the component. This can be useful if you want to access to the state and events of the model, or if you have nested components of the same type and you need to override the model provided by React Context.
elemPropsHook(<TProps>(model: { state: { emphasis: StatusIndicatorEmphasis; variant: StatusIndicatorVariant; }; events: {}; }, elemProps: TProps) => any) | undefinedOptional hook that receives the model and all props to be applied to the element. If you use this, it is your responsibility to return props, merging as appropriate. For example, returning an empty object will disable all elemProps hooks associated with this component. This allows finer control over a component without creating a new one.
as"symbol" | "object" | "small" | "a" | "abbr" | "address" | "area" | "article" | "aside" | "audio" | "b" | "base" | "bdi" | "bdo" | "big" | "blockquote" | "body" | "br" | "button" | ... 156 more ... | React.ComponentType<any>Optional override of the default element used by the component. Any valid tag or Component. If you provided a Component, this component should forward the ref using `React.forwardRef` and spread extra props to a root element.

Accessibility Guidelines

  • The status text and background color must meet the minimum contrast requirement.
  • Consistently pair color schemes with text in Status Indicators to help ensure accessibility and the accuracy of information to assistive technology.
  • If an icon is used alongside the status text, consider if adjacent text accurately describes the status. For example, icons that imply an action, like ‘+’ or ‘X’ may require an accessible name for screen reader users, such as ‘add’ or ‘close’. If the icon is redundant to the adjacent text, the icon may be considered decorative and an accessible name isn’t necessary.
  • In rare cases that you require more than the maximum 200px, the status text can be truncated and supported by an Overflow Tooltip to reveal the full text. Be aware that the tooltip must be accessible to users who do not use a mouse or trackpad to hover the text. Consider using a tabIndex to insert the status into focus order, but be advised that this is not a best practice and may confuse some users.

Content Guidelines

  • Keep status text short, direct, and preferably a single word. Keep in mind that Status Indicator containers have a maximum width of 200px before text truncation begins.
  • Avoid creating status labels that require more characters than the max-width allows for.
  • Status Indicator text should never wrap.
  • Use status labels that are relatable or familiar to your user and the task at hand.
  • When writing content for Status Indicators, refer to our Content Style Guide.

Can't Find What You Need?

Check out our FAQ section which may help you find the information you're looking for.

FAQ Section