Registry / productivity / format-quantity

format-quantity

library3.1.0jsnpmunverified

Format numbers as imperial measurement strings with vulgar fractions, mixed numbers, and Roman numerals. Current stable version is 3.1.0, released on npm with a Node.js >=16 requirement. It ships TypeScript types and is actively maintained. Key differentiators: supports vulgar fraction characters (e.g., '⅞'), mixed number parsing via numeric-quantity, and options like fractionSlash (using Unicode fraction slash) and custom separator. Intended for recipe ingredient formatting where empty string is returned for zero. Alternative to manual fraction conversion; inverse operation available in numeric-quantity package.

productivity

npm install format-quantity

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · FORMAT-QUANTITY

format-quantity

productivityjavascriptv3.1.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

formatQuantity

✓ import { formatQuantity } from 'format-quantity'

✗ import formatQuantity from 'format-quantity'

This is a named export (not default). Since v3, the package is ESM-only. For CommonJS, use dynamic import or the UMD build.

FormatQuantity (global)

✓ <script src="https://unpkg.com/format-quantity"></script> <script> FormatQuantity.formatQuantity(1.5); </script>

✗ window.formatQuantity(1.5)

When using UMD via script tag, the library exposes a global 'FormatQuantity' object. All exports are properties of that object.

formatQuantity (CDN ESM)

✓ import { formatQuantity } from 'https://cdn.jsdelivr.net/npm/format-quantity/+esm'

✗ import { formatQuantity } from 'https://cdn.jsdelivr.net/npm/format-quantity'

For CDN usage as ESM, you must use the +esm endpoint. Without it, you'll get a CommonJS bundle that can't be imported as ESM.

Demonstrates basic formatting, vulgar fractions, fraction slash, custom separator, zero handling, invalid input, and string parsing including mixed numbers and comma separators.

import { formatQuantity } from 'format-quantity'; // Basic usage console.log(formatQuantity(1.5)); // "1 1/2" console.log(formatQuantity(2.66)); // "2 2/3" // With vulgar fractions console.log(formatQuantity(3.875, true)); // "3⅞" console.log(formatQuantity(0.5, { vulgarFractions: true })); // "½" // Fraction slash option console.log(formatQuantity(3.875, { fractionSlash: true })); // "3 ⁷⁄₈" // Custom separator console.log(formatQuantity(1.5, { separator: '-' })); // "1-1/2" // Returns empty string for zero console.log(formatQuantity(0)); // "" // Returns null for invalid input console.log(formatQuantity('not a number')); // null // Accepts string inputs (parsed by numeric-quantity) console.log(formatQuantity('1 1/2')); // "1 1/2" console.log(formatQuantity('½')); // "½" console.log(formatQuantity('1,000.5')); // "1000 1/2"

Debug

Known issues

breakingESM-only since v3 - CommonJS require() will not work

fix

Use dynamic import() or switch to ESM: import { formatQuantity } from 'format-quantity'

affects: >=3.0.0

gotchaformatQuantity(0) returns empty string, not '0'

fix

If you need '0' output, handle it separately: formatQuantity(n) || '0'

affects: all

gotchaInvalid input returns null, not undefined

fix

Check for null return value explicitly: const result = formatQuantity(val); if (result === null) { /* handle error */ }

affects: all

gotchavulgarFractions option is ignored for fractions with denominator 16 (no standard character exists)

fix

Use fractionSlash option for sixteenths if you need Unicode fraction display

affects: all

deprecatedPassing a boolean as second argument is equivalent to { vulgarFractions: true }, but the object syntax is preferred

fix

Use options object: formatQuantity(3.875, { vulgarFractions: true })

affects: >=3.0.0

Errors

Common errors & fixes

SyntaxError: Named export 'formatQuantity' not found. The requested module 'format-quantity' is a CommonJS module...

Trying to import named exports from a CommonJS version of the package using static ESM import.

fix

Install v3+ (ESM) or use dynamic import: const { formatQuantity } = await import('format-quantity');

TypeError: formatQuantity is not a function

Imported the default export incorrectly. The package exports a named function, not a default.

fix

Use named import: import { formatQuantity } from 'format-quantity';

Uncaught ReferenceError: FormatQuantity is not defined

Using UMD build but script didn't load or globals are not as expected.

fix

Ensure the script tag loads before your code, and use FormatQuantity.formatQuantity() (note capital F).

Cannot find module 'format-quantity' or its corresponding type declarations.

Package not installed or TypeScript cannot locate types (should be auto-included for v3+).

fix

Run 'npm install format-quantity' and ensure tsconfig.json includes node modules. If still failing, check node_modules/@types/format-quantity doesn't exist (types are bundled).

Expected '1 1/2' but got '1.5' - fraction not formatted

The function returned a string representation of the input but not as imperial fraction (maybe input was not recognized).

fix

Pass a number or parsable string; check that numeric-quantity is installed (peer dependency).

Upgrade

Version history

3.1.0latest on npm

Audit

Dependencies

numeric-quantityrequiredParses string inputs like mixed numbers, vulgar fractions, and comma-separated numbers into numeric values for formatting.

Agent activity

21 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/jakeboone02/format-quantity ↗

packageformat-quantity ↗

homepagehttps://github.com/jakeboone02/format-quantity ↗