Skip to content

v2.0 documentation

Documentation for v2 (⚠ DEPRECATED)

Disclaimer 1: v1.9 has been superseeded by v4.* and is not longer supported. Please consider switching to the latest version.

Disclaimer 2: This documentation may be outdated.
Please consider using the Readme that always has up-to-date information.

List of methods and settings

The following is an uncomplete list of the methods and settings/options that control autoNumeric 2.0.*:

'init'
initializes autoNumeric Must be run before other methods can be called
  • $('someSelector').autoNumeric();
  • $('someSelector').autoNumeric('init');
  • $('someSelector').autoNumeric({options});
  • $('someSelector').autoNumeric('init', {options});
'destroy'
stops autoNumeric and removes jQuery data
  • $('someSelector').autoNumeric('destroy');
'wipe'
removes session storage and cookies from memory - only needed if the 'aStor' option is true - $(someSelector).autoNumeric('wipe');
'update'
updates autoNumeric's settings
  • $('someSelector').autoNumeric('update', {options});
  • Can be run multiple times
  • Overrides the default settings and HTML5 data
'set'
returns a formatted string via jQuery's ".val()" or ".text' methods to the selected tag(s)
  • $('someSelector').autoNumeric('set', value); // see
'unSet'
method to un-format inputs - handy to use right before form submission
  • $(someSelector).autoNumeric('unSet'); // returns "nnnn.nn" or "-nnnn.nn"
  • $(someSelector).autoNumeric('unSet', '.-'); // returns "nnnn.nn" or "nnnn.nn-" // trailing negative sign
  • $(someSelector).autoNumeric('unSet', ','); // returns "nnnn,nn" or "-nnnn,nn" // comma as decimal seperator
  • $(someSelector).autoNumeric('unSet', ',-'); // returns "nnnn,nn" or "nnnn,nn-" // comma as decimal separator & trailing negative sign
'reSet'
method to re-format inputs - handy to use right after form submission
  • $(someSelector).autoNumeric('reSet');
'get'
allows you to easily remove the formatting from a string on a autoNumeric controlled element and returns a string
  • $(someSelector).autoNumeric('get'); // returns "nnnn.nn" or "-nnnn.nn"
  • $(someSelector).autoNumeric('get', '.-'); // returns "nnnn.nn" or "nnnn.nn-" // trailing negative sign
  • $(someSelector).autoNumeric('get', ','); // returns "nnnn,nn" or "-nnnn,nn" // comma as decimal seperator
  • $(someSelector).autoNumeric('get', ',-'); // returns "nnnn,nn" or "nnnn,nn-" // comma as decimal separator & trailing negative sign
'getString'
this basically uses jQuery's .serialize() method which creates a text string (URL-encoded notation) from a set of form elements that is ready for submission. The extra step taken here is the string is split and iterated through and the formatted values are replaced with unformatted values. The string is then joined back together and returned
  • $(someSelector).autoNumeric('getString'); // returns "nnnn.nn" or "-nnnn.nn"
  • $(someSelector).autoNumeric('getString', '.-'); // returns "nnnn.nn" or "nnnn.nn-" // trailing negative sign
  • $(someSelector).autoNumeric('getString', ','); // returns "nnnn,nn" or "-nnnn,nn" // comma as decimal seperator
  • $(someSelector).autoNumeric('getString', ',-'); // returns "nnnn,nn" or "nnnn,nn-" // comma as decimal separator & trailing negative sign
'getArray'
this basically uses jQuery's .serializeArray() method which returns a JavaScript array of objects, ready to be encoded as a JSON string. Again autoNumeric iterated through the array object and replaces the formatted values with unformatted values.
  • $(someSelector).autoNumeric('getArray'); // returns "nnnn.nn" or "-nnnn.nn"
  • $(someSelector).autoNumeric('getArray', '.-'); // returns "nnnn.nn" or "nnnn.nn-" // trailing negative sign
  • $(someSelector).autoNumeric('getArray', ','); // returns "nnnn,nn" or "-nnnn,nn" // comma as decimal seperator
  • $(someSelector).autoNumeric('getArray', ',-'); // returns "nnnn,nn" or "nnnn,nn-" // comma as decimal separator & trailing negative sign
'getSettings'
this returns an object that shows the autoNumeric settings for the field. You may find this helpful when developing a page
  • $('someSelector').autoNumeric('getSettings'); // returns the jQuery data opbect with settings
  • $('someSelector').autoNumeric('getSettings').decimalCharacter; // returns the 'decimalCharacter' value
  • any individual setting can be returned by replacing decimalCharacter with the desired settings / option name

