Duration

Components

Duration

Code

Duration is a primitive component used to format durations of time according to our date & time formatting guidelines.

Please refer to our date & time formatting guidelines for more detailed information on how we format durations.

import { Duration } from '@sproutsocial/racine'

<Box display='flex' justifyContent='center'>
  <Duration milliseconds={123456789} invalidMillisecondsLabel='Not Available' />
</Box>

When the milliseconds prop is not a valid duration of time, Duration will automatically render an em dash to represent a null value. Always provide an invalidMillisecondsLabel prop to Duration so that a text alternative for screen reader users will be added to any null values.

<Box display='flex' justifyContent='center'>
  <Duration milliseconds={null} invalidMillisecondsLabel='Not Available' />
</Box>

Properties

Name	Type	Default	Description
`milliseconds`	`number` `null`	`null`	The milliseconds to be formatted.
`locale`	`Intl.LocalesArgument`	`en-US`	Locale to format. See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locales_argument.
`display`	`'long'` `'narrow'`	`narrow`	The style of the formatted duration.
`displayUnits`	`{ days?: boolean, hours?: boolean, minutes?: boolean, seconds?: boolean, milliseconds?: boolean, }`	`{ days: true, hours: true, minutes: true, seconds: true, milliseconds: false, }`	The units of the duration to render
`invalidMillisecondsLabel`	`string`		Text to be read off by screen readers for invalid values (i.e., any value rendered as '—' (em dash))
`qa`	`Object`

Note: This component uses the Text component under the hood, and accepts all of the props of that component in addition to those listed above.

Recipes

Long display

<Box display='flex' justifyContent='center'>
  <Duration milliseconds={123456789} display='long' />
</Box>

Display Units

Use the displayUnits prop to let Duration know which time units to render. Passing in an empty object will return the default displayUnits.

<Box display='flex' justifyContent='center'>
  <Duration
    milliseconds={123456789}
    displayUnits={{
      hours: true,
      minutes: true,
    }}
  />
</Box>

Negative milliseconds

When milliseconds is negative, Duration will return the same result as if it were 0.

<Box display='flex' justifyContent='center'>
  <Duration milliseconds={-123456789} />
</Box>

Helpers

formatDuration()

formatDuration() is a helper function that returns a string version of the content that gets rendered in the Duration component. It accepts all the same props as the Duration component listed above.

<Text>
  {formatDuration({
    milliseconds: 123456789
  })}
</Text>

getDurationMaxDisplayUnits()

getDurationMaxDisplayUnits() is a helper function that gets the largest number of display units based on the milliseconds value. For example, if you want to render only the 2 highest display units, you could call getDurationMaxDisplayUnits with the argument maxDisplayUnits: 2. Doing so would return either {days: true, hours: true}, {hours: true, minutes: true}, {minutes: true, seconds: true}, or {seconds: true, milliseconds: true}, all depending on the size of the milliseconds.

() => {
  const milliseconds = 123456789;

  return (
    <Box display='flex' justifyContent='center'>
      <Duration
        milliseconds={milliseconds}
        displayUnits={
          getDurationMaxDisplayUnits({
            milliseconds,
            maxDisplayUnits: 2,
          })
        }
      />
    </Box>
  )
}