Skip to content

Standalone Angular pipes using the ECMAScript Internationalization API, which provides language sensitive string comparison, number formatting, and date and time formatting.

License

Notifications You must be signed in to change notification settings

haiilo/ngx-intl

Repository files navigation

Angular Intl

This project was generated with Angular CLI version 14.1.0. The project provides the following set of standalone Angular pipes:

What is Intl?

The Intl object is the namespace for the ECMAScript Internationalization API, which provides language sensitive string comparison, number formatting, and date and time formatting. For more information, take a look at the mdm web docs.

Changelog

The latest changes are available within this repository in the project's CHANGELOG file.

intl-date

Format a date according to locale and formatting options.

Description

Just like the Angular DatePipe, IntlDatePipe is executed only when it detects a pure change to the input value. A pure change is either a change to a primitive input value (such as String, Number, Boolean, or Symbol), or a changed object reference (such as Date, Array, Function, or Object).

Note that mutating a Date object does not cause the pipe to be rendered again. To ensure that the pipe is executed, you must create a new Date object.

The default locale used for formatting is the one provided by the Angular LOCALE_ID injection token. See the I18n guide for more information. It can also be passed into the pipe as a third parameter.

The time zone of the formatted value can be specified either by passing it in as a property of the second parameter of the pipe, or by setting the default through the INTL_DATE_TIMEZONE injection token. The value that is passed in as the second parameter takes precedence over the one defined using the injection token.

Pre-defined format options

The pipe comes with a set of pre-defined format options as shown below.

Option Examples (given in en-US locale)
'short' 6/15/15, 9:03 AM
'medium' Jun 15, 2015, 9:03:01 AM
'long' June 15, 2015 at 9:03:01 AM GMT+1
'full' Monday, June 15, 2015 at 9:03:01 AM GMT+01:00
'shortDate' 6/15/15
'mediumDate' Jun 15, 2015
'longDate' June 15, 2015
'fullDate' Monday, June 15, 2015
'shortTime' 9:03 AM
'mediumTime' 9:03:01 AM
'longTime' 9:03:01 AM GMT+1
'fullTime' 9:03:01 AM GMT+01:00

Presets and custom configuration

You can add custom configuration and presets using the INTL_DATE_OPTIONS injection token. This allows the definition of additional presets as well as setting a default preset, which is used if no preset name is provided to the pipe.

@NgModule({
  //…,
  providers: [
    //…,
    {
      provide: INTL_DATE_OPTIONS,
      useValue: {
        defaultPreset: 'custom'
        presets: {
          custom: {
            dateStyle: 'short'
          }
        }
      }
    },
    {
      provide: INTL_DATE_TIMEZONE,
      useValue: 'America/Los_Angeles'
    }
  ]
})

API

Parameter Type Description
value Date | string | number | null | undefined The date to be formatted, given as a JS date, string or number.
options string | IntlDateLocalOptions The name of a preset or custom formatting options.
...locales string[] A list of locale overwrites.

Browser compatibility

See mdn web docs | Browser compatibility.

intl-timeago

Format a relative time according to locale and formatting options.

Description

Pre-defined format options

Presets and custom configuration

API

Browser compatibility

See mdn web docs | Browser compatibility (Intl.RelativeTimeFormat) and mdn web docs | Browser compatibility (Intl.DateTimeFormat).

intl-number

Format a number according to locale and formatting options.

Description

Pre-defined format options

Presets and custom configuration

API

Browser compatibility

See mdn web docs | Browser compatibility.

intl-plural

Enables plural-sensitive formatting.

Description

The IntlPluralPipe provides help for pluralization based on parameters provided in the options. The locales and options parameters customize the behavior of the pipe and let applications specify the language conventions that should be used.

Pre-defined format options

The pipe comes with a set of pre-defined sort options as shown below.

Option Examples (given in en-US locale)
'cardinal' 3other
'ordinal' 3few

Presets and custom configuration

You can add custom configuration and presets using the INTL_PLURAL_OPTIONS injection token. This allows the definition of additional presets as well as setting a default preset, which is used if no preset name is provided to the pipe.

@NgModule({
  //…,
  providers: [
    //…,
    {
      provide: INTL_PLURAL_OPTIONS,
      useValue: {
        defaultPreset: 'custom'
        presets: {
          custom: {
            type: 'ordinal'
          }
        }
      }
    }
  ]
})

API

Parameter Type Description
value number | null The number to be converted.
options string | IntlPluralLocalOptions The name of a preset or custom pluralization options.
...locales string[] A list of locale overwrites.

Browser compatibility

See mdn web docs | Browser compatibility.

intl-sort

Enables language-sensitive string comparison.

Description

The IntlSortPipe sorts a list of strings based on parameters provided in the options. The locales and options parameters customize the behavior of the pipe and let applications specify the language conventions that should be used to sort the list.

Pre-defined format options

You can add custom configuration and presets using the INTL_SORT_OPTIONS injection token. This allows the definition of additional presets as well as setting a default preset, which is used if no preset name is provided to the pipe.

@NgModule({
  //…,
  providers: [
    //…,
    {
      provide: INTL_SORT_OPTIONS,
      useValue: {
        defaultPreset: 'custom'
        presets: {
          custom: {
            sensitivity: 'base'
          }
        }
      }
    }
  ]
})

Presets and custom configuration

The pipe comes with a set of pre-defined sort options as shown below.

Option Examples (given in en-US locale)
'lowerFirst' ['a', 'e', 'z', 'Z']
'upperFirst' ['a', 'e', 'Z', 'z']

API

Parameter Type Description
value string[] | null The list of strings to be sorted.
options string | IntlSortLocalOptions The name of a preset or custom sort options.
...locales string[] A list of locale overwrites.

Browser compatibility

See mdn web docs | Browser compatibility.

Code Contributors

This project exists thanks to all the people who contribute.

License

The license is available within this repository in the LICENSE file.

About

Standalone Angular pipes using the ECMAScript Internationalization API, which provides language sensitive string comparison, number formatting, and date and time formatting.

Resources

License

Stars

Watchers

Forks