For more examples, documentation and the option code generator please take a look at http://www.decorplanit.com/plugin/.

New method for formatting and unformatting fields

Additionally, autoNumeric now supports formatting and unformatting directly without having to first initiate a DOM element :

'autoUnformat'
this returns an Number given the formatted string and the autoNumeric options passed as arguments

For instance, to unformat, you would use : 

let autoNumericOptions = { digitGroupSeparator: '.', decimalCharacter: ',', decimalCharacterAlternative: '.', currencySymbol: ' €', currencySymbolPlacement: 's', roundingMethod: 'U' };
let formattedString = "1.234,56 €";
$.fn.autoUnformat(formattedString, autoNumericOptions); // Returns 1234.56

'autoFormat'
this returns a formatted string given a Number and the autoNumeric options passed as arguments

For instance, to format, you would use : 

let autoNumericOptions = { digitGroupSeparator: '.', decimalCharacter: ',', decimalCharacterAlternative: '.', currencySymbol: ' €', currencySymbolPlacement: 's', roundingMethod: 'U' };
let number = 1234.56;
$.fn.autoFormat(number, autoNumericOptions); // Returns "1.234,56 €"

Default settings & supported options

visit autoNumeric's home page for an easy to use settings and option code generator

Disclaimer : This may be outdated. Please refer to the Readme or directly in the detailed comments in the source code for the defaultSettings object.

digitGroupSeparator

controls the thousand separator character - digitGroupSeparator: ',' // Comma - digitGroupSeparator: '.' // Dot - digitGroupSeparator: ' ' // Normal space - digitGroupSeparator: '\u2009' // Thin-space - digitGroupSeparator: '\u202f' // Narrow no-break space - digitGroupSeparator: '\u00a0' // No-break space - digitGroupSeparator: '' // No separator - digitGroupSeparator: "'" // Apostrophe - digitGroupSeparator: '٬' // Arabic thousands separator - digitGroupSeparator: '˙' // Dot above

showOnlyNumbersOnFocus

When true only numbers and the decimal character is visible while the input has focus - showOnlyNumbersOnFocus: false (default) - showOnlyNumbersOnFocus: true removes currency sign and thousand seperator while the input has focus. Help on some mobile devices

digitalGroupSpacing

controls the digital grouping and the placement of the thousand separator - digitalGroupSpacing: '3' produces 333,333,333 (default) - digitalGroupSpacing: '2' produces 22,22,22,333 India's Lakhs - digitalGroupSpacing: '2s' produces 22,333,22,22,333 scaled version of India Lakhs - digitalGroupSpacing: '4' produces 4,4444,4444 used in some Asian country's

decimalCharacter

controls the decimal character - decimalCharacter: ',' // Comma - decimalCharacter: '.' // Dot - decimalCharacter: '·' // Middle-dot - decimalCharacter: '٫' // Arabic decimal separator - decimalCharacter: '⎖' // Decimal separator key symbol

decimalCharacterAlternative

this was developed to accommodate for different keyboard layouts. decimalCharacterAlternative allows you to declare an alternative key to enter the decimal separator assigned in decimalCharacter - decimalCharacterAlternative: null (default)

currencySymbol

displays the desired currency symbol (examples: € or EUR). Note: other symbols can be used, such as %, °C, °F, km/h & MPH the possibilities are endless - currencySymbol: '' none (default) - examples: currencySymbol: 'U$D' or currencySymbol: 'EUR'

currencySymbolPlacement

controls the placement of the currency symbol (prefix or suffix) - currencySymbolPlacement: 'p' prefix to the left (default) - currencySymbolPlacement: 's' suffix to the right

negativePositiveSignPlacement

placement of the negative sign. This position is relative to the currencySymbol position - negativePositiveSignPlacement: 'l' (default) left of currency sign - negativePositiveSignPlacement: 'r' right of currency sign - negativePositiveSignPlacement: 's' suffix places the sign to the right of the numbers - negativePositiveSignPlacement: 'p' prefix places the sign(-) to the felt of the numbers - Examples:

