Status Indicator

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

yarn add @workday/canvas-kit-preview-react
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

StatusIndicator is a container component which renders an 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>

Layout Component

StatusIndicator supports all props from thelayout component.

Props

Props extend from div. Changing the as prop will change the element interface.

Props extend from . If a model is passed, props from StatusIndicatorModelConfig are ignored.

NameTypeDescriptionDefault
childrenReactNode

Children of the StatusIndicator. Can contain a StatusIndicator.Label and optionally a StatusIndicator.Icon.

cs

The cs prop takes in a single value or an array of values. You can pass the CSS class name returned by , or the result of and . If you're extending a component already using cs, you can merge that prop in as well. Any style that is passed to the cs prop will override style props. If you wish to have styles that are overridden by the css prop, or styles added via the styled API, use wherever elemProps is used. If your component needs to also handle style props, use instead.

import {handleCsProp} from '@workday/canvas-kit-styling';
import {mergeStyles} from '@workday/canvas-kit-react/layout';
// ...
// `handleCsProp` handles compat mode with Emotion's runtime APIs. `mergeStyles` has the same
// function signature, but adds support for style props.
return (
<Element
{...handleCsProp(elemProps, [
myStyles,
myModifiers({ size: 'medium' }),
myVars({ backgroundColor: 'red' })
])}
>
{children}
</Element>
)
asReact.ElementType

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.forwardRefand spread extra props to a root element.

Note: Not all elements make sense and some elements may cause accessibility issues. Change this value with care.

div
refReact.Ref<R = div>

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

Optional 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(
  model: ,
  elemProps: TProps
) => HTML Attributes

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

useStatusIndicator

(
  model: ,
  elemProps: {},
  ref: React.Ref
) => {
  opacity:  string undefined;
  color: string;
  background: string;
}

StatusIndicator.Label

StatusIndicator.Label renders 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>

Layout Component

StatusIndicator.Label supports all props from thelayout component.

Props

Props extend from span. Changing the as prop will change the element interface.

NameTypeDescriptionDefault
typeLevel
  'body.medium'
  'body.large'
  'body.small'
  'title.medium'
  'title.large'
  'title.small'
  'heading.medium'
  'heading.large'
  'heading.small'
  'subtext.medium'
  'subtext.large'
  'subtext.small'

Type token as string with level and size separated by dot. These values map to our Canvas type levels.

<Text typeLevel="body.small">Small body text</Text>
'subtext.large'
variantkeyof

Type variant token names: error, hint or inverse.

<Text variant="error" typeLevel="subtext.large">Error text</Text>
cs

The cs prop takes in a single value or an array of values. You can pass the CSS class name returned by , or the result of and . If you're extending a component already using cs, you can merge that prop in as well. Any style that is passed to the cs prop will override style props. If you wish to have styles that are overridden by the css prop, or styles added via the styled API, use wherever elemProps is used. If your component needs to also handle style props, use instead.

import {handleCsProp} from '@workday/canvas-kit-styling';
import {mergeStyles} from '@workday/canvas-kit-react/layout';
// ...
// `handleCsProp` handles compat mode with Emotion's runtime APIs. `mergeStyles` has the same
// function signature, but adds support for style props.
return (
<Element
{...handleCsProp(elemProps, [
myStyles,
myModifiers({ size: 'medium' }),
myVars({ backgroundColor: 'red' })
])}
>
{children}
</Element>
)
childrenReactNode
asReact.ElementType

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.forwardRefand spread extra props to a root element.

Note: Not all elements make sense and some elements may cause accessibility issues. Change this value with care.

span
refReact.Ref<R = span>

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

StatusIndicator.Icon

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

<StatusIndicator.Icon icon={uploadCloudIcon} />

Layout Component

StatusIndicator.Icon supports all props from thelayout component.

Props

Props extend from span. Changing the as prop will change the element interface.

NameTypeDescriptionDefault
icon

The icon to display from @workday/canvas-system-icons-web.

size number string undefined

The size of the SystemIcon in px.

20
accent

The accent color of the SystemIcon. This overrides color.

accentHover

The accent color of the SystemIcon on hover. This overrides colorHover.

background

The background color of the SystemIcon.

backgroundHover

The background color of the SystemIcon on hover.

color

The color of the SystemIcon. This defines accent and fill. color may be overriden by accent and fill.

colorHover

The hover color of the SystemIcon. This defines accentHover and fillHover. colorHover may be overriden by accentHover and fillHover.

fill

The fill color of the SystemIcon. This overrides color.

fillHover

The fill color of the SystemIcon on hover. This overrides colorHover.

styles
shouldMirrorboolean

If set to true, transform the SVG's x-axis to mirror the graphic

false
cs

The cs prop takes in a single value or an array of values. You can pass the CSS class name returned by , or the result of and . If you're extending a component already using cs, you can merge that prop in as well. Any style that is passed to the cs prop will override style props. If you wish to have styles that are overridden by the css prop, or styles added via the styled API, use wherever elemProps is used. If your component needs to also handle style props, use instead.

import {handleCsProp} from '@workday/canvas-kit-styling';
import {mergeStyles} from '@workday/canvas-kit-react/layout';
// ...
// `handleCsProp` handles compat mode with Emotion's runtime APIs. `mergeStyles` has the same
// function signature, but adds support for style props.
return (
<Element
{...handleCsProp(elemProps, [
myStyles,
myModifiers({ size: 'medium' }),
myVars({ backgroundColor: 'red' })
])}
>
{children}
</Element>
)
childrenReactNode
asReact.ElementType

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.forwardRefand spread extra props to a root element.

Note: Not all elements make sense and some elements may cause accessibility issues. Change this value with care.

span
refReact.Ref<R = span>

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

Optional 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(
  model: ,
  elemProps: TProps
) => HTML Attributes

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

useStatusIndicatorIcon

(
  model: ,
  elemProps: {},
  ref: React.Ref
) => {
  color: string;
  colorHover: string;
}

Model

useStatusIndicatorModel

useStatusIndicatorModel (config: ):

Accessibility Guidelines

How Status Indicators Impact the Accessible Experience?

Status Indicators do not have any keyboard interaction because they represent static text on the UI. However, when the text inside Status Indicator is truncated (overflow), users must be able to display the full text using a keyboard only.

When using icons in Status Indicators, the icons may be considered decorative in most cases and will not require any text alternatives for screen readers. In cases where the icon communicates something about the status that is not conveyed by the text of the status, then the icon will need to be augmented with a text alternative.

Keyboard Interaction

When the Status Indicator text overflows, it must have a focus indicator that is highly visible against the background and against the non-focused state. Refer to Accessible Colors for more information.

Status Indicator with overflow must support the following keyboard interactions:

  • Tab: focus the status indicator, tooltip displays when status indicator is focused
  • Esc: dismiss tooltip

Design Annotations Needed

No annotations required for Status Indicators

Implementation Markup Needed

  • Multiple Status Indicators can be grouped together using unordered list markup, <ul> and <li> elements.
  • Status Indicator with overflow must have a tabindex attribute and an OverflowTooltip to display the full text on hover and keyboard focus.
  • [Included in component] Decorative <svg> icons are hidden from assistive technology with role=“presentation” and focusable=“false”

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