API Reference

This page provides a detailed reference for the Numeral.js public API.

Global Namespace (numeral)

These functions and properties are available on the global numeral object.

numeral(input)

Creates a new Numeral instance. The input can be a Number, String, or another Numeral object.

  • input: The value to wrap.
  • Returns: A Numeral instance.
var n1 = numeral(100);
var n2 = numeral('1,234.56');
var n3 = numeral(null);

numeral.version

The current version of the library.

  • Returns: String
console.log(numeral.version); // '2.0.6'

numeral.isNumeral(object)

Checks if a variable is a Numeral instance.

  • object: The variable to check.
  • Returns: Boolean
numeral.isNumeral(numeral(100)); // true
numeral.isNumeral(100); // false

numeral.locale([key])

Sets or gets the current global locale.

  • key (optional): A string for the locale to set (e.g., 'fr').
  • Returns: The current locale key as a String.
numeral.locale('fr'); // Sets locale to French
console.log(numeral.locale()); // 'fr'

numeral.localeData([key])

Retrieves the definition object for a locale.

  • key (optional): The key for the locale to retrieve. If omitted, returns the current locale's data.
  • Returns: Object containing locale rules.
var data = numeral.localeData('en'); // { delimiters: { ... }, ... }

numeral.register(type, name, definition)

Registers a new format or locale.

  • type: String - Either 'locale' or 'format'.
  • name: String - The name/key for the new item.
  • definition: Object - The definition object for the locale or format.

numeral.reset()

Resets all global configuration options to their defaults.

numeral.defaultFormat(format)

Sets the default format string to use when .format() is called without arguments.

  • format: String - The format string.

numeral.zeroFormat(format)

Sets a custom format for the number 0.

  • format: String - The string to return when formatting 0.

numeral.nullFormat(format)

Sets a custom format for null values.

  • format: String - The string to return when formatting null.

numeral.validate(value, culture)

Validates if a string is a valid number based on the rules of a given locale.

  • value: String - The string to validate.
  • culture: String - The locale key to use for validation.
  • Returns: Boolean

Numeral Instances (numeral()...)

These methods are available on Numeral instances.

.clone()

Creates a new Numeral instance with the same value.

  • Returns: a new Numeral instance.

.format(formatString, [roundingFunction])

Formats the number into a string.

  • formatString (optional): The format to use. Defaults to numeral.defaultFormat().
  • roundingFunction (optional): A function to use for rounding (e.g., Math.floor). Defaults to Math.round.
  • Returns: String

.value()

Returns the raw numeric value.

  • Returns: Number or null.

.input()

Returns the original input value passed to the constructor.

  • Returns: Number or String

.set(value)

Sets the internal value of the instance.

  • value: Number - The new value.
  • Returns: The Numeral instance for chaining.

.add(value)

Adds a value.

  • value: Number - The value to add.
  • Returns: The Numeral instance for chaining.

.subtract(value)

Subtracts a value.

  • value: Number - The value to subtract.
  • Returns: The Numeral instance for chaining.

.multiply(value)

Multiplies by a value.

  • value: Number - The value to multiply by.
  • Returns: The Numeral instance for chaining.

.divide(value)

Divides by a value.

  • value: Number - The value to divide by.
  • Returns: The Numeral instance for chaining.

.difference(value)

Calculates the absolute difference.

  • value: Number - The value to compare against.
  • Returns: Number (the absolute difference).