README
react-number-format
React component to format number in an input or as a text
Features
- Prefix, suffix and thousand separator.
- Custom format pattern.
- Masking.
- Custom formatting handler.
- Format number in an input or format as a simple text.
Live demo example
Install
Through npm
npm install react-number-format --save
Or get compiled development and production version from ./dist
Usage
ES6
import NumberFormat from 'react-number-format';
ES5
const NumberFormat = require('react-number-format');
Typescript
import NumberFormat from 'react-number-format';
//or
import { default as NumberFormat } from 'react-number-format';
In typescript you also have to enable "esModuleInterop": true
in your tsconfig.json (https://www.typescriptlang.org/docs/handbook/compiler-options.html).
Props
Props | Options | Default | Description |
---|---|---|---|
thousandSeparator | mixed: single character string or boolean true (true is default to ,) | none | Add thousand separators on number. Demo |
decimalSeparator | single character string | . | Support decimal point on a number. Demo |
thousandsGroupStyle | One of ['thousand', 'lakh', 'wan'] | thousand | Define the thousand grouping style, It support three types. thousand style (thousand) : 123,456,789 , indian style (lakh) : 12,34,56,789 , chinese style (wan) : 1,2345,6789 . Demo |
decimalScale | number | none | If defined it limits to given decimal scale. Demo |
fixedDecimalScale | boolean | false | If true it add 0s to match given decimalScale. Demo |
allowNegative | boolean | true | allow negative numbers (Only when format option is not provided). Demo |
allowEmptyFormatting | boolean | false | Apply formatting to empty inputs. Demo |
allowLeadingZeros | boolean | false | Allow leading zeros at beginning of number. Demo |
prefix | String (ex : $) | none | Add a prefix before the number. Demo |
suffix | String (ex : /-) | none | Add a suffix after the number. Demo |
value | Number or String | null | Value to the number format. It can be a float number, or formatted string. If value is string representation of number (unformatted), isNumericString props should be passed as true. Demo. |
defaultValue | Number or String | null | Value to be used as default value if value is not provided. The format of defaultValue should be similar as defined for the value. Demo. |
isNumericString | boolean | false | If value is passed as string representation of numbers (unformatted) then this should be passed as true. Demo |
displayType | String: text / input | input | If input it renders a input element where formatting happens as you input characters. If text it renders it as a normal text in a span formatting the given value. Demo |
type | One of ['text', 'tel', 'password'] | text | Input type attribute. Demo |
format | String : Hash based ex (#### #### #### ####) Or Function |
none | If format given as hash string allow number input inplace of hash. If format given as function, component calls the function with unformatted number and expects formatted number. Demo |
removeFormatting | (formattedValue) => numericString | none | If you are providing custom format method and it add numbers as format you will need to add custom removeFormatting logic. Demo |
mask | String (ex : _) | ' ' |
If mask defined, component will show non entered placed with masked value. Demo |
customInput | Component Reference | input | This allow supporting custom inputs with number format. |
onValueChange | (values, sourceInfo) => {} | none | onValueChange handler accepts values object. Demo |
isAllowed | (values) => true or false | none | A checker function to check if input value is valid or not. If this function returns false, the onChange method will not get triggered. Demo |
renderText | (formattedValue, customProps) => React Element | null | A renderText method useful if you want to render formattedValue in different element other than span. It also returns the custom props that are added to the component which can allow passing down props to the rendered element. Demo |
getInputRef | (elm) => void | null | Method to get reference of input, span (based on displayType prop) or the customInput's reference. See Getting reference. Demo |
allowedDecimalSeparators | array of char | none | Characters which when pressed result in a decimal separator. When missing, decimal separator and '.' are used. |
customNumerals | array of string | none | an array of 10 single-character strings with represent numerals in different locales. ranging from 0 - 9. the result will be converted to english numeral and treated as number |
Other than this it accepts all the props which can be given to a input or span based on displayType you selected.
values object
values object is on following format
{
formattedValue: '$23,234,235.56', //value after applying formatting
value: '23234235.56', //non formatted value as numeric string 23234235.56, if you are setting this value to state make sure to pass isNumericString prop to true
floatValue: 23234235.56 //floating point representation. For big numbers it can have exponential syntax
}
Its recommended to use formattedValue / value / floatValue based on the initial state (it should be same as the initial state format) which you are passing as value prop. If you are saving the value
key on state make sure to pass isNumericString prop to true.
Notes and quirks
Value can be passed as string or number, but if it is passed as string it should be either formatted value or if it is a numeric string, you have to set isNumericString props to true.
Value as prop will be rounded to given decimal scale if format option is not provided.
If you want to block floating number set decimalScale to 0.
Use type as tel when you are providing format prop. This will change the mobile keyboard layout to have only numbers. In other case use type as text, so user can type decimal separator.
onChange no longer gets values object. You need to use onValueChange instead. onChange/onFocus/onBlur and other input events will be directly passed to the input.
Its recommended to use formattedValue / value / floatValue based on the initial state (it should be same as the initial state format) which you are passing as value prop. If you are saving the
value
key on state make sure to pass isNumericString prop to true.onValueChange is not same as onChange. It gets called on whenever there is change in value which can be caused by any event like change or blur event or by a prop change. It also provides a second argument which contains the event object and the reason for this function trigger.
Examples
Demo
Prefix and thousand separator : Format currency as text.var NumberFormat = require('react-number-format');
<NumberFormat value={2456981} displayType={'text'} thousandSeparator={true} prefix={'