{"id":22423367,"url":"https://github.com/prantlf/intl-datetimeformat-options","last_synced_at":"2026-06-22T08:31:38.472Z","repository":{"id":143005319,"uuid":"614604569","full_name":"prantlf/intl-datetimeformat-options","owner":"prantlf","description":"Provides localized date/time format patterns for styles full, long, medium and short, using Intl.DateTimeFormat.","archived":false,"fork":false,"pushed_at":"2025-08-14T07:57:03.000Z","size":105,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-10-29T01:49:04.926Z","etag":null,"topics":["cldr","date","datetime","format","intl","ldml","locale","pattern","time","unicode"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/prantlf.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-03-15T23:47:55.000Z","updated_at":"2025-08-14T07:57:07.000Z","dependencies_parsed_at":null,"dependency_job_id":"c4303465-59d0-44fd-af66-105bc4d9c5df","html_url":"https://github.com/prantlf/intl-datetimeformat-options","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/prantlf/intl-datetimeformat-options","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prantlf%2Fintl-datetimeformat-options","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prantlf%2Fintl-datetimeformat-options/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prantlf%2Fintl-datetimeformat-options/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prantlf%2Fintl-datetimeformat-options/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/prantlf","download_url":"https://codeload.github.com/prantlf/intl-datetimeformat-options/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prantlf%2Fintl-datetimeformat-options/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34641636,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-22T02:00:06.391Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cldr","date","datetime","format","intl","ldml","locale","pattern","time","unicode"],"created_at":"2024-12-05T18:10:43.079Z","updated_at":"2026-06-22T08:31:38.459Z","avatar_url":"https://github.com/prantlf.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Intl DateTime Format Patterns\n\n[![Latest version](https://img.shields.io/npm/v/intl-datetimeformat-options)\n ![Dependency status](https://img.shields.io/librariesio/release/npm/intl-datetimeformat-options)\n](https://www.npmjs.com/package/intl-datetimeformat-options)\n[![Coverage](https://codecov.io/gh/prantlf/intl-datetimeformat-options/branch/master/graph/badge.svg)](https://codecov.io/gh/prantlf/intl-datetimeformat-options)\n\nProvides localized date/time format patterns for styles `full`, `long`, `medium` and `short`, using [`Intl.DateTimeFormat`]. For example:\n\n| Locale | Style | Pattern             | Example                     |\n|:-------|:------|:--------------------|:----------------------------|\n| en     | short | M/d/yy, h:mm a      | 2/3/01, 4:05 AM             |\n| cs     | long  | d. MMMM y H:mm:ss z | 3. února 1901 4:05:06 GMT+1 |\n\n```js\nconst formatter = new Intl.DateTimeFormat('cs', { dateStyle: 'short'})\nconst pattern = getDateTimeFormatPattern(formatter) // d.M.yy\n```\n\n* ES, CJS and UMD module exports.\n* TypeScript type declarations (typings).\n* No other dependencies.\n* Tiny code base - 2.73 kB minified, 1.31 B gzipped, 1.16 B brotlied.\n* Resolves four date/time-formatting pattern styles (lengths) - `full`, `long`, `medium`, `short`.\n\nThis library needs a working implementation of `Intl.DateTimeFormat`.If you are interested in a library, which does not need `Intl.DateTimeFormat` and uses [CLDR data] to be compliant with [Unicode LDML] too, have look at [datetime-locale-patterns].\n\nRelated projects:\n\n* [date-and-time-formatter] - formats a date/time value to a localised string using a pattern consisting of [Unicode LDML] tokens.\n* [datetime-placeholder] - simplifies a date/time-formatting pattern using [Unicode LDML] tokens to a pattern usable in date/time pickers.\n* [datetime-locale-patterns] - provides localized date/time format patterns for styles `full`, `long`, `medium` and `short` using [Unicode CLDR], compliant with [Unicode LDML].\n* [intl-datetimeformat-pattern] - creates a valid [`Intl.DateTimeFormat`] options object from a [Unicode CLDR] skeleton or token pattern.\n\n## Motivation\n\nWhen do you need to know the date/time format pattern? When is just formatting a date or time values to a string not enough?\n\n1. **Date/time pickers.** You format with [`Intl.DateTimeFormat`]. [`Intl.DateTimeFormat`] or [luxon] format using a localized pattern decided by a specified locale. No need to provide the format explicitly. But what if you need to display the format pattern, which is used for the formatting? For example, in a date picker field as a value placeholder.\n2. **Raw date/time formatting.** You do not format with [`Intl.DateTimeFormat`]. Libraries like [date-and-time], [date-fns] and others format using patterns provided by the developer. But how to get a localized pattern for a particular language and country?\n\nThere is no built-in API in browsers or Node.js for getting localized date/time-formatting patterns.\n\n## Synopsis\n\n1. **Date/time pickers.** Get a pattern to see in an abstract way how a concrete date will be formatted:\n\n```js\nimport { getDateTimeFormatPattern } from 'intl-datetimeformat-options'\n\nconst date = new Date(1, 1, 3, 4, 5, 6)\nconst options = { dateStyle: 'short', timeStyle: 'short' }\n\nconst formatter = new Intl.DateTimeFormat('en', options)\nconst text = formatter.format(date)\nconsole.log(text) // prints '2/3/01, 4:05 AM'\n\nconst pattern = getDateTimeFormatPattern('en', options)\nconsole.log(pattern) // prints 'M/d/yy, h:mm a'\n```\n\n2. **Raw date/time formatting.** Get a pattern to format a concrete date with:\n\n```js\nimport { getDateTimeFormatPattern } from 'intl-datetimeformat-options'\nimport formatter from 'date-and-time'\n\nconst date = new Date(1, 1, 3, 4, 5, 6)\n\nconst pattern = getDateTimeFormatPattern('en', 'short', 'short')\nconsole.log(pattern) // prints 'M/d/yy, h:mm a'\n\nconst text = formatter.format(date, pattern)\nconsole.log(text) // prints '2/3/01, 4:05 AM'\n```\n\n## Installation\n\nThis module can be installed in your project using [NPM], [PNPM] or [Yarn]. Make sure, that you use [Node.js] version 16.14 or newer.\n\n```sh\n$ npm i intl-datetimeformat-options\n$ pnpm i intl-datetimeformat-options\n$ yarn add intl-datetimeformat-options\n```\n\nFunctions are exposed as named exports from ES and CJS modules, for example:\n\n```js\nimport { getDateTimeFormatPattern } from 'intl-datetimeformat-options'\n```\n\n```js\nconst { getDateTimeFormatPattern } = require('intl-datetimeformat-options')\n```\n\nA UMD module can be loaded to the browser either directly:\n\n```html\n\u003cscript src=\"https://unpkg.com/intl-datetimeformat-options@1.0.0/lib/index.min.js\"\u003e\u003c/script\u003e\n\u003cscript\u003e\n  const { getDateTimeFormatPattern } = window.intlDateTimeFormatOptions\n\u003c/script\u003e\n```\n\nOr using an AMD module loader:\n\n```html\n\u003cscript\u003e\n  require([\n    'https://unpkg.com/intl-datetimeformat-options@1.0.0/lib/index.min.js'\n  ], ({ getDateTimeFormatPattern }) =\u003e {\n    ...\n  })\n\u003c/script\u003e\n```\n\n## API\n\nThis library works well with [`Intl.DateTimeFormat`] by using concepts from [Unicode CLDR] (Common Locale Data Repository):\n\n* It expects [Unicode locales] (2-letter and 3-letter languages and countries from [ISO 639] and [ISO 3166], formatted according to [extended BCP 47]), which [`Intl` locales] is based on.\n* It supports [Unicode calendar formats] - `date`, `time`, `dateTime`.\n* It expects [Unicode pattern styles] (lengths) - `full`, `long`, `medium`, `short`, as `dateStyle` and `timeStyle` properties of [`Intl.DateTimeFomat` options] do.\n* It supplies date/time-formatting patterns using [date fields] from [Unicode LDML] (Locale Data Markup Language) as tokens.\n\n### getDateTimeFormatPattern(locale, dateStyle?, timeStyle?)\n\nReturns a pattern to format a date+time value for the specified locale with the specified style.\n\nThe **locale** argument can be either a locale or an instance of `Intl.DateTimeFomat`. The second argument won't be needed in the latter case.\n\nThe **dateStyle** argument can be either a string (`full`, `long`, `medium`, `short`) or an object with `dateStyle` and `timeStyle` properties from [`Intl.DateTimeFomat` options]. If it is a string, the **timeStyle** argument will be required (as a string).\n\n```js\nimport { getDateTimeFormatPattern } from 'intl-datetimeformat-options'\n\nconst pattern = getDateTimeFormatPattern('en', 'short', 'short')\nconsole.log(pattern) // prints 'M/d/yy, h:mm a'\n```\n\n## Problems\n\nThe patterns are guessed by formatting a specific date (1901-02-03 04:05:06), parsing the formatted output and detecting numeric formats, names of days and months and other tokens from [Unicode LDML]. This needs a reliable implementation of [`Intl.DateTimeFormat`].\n\n* If the date/time formatting provided by the underlying OS API is used in the implementation of [`Intl.DateTimeFormat`], the actual pattern may differ from the multi-platform [Unicode CLDR].\n* If [ICU] (International Components for Unicode) library, which is supposed to be in sync with [Unicode CLDR], is used by a browser or Node.js, the version of that [ICU] may differ from the latest version of [Unicode CLDR] and from the implementation of [`Intl.DateTimeFormat`]. This can be seen in `long` and `full` styles of the `en` locale, which include a different \"glue pattern\" for joining data and time patterns. [ICU] includes \" at \", while [Unicode CLDR] includes \",\".\n\nPatterns returned by this library should match the behaviour of [`Intl.DateTimeFormat`] well. Patterns from [Unicode CLDR] may differ.\n\n## Contributing\n\nIn lieu of a formal styleguide, take care to maintain the existing coding style.  Add unit tests for any new or changed functionality. Lint and test your code using Grunt.\n\n## License\n\nCopyright (c) 2023-2025 Ferdinand Prantl\n\nLicensed under the MIT license.\n\n[Node.js]: http://nodejs.org/\n[NPM]: https://www.npmjs.com/\n[PNPM]: https://pnpm.io/\n[Yarn]: https://yarnpkg.com/\n[date-and-time]: https://github.com/knowledgecode/date-and-time#compileformatstring\n[date-fns]: https://github.com/date-fns/date-fns\n[luxon]: https://moment.github.io/luxon/\n[ICU]: https://icu.unicode.org/\n[CLDR data]: https://www.npmjs.com/package/cldr-dates-full\n[Unicode LDML]: https://unicode.org/reports/tr35/\n[Unicode CLDR]: https://cldr.unicode.org/\n[Unicode locales]: https://www.unicode.org/reports/tr35/#Language_and_Locale_IDs\n[`Intl` locales]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locale_identification_and_negotiation\n[ISO 3166]: https://en.wikipedia.org/wiki/ISO_3166\n[ISO 639]: https://en.wikipedia.org/wiki/ISO_639\n[extended BCP 47]: https://cldr.unicode.org/index/bcp47-extension\n[`Intl.DateTimeFormat`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat\n[Unicode pattern styles]: https://unicode.org/reports/tr35/tr35-dates.html#24-element-dateformats\n[Unicode calendar formats]: https://unicode.org/reports/tr35/tr35-dates.html#2-calendar-elements\n[date fields]: http://unicode.org/reports/tr35/tr35-dates.html#Date_Field_Symbol_Table\n[`Intl.DateTimeFomat` options]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat#options\n[date-and-time-formatter]: https://github.com/prantlf/date-and-time-formatter\n[datetime-placeholder]: https://github.com/prantlf/datetime-placeholder\n[datetime-locale-patterns]: https://github.com/prantlf/datetime-locale-patterns\n[intl-datetimeformat-pattern]: https://github.com/caridy/intl-datetimeformat-pattern\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprantlf%2Fintl-datetimeformat-options","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprantlf%2Fintl-datetimeformat-options","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprantlf%2Fintl-datetimeformat-options/lists"}