react intl formatted duration

Formatted Duration

react-intl is an amazing library providing React components and API to localize your application, however it lacks a Duration component.

If you want to show the time it takes to do something like 1 minute or 5 minutes or even a simple timer 0:30 you're out of luck because the ECMA committee hasn't specified the DurationFormat yet.

This component provides a very simple abstraction that works on React (DOM), React Native and any other target environment to format simple durations.

Usage

npm i --save react-intl-formatted-duration

Extended format

// Using React DOM
import React from 'react';
import FormattedDuration from 'react-intl-formatted-duration';

export default MyComponent() {
  return <FormattedDuration seconds={60} />
  // will render `1 minute`
}

The default format only shows minutes and seconds. For more complex needs check the custom format section.

By default the output text is wrapped in a span, you can specify any component you like available on your target environment:

// Using React Native
import React from 'react';
import FormattedDuration from 'react-intl-formatted-duration';

import { Text } from 'react-native';

export default MyComponent() {
  return <FormattedDuration seconds={60} textComponent={Text} />
  // will render `1 minute`
}

// Using styled components
import React from 'react';
import FormattedDuration from 'react-intl-formatted-duration';

import styled from 'styled-components';
const Text = styled.span``;

export default MyComponent() {
  return <FormattedDuration seconds={60} textComponent={Text} />
  // will render `1 minute`
}

Styling numbers

If you want to style numbers differently from text you can pass a valueComponent

<FormattedDuration seconds={90} textComponent={Text} valueComponent={Value} />

// renders

<Value>1</Value> minute</Text> <Value>30</Value> <Text>seconds</Text>

Having different components is useful not only for styling. Some languages use different numbering systems. For example Japanese has full-width numbers, so you might want to render １０分 instead of 10分, to do so you can use:

import React from 'react';
import { FormattedNumber } from 'react-intl';
import FormattedDuration from 'react-intl-formatted-duration';

/*
You'll also need to select Japanese locale and configure the IntlProvider to use
`ja-JP-u-nu-fullwide`

Somewhere in you application
import { IntlProvider } from 'react-intl';

   locale="ja-JP-u-nu-fullwide"
/>
 */

export default MyComponent() {
  return <FormattedDuration seconds={600} textComponent={Text} valueComponent={FormattedNumber} />
  // will render `１０分`
}

Custom format

Hours and days

By default the component only renders minutes and seconds, if you want to display hours or days you can use a custom format:

<FormattedDuration seconds={180000} format="{days} {hours} {minutes} {seconds}" />
// will render `2 days 2 hours`

<FormattedDuration seconds={180000} format="{hours} {minutes} {seconds}" />
// will render `50 hours`

<FormattedDuration seconds={180000} format="{minutes} {seconds}" />
// will render `3000 minutes`
}

Seconds is also optional and if missing, minutes will be rounded to the closed value

<FormattedDuration seconds={10} format="{minutes}" />
// will render `0 minutes`

<FormattedDuration seconds={30} format="{minutes}" />
// will render `1 minute`

<FormattedDuration seconds={70} format="{minutes}" />
// will render `1 minute`

The custom format can itself be localized by passing a message id instead of the actual value

import React from 'react';
import FormattedDuration from 'react-intl-formatted-duration';

import messages from './messages';

export default MyComponent() {
  return (
    <FormattedDuration
      seconds={600}
      format={messages.customFormat.id}
    />
  );
}

Unit display

While format allows to select which units to render, unitDisplay allows to configure the way each unit is rendered.

<FormattedDuration seconds={60} unitDisplay="long" />
// will render `1 minute`

<FormattedDuration seconds={60} unitDisplay="short" />
// will render `1 min`

<FormattedDuration seconds={60} unitDisplay="narrow" />
// will render `1m`

Timer format

import FormattedDuration, { TIMER_FORMAT } from 'react-intl-formatted-duration';

export default MyComponent() {
  return <FormattedDuration seconds={60} format={TIMER_FORMAT} />
  // will render `1:00`
}

Localization

react-intl-formatted-duration expects the following keys inside your translation file

• react-intl-formatted-duration.longFormatting the default format that generates something like 1 minute 30 seconds. It uses the values {days}, {hours}, {minutes} and {seconds}. For example you can change it to {minutes} and {seconds}.
• react-intl-formatted-duration.duration the format used by the minutes and seconds variables described above. It uses the values {value} and {unit}. The default is {value} {unit} where value is a number and {unit} is the textual unit like minute(s) or second(s).
• react-intl-formatted-duration.timerFormatting format for TIMER_FORMAT, defaults to {minutes}:{seconds} where both values are numbers padded to have a minimum length of 2 characters
• react-intl-formatted-duration.daysUnit string for formatting days, default {value, plural, one {day} other {days}}
• react-intl-formatted-duration.hoursUnit string for formatting hours, default {value, plural, one {hour} other {hours}}
• react-intl-formatted-duration.minutesUnit string for formatting minutes, default {value, plural, one {minute} other {minutes}}
• react-intl-formatted-duration.secondsUnit string for formatting seconds, default {value, plural, one {second} other {seconds}}

The messages for daysUnit, hoursUnit, minutesUnit, secondsUnit use the format-js syntax and are only used when unitDisplay is not specified.

If you're using the extract-intl script from react-boilerplate you can import react-intl-formatted-duration/messages to automatically generate the keys in your translation files.

Upgrading from version 1.0

Version 2.x allows to use the whole power of format-js message syntax. All you need to do is remove all keys like daysSingular, dayPlural and simply use daysUnit with the format described above.

Upgrading from version 2.0

Version 3.x has exactly the same API as version 2.x but is a complete rewrite. You don't need to change your code.

Upgrading from version 3.0

Version 4.x doesn't change any of the default behavior of version 3.x and only contains new features. However internally it bumps the version of intl-unofficial-duration-unit-format from 1.x to 3.x which now requires Intl.NumberFormat to be available globally. If you've installed react-intl correctly, chances are you don't need to change your code.