Skip to content
lab components / Data Visualization

Trend Formatter

Visually communicates trends (positive, negative, or neutral) in numerical data within highlights and tables, enhancing data comprehension.

ExamplesBaseTrendFormatterPropertiesGuidelines

This is a Lab component!

That means it doesn't satisfy our definition of done and may be changed or even deleted. For an exact status, please reach out to the Fancy team through the dev_fancy or ux_fancy channels.

import { TrendFormatter } from "@siteimprove/fancylab";

#Examples

Up: 42
<TrendFormatter value={42} referenceValue={41} />

#Variants

The TrendFormatter consists of an icon arrow colored red, green, or gray to indicate whether the change is negative, positive, or neutral, respectively. It's accompanied by a number next to the arrow that displays the specific value of the change (e.g., "+5%", "-3.2%").

Up: 42
Down: 41
Neutral: 42

Up: 42
Down: 42
Neutral: 42

Up: 42
Down: 41
Neutral: 42
<TrendFormatter value={42} referenceValue={41} variant="green-positive" /> <TrendFormatter value={41} referenceValue={42} variant="green-positive" /> <TrendFormatter value={42} referenceValue={42} variant="green-positive" /> <br /> <TrendFormatter value={42} referenceValue={41} variant="red-positive" /> <TrendFormatter value={42} referenceValue={43} variant="red-positive" /> <TrendFormatter value={42} referenceValue={42} variant="red-positive" /> <br /> <TrendFormatter value={42} referenceValue={41} variant="neutral" /> <TrendFormatter value={41} referenceValue={42} variant="neutral" /> <TrendFormatter value={42} referenceValue={42} variant="neutral" />

#Alignment

The TrendFormatter offers flexible alignment options, allowing you to position the trend indicator to the left or right of the numerical value. Choose the alignment that best complements the surrounding content and layout.

Up: 42
Up: 42
<TrendFormatter value={42} referenceValue={41} alignment="left" /> <TrendFormatter value={42} referenceValue={41} alignment="right" />

#BaseTrendFormatter

import { BaseTrendFormatter } from "@siteimprove/fancylab";

The BaseTrendFormatter is a fundamental building block for creating custom trend indicators. It provides a standardized structure and default styling that can be easily extended and customized to match your specific design requirements.

Down: 42
Down: 42
Down: 42

Up: 42
Up: 42
Up: 42

Neutral: 42

Down: 42
Down: 42
Down: 42

Up: 42
Up: 42
Up: 42

Neutral: 42
Neutral: 42
<BaseTrendFormatter value={42} direction="down" color="green" /> <BaseTrendFormatter value={42} direction="down" color="red" /> <BaseTrendFormatter value={42} direction="down" color="gray" /> <br /> <BaseTrendFormatter value={42} direction="up" color="green" /> <BaseTrendFormatter value={42} direction="up" color="red" /> <BaseTrendFormatter value={42} direction="up" color="gray" /> <br /> <BaseTrendFormatter value={42} direction="neutral" /> <br /> <BaseTrendFormatter value={42} direction="down" color="green" alignment="right" /> <BaseTrendFormatter value={42} direction="down" color="red" alignment="right" /> <BaseTrendFormatter value={42} direction="down" color="gray" alignment="right" /> <br /> <BaseTrendFormatter value={42} direction="up" color="green" alignment="right" /> <BaseTrendFormatter value={42} direction="up" color="red" alignment="right" /> <BaseTrendFormatter value={42} direction="up" color="gray" alignment="right" /> <br /> <BaseTrendFormatter value={42} direction="neutral" alignment="left" /> <BaseTrendFormatter value={42} direction="neutral" alignment="right" />

#Properties

#TrendFormatter

Up: 42
PropertyDescriptionDefinedValue
valueRequired
numberThe trend value
referenceValueRequired
numberThe reference value
classNameOptional
stringCustom className that's applied to the outermost element (only intended for special cases)
onKeyDownOptional
functionCallback for onKeyDown event
onBlurOptional
functionCallback for onBlur event
onMouseDownOptional
functionCallback for onMouseDown event
aria-describedbyOptional
stringID of an an element that describes the trend content
aria-labelOptional
stringLabel of the trend
aria-labelledbyOptional
stringID of an an element that labels this trend
data-observe-keyOptional
stringUnique string, used by external script e.g. for event tracking
styleOptional
objectStyle object to apply custom inline styles (only intended for special cases)
colorOptional
stringThe arrow color
alignmentOptional
"left" | "right"Whether the arrow comes before or after the number
tabIndexOptional
numberTab index of the outermost HTML element of the component
onMouseEnterOptional
functionCallback for onMouseEnter event
onMouseLeaveOptional
functionCallback for onMouseLeave event
onFocusOptional
functionCallback for onFocus event
variantOptional
"green-positive" | "neutral" | "red-positive"

#BaseTrendFormatter

Up: 45
PropertyDescriptionDefinedValue
valueRequired
| string | numberThe trend value
directionRequired
"down" | "neutral" | "up"The arrow orientation
colorOptional
stringThe arrow color
alignmentOptional
"left" | "right"Whether the arrow comes before or after the number
aria-labelOptional
stringLabel of the trend
aria-labelledbyOptional
stringID of an an element that labels this trend
aria-describedbyOptional
stringID of an an element that describes the trend content
data-observe-keyOptional
stringUnique string, used by external script e.g. for event tracking
classNameOptional
stringCustom className that's applied to the outermost element (only intended for special cases)
styleOptional
objectStyle object to apply custom inline styles (only intended for special cases)
tabIndexOptional
numberTab index of the outermost HTML element of the component
onKeyDownOptional
functionCallback for onKeyDown event
onMouseDownOptional
functionCallback for onMouseDown event
onMouseEnterOptional
functionCallback for onMouseEnter event
onMouseLeaveOptional
functionCallback for onMouseLeave event
onFocusOptional
functionCallback for onFocus event
onBlurOptional
functionCallback for onBlur event

#Guidelines

#Best practices

#General

Use TrendFormatter when

  • You want to visually highlight trends in numerical data.
  • You need to communicate positive, negative, or neutral trends quickly.

#Placement

TrendFormatter is typically used in the following places:

  • Highlight: Within cards, summaries, or other visual elements that emphasize key data points.
  • Table: Within table cells to provide context and comparison between numerical values.

#Style

  • Siteimprove Design System: Adhere to Siteimprove's guidelines for color, typography, and spacing. If you are not using a component from Fancy, match the styling of your TrendFormatter to existing components for visual consistency.

#Do not use when

  • The numerical value itself is sufficient to convey the information.
  • The trend is not a significant aspect of the data being presented.
  • The use of trend indicators would add unnecessary visual clutter.

#Accessibility

#For designers

  • Ensure sufficient color contrast between the trend indicator and its background for visually impaired users.
  • Provide alternative text descriptions for screen readers.

#For developers

This component comes with built-in accessibility, no extra work required.

Explore detailed guidelines for this component: Accessibility Specifications

#Writing

  • Use short, descriptive labels to convey the trend.
  • Consider adding additional information or a tooltip to explain the trend calculation or provide further details.