useFormattedMetricValue

Formats the value of a ChannelValue for display, based on the value type of the metric: numbers are rounded, dates are formatted, and so on.

function useFormattedMetricValue(
  channelValue: ChannelValue | null,
  options: FormatMetricValueOptions
): FormattedMetricValue | null

To format values outside of rendering, e.g. within the memo function of useMemoizedMetricField, use useFormatMetricValue. It returns the formatting function itself:

function useFormatMetricValue(): (
  channelValue: ChannelValue | null,
  options: FormatMetricValueOptions
) => FormattedMetricValue | null

Arguments

Argument	Type	Description
channelValue	ChannelValue | null	The value to format, e.g. as returned by useMetricField.
options	FormatMetricValueOptions	Formatting options, see below. Pass {} for the defaults.

Options

All options are optional. Each option only applies to the listed value types.

Option	Type	Value types	Description
precision	number	Numeric, Duration	The number of decimals. Defaults to 2.
autoConvertUnit	boolean	Numeric, Duration	Converts the value to the largest unit of the metric type in which the value is still at least 1, e.g. 1.5 GB instead of 1536 MB.
dateTimeFormat	string	DateTime	The format of date and time values, e.g. yyyy-mm-dd HH:MM:ss.
dateFormat	string	DateOnly	The format of date values, e.g. yyyy-mm-dd.
timeFormat	string	TimeOnly	The format of time values, e.g. HH:MM:ss.
formatDateTime	(date: Date) => ReactNode	DateTime	Custom formatting of date and time values. Takes precedence over dateTimeFormat.
formatDate	(date: Date) => ReactNode	DateOnly	Custom formatting of date values. Takes precedence over dateFormat.
formatTime	(date: Date) => ReactNode	TimeOnly	Custom formatting of time values. Takes precedence over timeFormat.
timezone	string	DateTime, DateOnly, TimeOnly	Converts dates to this timezone. Only applied together with language.
language	string	DateTime, DateOnly, TimeOnly	The language used to convert dates to the timezone.
formatResource	(resourceId: string) => ReactNode	Resource	Renders a resource, e.g. as image.
baseUrl	string	Resource	Renders the resource as <object>, loaded from this base URL. Ignored if formatResource is set.

The format strings use the masks of the dateformat library, e.g. yyyy for the year, mm for the month, HH for 24-hour hours, MM for minutes and TT for AM/PM.

Returns

A FormattedMetricValue, or null if channelValue is null:

Property	Type	Description
value	ReactNode	The formatted value. Strings starting with http:// or https:// are rendered as links.
unit	string	The abbreviation of the unit, if the value has one.
unitPosition	'before' | 'after'	Whether to display the unit before the value (e.g. currencies) or after it.

How values are formatted depends on the value type of the metric:

Value type	Formatting
Numeric, Duration	Rounded to precision decimals, unit after the value
Currency	Two decimals in the format of the device's locale, unit before the value
DateTime, DateOnly, TimeOnly	Formatted using the options above, otherwise the ISO string. No unit.
Resource	Rendered using formatResource or baseUrl, otherwise the resource id. No unit.
Other value types	The value as string, unit after the value

A metric without a value is formatted as an empty string.

Example

src/widgets/example/Example.tsx

import React from 'react'
import {useFormattedMetricValue, useMetricField} from '@modbros/dashboard-sdk'
import {createMetricResourcePath} from '@modbros/dashboard-core'

export default function Example() {
  const channelValue = useMetricField({field: 'metric'})
  const formatted = useFormattedMetricValue(channelValue, {
    precision: 1,
    dateTimeFormat: 'yyyy-mm-dd HH:MM',
    formatResource: (resourceId) => <img src={createMetricResourcePath(resourceId)} alt={resourceId}/>
  })

  if (!formatted) {
    return null
  }

  return (
    <span>
      {formatted.unitPosition === 'before' && formatted.unit}
      {formatted.value}
      {formatted.unitPosition === 'after' && formatted.unit}
    </span>
  )
}

createMetricResourcePath, exported by @modbros/dashboard-core, returns the URL of a resource provided by a plugin.