docs: update README (#330)

cchanxzy · Dec 29, 2023 · 6aa5216 · 6aa5216
1 parent 631a986
commit 6aa5216
Show file tree

Hide file tree

Showing 2 changed files with 60 additions and 4 deletions.
diff --git a/README.md b/README.md
@@ -1,13 +1,18 @@
 # React Currency Input Field Component
 
-[![npm](https://img.shields.io/npm/v/react-currency-input-field)](https://www.npmjs.com/package/react-currency-input-field) [![NPM](https://img.shields.io/npm/l/react-currency-input-field)](https://www.npmjs.com/package/react-currency-input-field) [![Codecov Coverage](https://img.shields.io/codecov/c/github/cchanxzy/react-currency-input-field)](https://codecov.io/gh/cchanxzy/react-currency-input-field/) [![Release build](https://github.com/cchanxzy/react-currency-input-field/workflows/Release/badge.svg)](https://github.com/cchanxzy/react-currency-input-field/actions?query=workflow%3ARelease)
+[![npm](https://img.shields.io/npm/v/react-currency-input-field)](https://www.npmjs.com/package/react-currency-input-field) [![npm](https://img.shields.io/npm/dm/react-currency-input-field)](https://www.npmjs.com/package/react-currency-input-field)
+[![NPM](https://img.shields.io/npm/l/react-currency-input-field)](https://www.npmjs.com/package/react-currency-input-field) [![Codecov Coverage](https://img.shields.io/codecov/c/github/cchanxzy/react-currency-input-field)](https://codecov.io/gh/cchanxzy/react-currency-input-field/) [![Release build](https://github.com/cchanxzy/react-currency-input-field/workflows/Release/badge.svg)](https://github.com/cchanxzy/react-currency-input-field/actions?query=workflow%3ARelease)
 
 - [React Currency Input Field Component](#react-currency-input-field-component)
   - [Features](#features)
   - [Examples](#examples)
   - [Install](#install)
   - [Usage](#usage)
   - [Props](#props)
+    - [onValueChange](#onvaluechange)
+      - [value](#value)
+      - [name](#name)
+      - [values](#values)
     - [Abbreviations](#abbreviations)
     - [Prefix and Suffix](#prefix-and-suffix)
     - [Separators](#separators)
@@ -58,7 +63,7 @@ import CurrencyInput from 'react-currency-input-field';
   placeholder="Please enter a number"
   defaultValue={1000}
   decimalsLimit={2}
-  onValueChange={(value, name) => console.log(value, name)}
+  onValueChange={(value, name, values) => console.log(value, name, values)}
 />;
 ```
 
@@ -72,7 +77,7 @@ Have a look in [`src/examples`](https://github.com/cchanxzy/react-currency-input
 | allowNegativeValue                                 | `boolean`  | `true`         | Allow user to enter negative value                                                             |
 | defaultValue                                       | `number`   |                | Default value                                                                                  |
 | value                                              | `number`   |                | Programmatically set the value                                                                 |
-| onValueChange                                      | `function` |                | Handle change in value                                                                         |
+| [onValueChange](#onvaluechange)                    | `function` |                | Handle change in value                                                                         |
 | placeholder                                        | `string`   |                | Placeholder if no value                                                                        |
 | [decimalsLimit](#decimal-scale-and-decimals-limit) | `number`   | `2`            | Limit length of decimals allowed                                                               |
 | [decimalScale](#decimal-scale-and-decimals-limit)  | `number`   |                | Specify decimal scale for padding/trimming eg. 1.5 -> 1.50 or 1.234 -> 1.23 if decimal scale 2 |
@@ -89,6 +94,32 @@ Have a look in [`src/examples`](https://github.com/cchanxzy/react-currency-input
 | step                                               | `number`   |                | Incremental value change on arrow down and arrow up key press                                  |
 | transformRawValue                                  | `function` |                | Transform the raw value from the input before parsing. Needs to return `string`.               |
 
+### onValueChange
+
+Handle changes to the value.
+
+```js
+onValueChange = (value, name, values) => void;
+```
+
+#### value
+
+`value` will give you the value in a string format, without the prefix/suffix/separators.
+
+Example: `£123,456 -> 123456`
+
+#### name
+
+`name` is the name you have passed to your component
+
+#### values
+
+`values` gives an object with three key values:
+
+- `float`: Value as float or null if empty. Example: "1.99" > 1.99
+- `formatted`: Value after applying formatting. Example: "1000000" > "1,000,0000"
+- `value`: Non formatted value as string, ie. same as first param.
+
 ### Abbreviations
 
 It can parse values with abbreviations `k`, `m` and `b`

diff --git a/src/examples/index.html b/src/examples/index.html
@@ -16,6 +16,18 @@
       <div class="row">
         <div class="col mb-3">
           <h1>React Currency Input Field</h1>
+          <a
+            href="https://www.npmjs.com/package/react-currency-input-field"
+            target="_blank"
+            rel="noreferrer"
+            ><img alt="npm" src="https://img.shields.io/npm/v/react-currency-input-field"
+          /></a>
+          <a
+            href="https://www.npmjs.com/package/react-currency-input-field"
+            target="_blank"
+            rel="noreferrer"
+            ><img alt="npm" src="https://img.shields.io/npm/dm/react-currency-input-field"
+          /></a>
         </div>
       </div>
       <div class="row">
@@ -31,9 +43,22 @@ <h1>React Currency Input Field</h1>
             <li>Written in TypeScript and has type support</li>
             <li>Does not use any third party packages</li>
           </ul>
+          <p>
+            See the
+            <a
+              href="https://github.com/cchanxzy/react-currency-input-field/"
+              target="_blank"
+              rel="noreferrer"
+              >README</a
+            >
+            for full documentation.
+          </p>
           <p>
             Please visit the
-            <a href="https://github.com/cchanxzy/react-currency-input-field/tree/main/src/examples"
+            <a
+              href="https://github.com/cchanxzy/react-currency-input-field/tree/main/src/examples"
+              target="_blank"
+              rel="noreferrer"
               >Github repository</a
             >
             to see the source code from examples.