Status Indicator
Status Indicators help the user quickly identify the status of a task, action, or page element.
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.
Anatomy
- Text: Bold, single-line, title-case text is used to recognize a status quickly.
- 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).
- 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.
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
.
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.
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.
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
.
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.
Name | Type | Description | Default |
---|---|---|---|
children | ReactNode | Children of the | |
flexDirection | 'row' |Â 'row-reverse' | sets the direction for the stack | 'row' |
as | React.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 Note: Not all elements make sense and some elements may cause accessibility issues. Change this value with care. | div |
ref | React.Ref | Optional ref. If the component represents an element, this ref will be a reference to the real DOM element of the component. If | |
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 | ( | 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.
Name | Type | Description | Default |
---|---|---|---|
typeLevel | | Type token as string with level and size separated by dot. These values map to our Canvas type levels.
| 'subtext.large' |
variant | keyof | Type variant token names:
| |
children | ReactNode | ||
as | React.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 Note: Not all elements make sense and some elements may cause accessibility issues. Change this value with care. | span |
ref | React.Ref | Optional ref. If the component represents an element, this ref will be a reference to the real DOM element of the component. If |
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
supports all props from the
layout component.
Props
Props extend from span. Changing the as
prop will change the element interface.
Name | Type | Description | Default |
---|---|---|---|
icon |
| The icon to display from | |
size | number |Â string |Â undefined | The size of the SystemIcon in | 20 |
accent |
| The accent color of the SystemIcon. This overrides | |
accentHover |
| The accent color of the SystemIcon on hover. This overrides | |
background |
| The background color of the SystemIcon. |
|
backgroundHover |
| The background color of the SystemIcon on hover. |
|
color |
| The color of the SystemIcon. This defines |
|
colorHover |
| The hover color of the SystemIcon. This defines |
|
fill |
| The fill color of the SystemIcon. This overrides | |
fillHover |
| The fill color of the SystemIcon on hover. This overrides | |
styles |
| ||
shouldMirror | boolean | If set to | false |
children | ReactNode | ||
as | React.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 Note: Not all elements make sense and some elements may cause accessibility issues. Change this value with care. | span |
ref | React.Ref | Optional ref. If the component represents an element, this ref will be a reference to the real DOM element of the component. If | |
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 | ( | 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
- 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