Nearly Perfect Mediocracy

    This package has been deprecated

    Author message:

    the package is rather renamed to @formatjs/ecma-abstract with some changes in functionality (primarily selectUnit is removed and we don't plan to make any further changes to this package

    TypeScript icon, indicating that this package has built-in type declarations

    3.8.4 • Public • Published

    Intl Utils

    Provide i18n utilities.

    npm Version



    This function determines the best fit unit based on a specific set of customizable thresholds.

    function selectUnit(
      from: Date | number,
      to: Date | number =,
      thresholds = DEFAULT_THRESHOLDS
    ): {value: number; unit: Unit};

    where thresholds has the shape of:

    interface Threshold {
      second: number;
      minute: number;
      hour: number;
      day: number;

    month & year are based on calendar, thus not customizable.


    import {selectUnit} from '@formatjs/intl-utils';
    selectUnit( - 1000); // { value: -1, unit: 'second' }
    selectUnit( - 44000); // { value: -44, unit: 'second' }
    selectUnit( - 50000); // { value: 1, unit: 'minute' }


    selectUnit is meant to be a stepping stone from the old IntlRelativeFormat to the officially spec-ed Intl.RelativeTimeFormat. Therefore we don't recommend using this for an extended period of time because of ambiguous editorial issues such as:

    • From 2019/01/01 -> 2018/11/01 can technically be last year, 2 months ago or a quarter ago.

    • From 2019/01/02 6am to 2019/01/01 11pm can also be 7 hours ago or yesterday. Timezone further complicates the issue.

    The examples above have not even tackled the differences in non-Gregorian calendars. There is an issue opened upstream in the spec that potentially introduces a best fit algorithm. Therefore, we recommend that you implement your own version of selectUnit that matches your editorial expectation. This will be removed in future releases.


    npm i @formatjs/intl-utils

    DownloadsWeekly Downloads






    Unpacked Size

    126 kB

    Total Files


    Last publish


    • longlho
    • pyrocat
    • redonkulus