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.

<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

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