{"id":17260834,"url":"https://github.com/jakeboone02/format-quantity","last_synced_at":"2026-02-13T02:01:45.752Z","repository":{"id":28930674,"uuid":"32456332","full_name":"jakeboone02/format-quantity","owner":"jakeboone02","description":"Format a number as an integer plus fraction, as seen in recipe ingredient lists","archived":false,"fork":false,"pushed_at":"2025-04-11T16:40:58.000Z","size":3814,"stargazers_count":14,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-14T07:11:48.495Z","etag":null,"topics":["converts","fraction","javascript","quantity","recipe-ingredients","vulgar-fractions"],"latest_commit_sha":null,"homepage":"https://jakeboone02.github.io/format-quantity/","language":"TypeScript","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/jakeboone02.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","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,"zenodo":null},"funding":{"github":["jakeboone02"]}},"created_at":"2015-03-18T12:04:12.000Z","updated_at":"2025-04-11T16:40:54.000Z","dependencies_parsed_at":"2024-01-15T19:38:14.598Z","dependency_job_id":"bcfc9ace-380c-4aab-8855-f1e45d2839a7","html_url":"https://github.com/jakeboone02/format-quantity","commit_stats":{"total_commits":106,"total_committers":2,"mean_commits":53.0,"dds":"0.037735849056603765","last_synced_commit":"ae6a0d6f72e2a47b3d1f499a4b1808655e2f6e0b"},"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/jakeboone02/format-quantity","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jakeboone02%2Fformat-quantity","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jakeboone02%2Fformat-quantity/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jakeboone02%2Fformat-quantity/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jakeboone02%2Fformat-quantity/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jakeboone02","download_url":"https://codeload.github.com/jakeboone02/format-quantity/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jakeboone02%2Fformat-quantity/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259397855,"owners_count":22851313,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["converts","fraction","javascript","quantity","recipe-ingredients","vulgar-fractions"],"created_at":"2024-10-15T07:49:21.145Z","updated_at":"2026-02-13T02:01:45.748Z","avatar_url":"https://github.com/jakeboone02.png","language":"TypeScript","funding_links":["https://github.com/sponsors/jakeboone02"],"categories":[],"sub_categories":[],"readme":"[![npm][badge-npm]](https://www.npmjs.com/package/format-quantity)\n![workflow status](https://github.com/jakeboone02/format-quantity/actions/workflows/main.yml/badge.svg)\n[![codecov.io](https://codecov.io/github/jakeboone02/format-quantity/coverage.svg?branch=main)](https://codecov.io/github/jakeboone02/format-quantity?branch=main)\n[![downloads](https://img.shields.io/npm/dm/format-quantity.svg)](https://npm-stat.com/charts.html?package=format-quantity\u0026from=2015-08-01)\n[![MIT License](https://img.shields.io/npm/l/format-quantity.svg)](https://opensource.org/licenses/MIT)\n\nFormats a number (or string that appears to be a number) as one would see it written in imperial measurements, e.g. \"1 1/2\" instead of \"1.5\".\n\n**[Full documentation](https://jakeboone02.github.io/format-quantity/)**\n\nFeatures:\n\n- To use vulgar fraction characters like \"⅞\", pass `true` as the second argument. Other options like Roman numerals are described below.\n- String inputs are parsed with [`numeric-quantity`](https://www.npmjs.com/package/numeric-quantity), so mixed numbers (`\"1 1/2\"`), vulgar fractions (`\"½\"`), bare fractions (`\"1/3\"`), and comma/underscore-separated numbers (`\"1,000\"`) are all accepted in addition to plain decimal strings.\n- The return value will be `null` if the first argument is not a recognized numeric format.\n- The return value will be an empty string (`\"\"`) if the first argument is `0` or `\"0\"`, which fits the primary use case of formatting recipe ingredient quantities.\n\n\u003e _For the inverse operation—converting a string to a `number`—check out [numeric-quantity](https://www.npmjs.com/package/numeric-quantity). It handles mixed numbers, vulgar fractions, comma/underscore separators, and Roman numerals._\n\u003e\n\u003e _If you're interested in parsing recipe ingredient strings, try [parse-ingredient](https://www.npmjs.com/package/parse-ingredient)._\n\n## Usage\n\n### Installed\n\n```js\nimport { formatQuantity } from 'format-quantity';\n\nformatQuantity(1.5); // \"1 1/2\"\nformatQuantity(2.66); // \"2 2/3\"\nformatQuantity(3.875, true); // \"3⅞\"\n```\n\n### CDN\n\nAs an ES module:\n\n```html\n\u003cscript type=\"module\"\u003e\n  import { formatQuantity } from 'https://cdn.jsdelivr.net/npm/format-quantity/+esm';\n\n  console.log(formatQuantity(10.5)); // \"10 1/2\"\n\u003c/script\u003e\n```\n\nAs UMD (all exports are properties of the global object `FormatQuantity`):\n\n```html\n\u003cscript src=\"https://unpkg.com/format-quantity\"\u003e\u003c/script\u003e\n\u003cscript\u003e\n  console.log(FormatQuantity.formatQuantity(10.5)); // \"10 1/2\"\n\u003c/script\u003e\n```\n\n## Options\n\nThe second parameter to `formatQuantity` can be a `boolean` value or an options object.\n\n### `vulgarFractions`\n\n| Type      | Default |\n| --------- | ------: |\n| `boolean` | `false` |\n\nReturns vulgar fractions when appropriate. This option has the same effect as passing a plain `boolean` value as the second parameter.\n\n```js\nformatQuantity(3.875, { vulgarFractions: true }); // \"3⅞\"\n// is the same as\nformatQuantity(3.875, true); // \"3⅞\"\n```\n\nNote: `formatQuantity` supports sixteenths, but no vulgar fraction characters exist for that denomination. Therefore the `vulgarFractions` option has no effect if the fraction portion of the final string is an odd numerator over a denominator of `16`.\n\n### `fractionSlash`\n\n| Type      | Default |\n| --------- | ------: |\n| `boolean` | `false` |\n\nUses the [fraction slash character](\u003chttps://en.wikipedia.org/wiki/Slash_(punctuation)#Fractions\u003e) (`\"\\u2044\"`) to separate the numerator and denominator instead of the regular \"solidus\" slash (`\"\\u002f\"`), with Unicode superscript numerator and subscript denominator digits. This option is ignored if the `vulgarFractions` option is also `true`.\n\n```js\nformatQuantity(3.875, { fractionSlash: true }); // \"3 ⁷⁄₈\"\nformatQuantity(3.875, { fractionSlash: true, vulgarFractions: true }); // \"3⅞\"\n```\n\n### `separator`\n\n| Type     | Default |\n| -------- | ------: |\n| `string` |     N/A |\n\nOverrides the string placed between the whole number and the fraction. When not specified, the default is `\" \"` (a space) for ASCII and fraction-slash fractions, and `\"\"` (no space) for vulgar fractions. Common alternatives include a hyphen (`\"-\"`) and a no-break space (`\"\\u00a0\"`).\n\n```js\nformatQuantity(1.5, { separator: '-' }); // \"1-1/2\"\nformatQuantity(1.5, { separator: ' ', vulgarFractions: true }); // \"1 ½\"\nformatQuantity(1.5, { separator: '\\u00a0' }); // \"1\\u00a01/2\" (no-break space)\n```\n\n### `tolerance`\n\n| Type     |  Default |\n| -------- | -------: |\n| `number` | `0.0075` |\n\nThis option determines how close the decimal portion of a number has to be to the actual quotient of a fraction to be considered a match. For example, consider the fraction 1⁄3: $1 \\div 3 = 0.\\overline{333}$, repeating forever. The number `0.333` (exactly 333 thousandths) is not equivalent to 1⁄3, but it's very close. So even though $0.333 \\neq 1 \\div 3$, both `formatQuantity(0.333)` and `formatQuantity(1/3)` will return `\"1/3\"`.\n\nA lower tolerance increases the likelihood that `formatQuantity` will return a decimal representation instead of a fraction or mixed number since the matching algorithm will be stricter. An higher tolerance increases the likelihood that `formatQuantity` will return a fraction or mixed number, but at the risk of arbitrarily matching an incorrect fraction simply because it gets evaluated first (the export `fractionDecimalMatches` defines the order of evaluation).\n\n```js\n// Low tolerance - returns a decimal since 0.333 is not close enough to 1/3\nformatQuantity(0.333, { tolerance: 0.00001 }); // \"0.333\"\n// High tolerance - matches \"1/3\" even for 3/10\nformatQuantity(0.3, { tolerance: 0.1 }); // \"1/3\"\n// *Way* too high tolerance - incorrect result because thirds get evaluated before halves\nformatQuantity(0.5, { tolerance: 0.5 }); // \"1/3\"\n```\n\n### `romanNumerals`\n\n| Type      | Default |\n| --------- | ------: |\n| `boolean` | `false` |\n\nCoerces the number into an integer using `Math.floor`, then formats the value as Roman numerals. The algorithm uses strict, modern rules, so the number must be between 1 and 3999 (inclusive).\n\nWhen this option is `true`, all other options are ignored.\n\n```js\nformatQuantity(1214, { romanNumerals: true }); // \"MCCXIV\"\nformatQuantity(12.14, { romanNumerals: true, vulgarFractions: true }); // \"XII\"\n```\n\n[badge-npm]: https://img.shields.io/npm/v/format-quantity.svg?cacheSeconds=3600\u0026logo=npm\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjakeboone02%2Fformat-quantity","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjakeboone02%2Fformat-quantity","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjakeboone02%2Fformat-quantity/lists"}