format options to achieve format
-1,234.56 defaults
1,234.56- {negativePositiveSignPlacement: 's'}
-$1,234.56 {currencySymbol: '$'}
$-1,234.56 {currencySymbol: '$', negativePositiveSignPlacement: 'r'}
$1,234.56- {currencySymbol: '$', negativePositiveSignPlacement: 's'}
1,234.56-$ {currencySymbol: '$', currencySymbolPlacement: 's'}
1,234.56$- {currencySymbol: '$', currencySymbolPlacement: 's', negativePositiveSignPlacement: 'r'}
-1,234.56$ {currencySymbol: '$', currencySymbolPlacement: 's', negativePositiveSignPlacement: 'p'}

suffixText

Allows additional text as a suffix - suffixText: '' (default) no suffix defined - suffixText: 'test' example: 123,4.56 test - Numbers and minus sign (-) are not allowed and will cause an error

minimumValue

controls the minimum value allowed - minimumValue: '-9999999999999.99' (default) - Must be set as text - Can be negative or positive but must be less than 'maximumValue'

maximumValue

controls the maximum value allowed - maximumValue: '9999999999999.99' (default) - Must be set as text - Can be positive or negative but must be greater than 'minimumValue'

Note: setting the minimumValue and maximumValue to both positive or negative with situations that limits the users ability to enter the proper values

decimalPlacesOverride

Note: This has been deprecated in v4 overrides the decimal places that that are set via the minimumValue/maximumValue values - decimalPlacesOverride: null (default method) - decimalPlacesOverride: '4' overides the default and allows 4 decimal places

roundingMethod

sets the rounding method used (12 different available - case sensitive)

option Rounding method
'S' Round-Half-Up Symmetric (default)
'A' Round-Half-Up Asymmetric
's' Round-Half-Down Symmetric (lower case s)
'a' Round-Half-Down Asymmetric (lower case a)
'B' Round-Half-Even "Bankers Rounding"
'U' Round Up "Round-Away-From-Zero"
'D' Round Down "Round-Toward-Zero" - same as truncate
'C' Round to Ceiling "Toward Positive Infinity"
'F' Round to Floor "Toward Negative Infinity"
'N05' Rounding "to the nearest .00 or .05"
'U05' Rounds up to next .00 or .05
'D05' Rounds down to next .00 or .05

allowDecimalPadding

controls padding of the decimal places - allowDecimalPadding: true always pads the decimal with zeros (default) - allowDecimalPadding: false no padding

negativeBracketsTypeOnBlur

controls if negative values are display with brackets when the input does not have focus - negativeBracketsTypeOnBlur: null no brackets use for negative values (default) - negativeBracketsTypeOnBlur: '(,)' - negativeBracketsTypeOnBlur: '[,]' - negativeBracketsTypeOnBlur: '{,}' - negativeBracketsTypeOnBlur: '<,>'

emptyInputBehavior

controls input currency sign display behavior when the input does not have a value '' - emptyInputBehavior: 'focus' (default) the currency symbol will be displayed on focus - emptyInputBehavior: 'press' currency symbol will not be displayed until the first key is pressed - emptyInputBehavior: 'always' currency symbol is always displayed with or without a value

leadingZero

controls leading zeros behavior - leadingZero: 'allow' allows leading zero to be entered. They are removed on focusout event (default) - leadingZero: 'deny' leading zeros not allowed. - leadingZero: 'keep' leading zeros allowed and will be retained on the focusout event

selectNumberOnly

controls the 'alt' & 'a' select key combination - selectNumberOnly: false (default) selects all characters within the input - selectNumberOnly: true selects only the numbers - note: if the currency symbol is between the numeric value and the negative sign only the numeric characters will be selected

formatOnPageLoad

controls if default values are formatted on page ready (load) - formatOnPageLoad: true default values are formatted on page ready (default) - formatOnPageLoad: false default values are NOT formatted on page ready

defaultValueOverride

helper option for ASP.NET post-back - should be the value of the un-formatted default value - this can be set as an option when initializing autoNumeric or as HTML5 data - examples: - no default value='' {defaultValueOverride: ''} - value=1234.56 {defaultValueOverride: '1234.56'}

unformatOnSubmit

removes the format on the submit event - unformatOnSubmit: false (default) does not remove the formatting - unformatOnSubmit: true - removes the formatting on the submit event - this can be done globally via the extend method or by elemnt via the jQuery selector - output is always "nnnn.nn" or negative "-nnnn.nn". n = 0-9

showWarnings

error handling function - showWarnings: true - (default) throws errors - helpful during developing. - showWarnings: false - stops most errors from being thrown.