### Install v-money3

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/00-START-HERE.md

Install the v-money3 package using npm.

```bash
npm install v-money3
```

--------------------------------

### Install v-money3 with npm

Source: https://github.com/jonathanpmartins/v-money3/blob/main/README.md

Install the v-money3 package using npm. Requires vue version 3.2.0 or higher.

```bash
npm i v-money3 --save
```

--------------------------------

### TypeScript Configuration Example

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/QUICK-REFERENCE.md

Demonstrates how to import and use v-money3 types in TypeScript for defining currency formatting options.

```typescript
import {
  Money3Component,
  type VMoneyOptions
} from 'v-money3';

const config: Partial<VMoneyOptions> = {
  prefix: '$',
  precision: 2,
};
```

--------------------------------

### Complete VMoney Configuration

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/configuration.md

This example shows all available configuration options for VMoney, demonstrating how to customize formatting, display, constraints, and other behaviors.

```typescript
const fullConfig = {
  // Formatting
  precision: 2,
  decimal: ',',
  thousands: '.',
  prefix: 'R$ ',
  suffix: '',
  
  // Display
  masked: false,
  focusOnRight: false,
  minimumNumberOfCharacters: 0,
  
  // Constraints
  min: 0,
  max: 10000,
  setMaxIfBigger: true,
  disableNegative: false,
  
  // Blank/Zero handling
  allowBlank: false,
  treatZeroAsBlank: true,
  
  // Rounding
  shouldRound: true,
  
  // Other
  debug: false,
  disabled: false,
  modelModifiers: { number: false },
  lazy: true,
};
```

--------------------------------

### Full Configuration with Defaults

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/configuration.md

This example shows how to create a full configuration by spreading the default options and then overriding specific values. This is useful when you want to modify only a few settings while keeping most defaults.

```typescript
// Full config
{ ...defaults, precision: 2, prefix: '$' }
```

--------------------------------

### Install v-money3 via yarn

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/installation-and-setup.md

Use yarn to add v-money3 to your project dependencies.

```bash
yarn add v-money3
```

--------------------------------

### CommonJS Usage Example for v-money3

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/installation-and-setup.md

Demonstrates how to use v-money3 with CommonJS, utilizing the UMD build for formatting currency values.

```javascript
const { Money3Component, format } = require('v-money3');

const display = format(1234.56, { precision: 2, prefix: '$' });
```

--------------------------------

### Complete v-money3 TypeScript Example with Vue

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/installation-and-setup.md

A full example demonstrating v-money3 integration within a Vue.js application using TypeScript. Includes component import, state management, and template usage.

```vue
<script lang="ts" setup>
import { Money3Component, type VMoneyOptions } from 'v-money3';
import { ref } from 'vue';

interface AppState {
  amount: string;
  config: Partial<VMoneyOptions>;
}

const state: AppState = {
  amount: '1234.56',
  config: {
    prefix: 'R$ ',
    thousands: '.',
    decimal: ',',
    precision: 2,
  },
};

const amount = ref<string>(state.amount);
const config = ref<Partial<VMoneyOptions>>(state.config);
</script>

<template>
  <money3 v-model="amount" v-bind="config" />
</template>
```

--------------------------------

### Install v-money3 via pnpm

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/installation-and-setup.md

Use pnpm to add v-money3 to your project dependencies.

```bash
pnpm add v-money3
```

--------------------------------

### Component Usage Example

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/QUICK-REFERENCE.md

Use the v-money3 component to format currency input with various options.

```vue
<money3 
  v-model="amount"
  :precision="2"
  prefix="$"
  thousands=","
  decimal="."
/>
```

--------------------------------

### Webpack Configuration Example

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/installation-and-setup.md

A basic webpack configuration file. No special configuration is needed for v-money3 as webpack automatically respects the 'exports' field.

```javascript
// webpack.config.js
module.exports = {
  entry: './src/main.ts',
  module: {
    rules: [
      {
        test: /\.ts$/,
        use: 'ts-loader',
      },
      {
        test: /\.vue$/,
        use: 'vue-loader',
      },
    ],
  },
};
```

--------------------------------

### Minimal VMoney Configuration

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/configuration.md

This example demonstrates a minimal configuration for VMoney, specifying only the essential options like precision and prefix. It assumes other options will use their default values.

```typescript
// Minimal config
{ precision: 2, prefix: '$' }
```

--------------------------------

### Component Only Setup

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/QUICK-REFERENCE.md

Register the Money3Component for use within specific components.

```typescript
import { Money3Component } from 'v-money3';
app.component('money3', Money3Component);
```

--------------------------------

### BigNumber Constructor Examples

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/types.md

Demonstrates how to instantiate the BigNumber class using different valid input types: bigint, number, and string.

```typescript
import BigNumber from 'v-money3';

new BigNumber(12345n);        // bigint
new BigNumber(12345.67);      // number
new BigNumber('12345.67');    // string
```

--------------------------------

### Import and Configure v-money3 with TypeScript

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/README.md

Demonstrates how to import necessary components and types from v-money3 and configure formatting options using TypeScript. This setup is useful for applying custom currency formatting rules.

```typescript
import {
  Money3Component,
  Money3Directive,
  format,
  unformat,
  BigNumber,
  type VMoneyOptions
} from 'v-money3';

const config: Partial<VMoneyOptions> = {
  prefix: 'R$ ',
  thousands: '.',
  decimal: ',',
  precision: 2,
};

const formatted: string = format(12345.67, config as VMoneyOptions);
```

--------------------------------

### Global Plugin Setup

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/QUICK-REFERENCE.md

Register v-money3 as a global plugin for your Vue application.

```typescript
import money from 'v-money3';
app.use(money);
```

--------------------------------

### Configure Large Number Input (Crypto)

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/README.md

Adapt the library for large numbers, such as cryptocurrency values like Bitcoin. This example sets a suffix and specifies a high precision for decimal places.

```javascript
const config = {
  suffix: ' BTC',
  precision: 8,  // 8 decimal places for satoshis
};
```

--------------------------------

### Directive Only Setup

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/QUICK-REFERENCE.md

Register the Money3Directive for use with input elements.

```typescript
import { Money3Directive } from 'v-money3';
app.directive('money3', Money3Directive);
```

--------------------------------

### Directive Usage Example

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/QUICK-REFERENCE.md

Apply the v-money3 directive to an input element for currency formatting.

```html
<input 
  v-model.lazy="amount"
  v-money3="{ precision: 2, prefix: '$' }"
/>
```

--------------------------------

### v-money3 Entry Point Exports

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/module-structure.md

The main export from v-money3 includes the default plugin install function for Vue applications and various named exports for components, directives, and utility functions. This snippet shows the structure of the main entry file.

```typescript
// src/index.ts

export default {
  install(app: App): void {
    app.component('money3', Money3Component);
    app.directive('money3', Money3Directive);
  },
};

export type { VMoneyOptions };
export {
  Money3Component,
  Money3Directive,
  format,
  unformat,
  BigNumber,
  // backwards compatibility aliases
  Money3Component as Money3,
  Money3Directive as VMoney3,
  Money3Component as Money,
  Money3Directive as VMoney,
};
```

--------------------------------

### Integrate v-money3 with UI Frameworks

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/QUICK-REFERENCE.md

Examples of using the v-money3 directive with wrapper components from popular UI libraries like Vuetify, Nuxt UI, and Element Plus.

```html
<!-- Vuetify -->
<v-text-field v-money3="config" v-model.lazy="amount" />

<!-- Nuxt UI -->
<UInput v-money3="config" v-model.lazy="amount" />

<!-- Element Plus -->
<el-input v-money3="config" v-model.lazy="amount" />
```

--------------------------------

### Nuxt 3 Plugin Setup in nuxt.config.ts

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/installation-and-setup.md

Configure your Nuxt 3 application to use v-money3 by adding the plugin to your nuxt.config.ts file.

```typescript
export default defineNuxtConfig({
  modules: [],
  plugins: ['~/plugins/v-money3.ts'],
});
```

--------------------------------

### Vue Form Integration with v-money3 Component

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/QUICK-REFERENCE.md

Shows a complete Vue.js form example using the v-money3 component for input, including submission handling. The form data's price will be a numeric string upon submission.

```vue
<template>
  <form @submit.prevent="handleSubmit">
    <money3 
      v-model="formData.price"
      :precision="2"
      prefix="$"
      required
    />
    <button type="submit">Save</button>
  </form>
</template>

<script setup>
import { Money3Component } from 'v-money3';
import { ref } from 'vue';

const formData = ref({
  price: '0.00'
});

function handleSubmit() {
  // formData.price contains numeric string like '1234.56'
  console.log(parseFloat(formData.price));
}
</script>
```

--------------------------------

### Usage with format() and unformat()

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/types.md

Demonstrates configuring and using the `format` and `unformat` functions with custom options. Ensure the configuration object is cast to `VMoneyOptions` when passed to these functions.

```typescript
import { format, unformat, type VMoneyOptions } from 'v-money3';

const config: Partial<VMoneyOptions> = {
  prefix: 'R$ ',
  thousands: '.',
  decimal: ',',
  precision: 2,
};

const formatted: string = format(12345.67, config as VMoneyOptions);
const unformatted: string | number = unformat(formatted, config as VMoneyOptions);
```

--------------------------------

### Configure Percentage Formatting

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/QUICK-REFERENCE.md

Set up v-money3 for percentage values with a suffix, specific precision, and constraints to prevent negative numbers and enforce a 0-100 range.

```javascript
const config = {
  suffix: ' %',
  precision: 1,
  disableNegative: true,
  min: 0,
  max: 100,
};
```

--------------------------------

### Get Decimal Precision

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/api-reference-bignumber-class.md

Returns the current number of decimal places stored in the BigNumber instance.

```typescript
const bn = new BigNumber('123.45');
console.log(bn.getDecimalPrecision()); // 2
```

--------------------------------

### Import and Configure v-money3

Source: https://github.com/jonathanpmartins/v-money3/blob/main/README.md

Import necessary components and helpers from v-money3. Configure formatting options like prefix, decimal, thousands separators, and precision.

```typescript
import {
  Money3Component,
  Money3Directive,
  format,
  unformat,
  type VMoneyOptions,
} from 'v-money3';

const config: Partial<VMoneyOptions> = {
  prefix: 'R$ ',
  decimal: ',',
  thousands: '.',
  precision: 2,
};

const display: string = format(12345.67, config as VMoneyOptions);
```

--------------------------------

### Get Underlying BigInt Value

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/api-reference-bignumber-class.md

Retrieves the raw BigInt value of the BigNumber instance. The decimal position is managed separately.

```typescript
const bn = new BigNumber('123.45');
console.log(bn.getNumber()); // 12345n (decimal position tracked separately)
```

--------------------------------

### Applying Min/Max Constraints with format()

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/api-reference-format-function.md

Illustrates using the format function with minimum and maximum value constraints. Values outside these bounds are clamped to the nearest boundary.

```typescript
const config = {
  prefix: '$',
  precision: 2,
  min: 0,
  max: 1000,
};

const result = format(2000, config);
// result: '$1,000.00' (clamped to max)
```

--------------------------------

### Basic Usage of format() with Defaults

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/api-reference-format-function.md

Demonstrates the basic usage of the format function with default options. It converts a number into a string with default formatting.

```typescript
import { format } from 'v-money3';

const result = format(12345.67);
// result: '12345.67'
```

--------------------------------

### Configure Decimal Separator

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/configuration.md

Sets the character used as the decimal separator. Cannot contain digits or signs. Examples show US/UK and European styles.

```typescript
// US/UK style
{ decimal: '.' } // 1,234.56

// European style
{ decimal: ',' } // 1.234,56
```

--------------------------------

### Simple Currency Input with v-money3

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/api-reference-money3-directive.md

Use this for basic currency input with a specified precision. Ensure 'v-money3' is imported and registered.

```html
<template>
  <input v-model.lazy="amount" v-money3="{ precision: 2 }" />
  <p>{{ amount }}</p>
</template>

<script setup>
import { Money3Directive } from 'v-money3';
import { ref } from 'vue';

const amount = ref('0.00');
</script>
```

--------------------------------

### Configure Prefix Text

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/configuration.md

Adds text prepended to the numeric value for display. This prefix is automatically removed during parsing. Examples include currency symbols.

```typescript
// US Dollar
{ prefix: '$ ' } // $ 1,234.56

// Brazilian Real
{ prefix: 'R$ ' } // R$ 1.234,56

// No prefix
{ prefix: '' } // 1,234.56
```

--------------------------------

### Include v-money3 UMD build in HTML

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/installation-and-setup.md

Load the v-money3 UMD build directly in your HTML using a script tag. The library will be available as `window.VMoney3`.

```html
<script src="https://unpkg.com/v-money3@latest/dist/v-money3.umd.js"></script>
```

--------------------------------

### package.json Exports for v-money3

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/installation-and-setup.md

Defines the entry points for v-money3, allowing module bundlers to resolve ESM and CommonJS modules correctly.

```json
{
  "exports": {
    ".": {
      "import": "./dist/v-money3.mjs",
      "require": "./dist/v-money3.umd.js"
    }
  }
}
```

--------------------------------

### Basic unformat() Usage

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/api-reference-unformat-function.md

Demonstrates the basic usage of the unformat function to parse a simple numeric string. Requires importing the function from 'v-money3'.

```typescript
import { unformat } from 'v-money3';

const result = unformat('12345.67');
// result: '12345.67'
```

--------------------------------

### Configure Formatting with Min/Max Values

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/QUICK-REFERENCE.md

Configure currency formatting with a minimum and maximum value. The `setMaxIfBigger` option ensures values exceeding the maximum are clamped.

```javascript
const config = {
  prefix: '$',
  precision: 2,
  min: 0,
  max: 10000,
  setMaxIfBigger: true,  // clamp values above max
};
```

--------------------------------

### Brazilian Real Input with Custom Separators

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/api-reference-money3-directive.md

Configure the directive for specific regional formats like Brazilian Real, including custom prefixes, thousands separators, and decimal points. The 'placeholder' attribute is useful for guiding user input.

```html
<template>
  <input 
    v-model.lazy="preco"
    v-money3="config"
    placeholder="R$ 0,00"
  />
</template>

<script setup>
import { Money3Directive } from 'v-money3';
import { ref } from 'vue';

const config = {
  prefix: 'R$ ',
  thousands: '.',
  decimal: ',',
  precision: 2,
};

const preco = ref('0,00');
</script>
```

--------------------------------

### Complete VMoneyOptions Defaults

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/types.md

Shows the full default configuration object for VMoneyOptions, including all available settings.

```typescript
const defaults: VMoneyOptions = {
  debug: false,
  masked: false,
  prefix: '',
  suffix: '',
  thousands: ',',
  decimal: '.',
  precision: 2,
  disableNegative: false,
  disabled: false,
  min: null,
  max: null,
  setMaxIfBigger: true,
  allowBlank: false,
  treatZeroAsBlank: true,
  minimumNumberOfCharacters: 0,
  modelModifiers: {
    number: false,
  },
  shouldRound: true,
  focusOnRight: false,
  lazy: true,
};
```

--------------------------------

### format()

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/QUICK-REFERENCE.md

Formats a given input (string, number, null, or undefined) into a currency string based on the provided VMoneyOptions.

```APIDOC
## format()

### Description
Formats a given input (string, number, null, or undefined) into a currency string based on the provided VMoneyOptions.

### Method
N/A (Function Signature)

### Endpoint
N/A (Library Function)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```typescript
format(input: string | number | null | undefined, options: VMoneyOptions)
```

### Response
#### Success Response
- **string**: The formatted currency string.

#### Response Example
N/A
```

--------------------------------

### Format and Unformat Currency with v-money3

Source: https://github.com/jonathanpmartins/v-money3/blob/main/README.md

Demonstrates using the `format` and `unformat` functions with a custom configuration. The `unformat` function can return a string or a number based on `modelModifiers`.

```javascript
import { format, unformat } from 'v-money3';

const config = {
    masked: false,
    prefix: 'R$ ',
    suffix: ' #',
    thousands: '.',
    decimal: ',',
    precision: 2,
    disableNegative: false,
    disabled: false,
    min: null,
    max: null,
    setMaxIfBigger: true,
    allowBlank: false,
    treatZeroAsBlank: true,
    minimumNumberOfCharacters: 0,
    modelModifiers: {
        number: false,
    },
    shouldRound: true,
    focusOnRight: false,
}

const formatted = format(12345.67, config);
console.log(formatted);
// output string: 'R$ 12.345,67 #'

const unformattedString = unformat(formatted, config);
console.log(unformattedString);
// output fixed string: '12345.67'

/* ----------------- or ----------------- */

config.modelModifiers = { number: true };

const unformattedNumber = unformat(formatted, config);
console.log(unformattedNumber);
// output float number: 12345.67
```

--------------------------------

### V-Money3 Build Output Formats

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/module-structure.md

This snippet lists the different formats the V-Money3 library is built into for distribution, including ESM, UMD, and TypeScript types.

```text
- ESM — dist/v-money3.mjs (for import statements)
- UMD — dist/v-money3.umd.js (for <script> tags and Node.js require)
- Types — dist/index.d.ts (TypeScript declarations)

```

--------------------------------

### Formatting with Currency Symbol and Custom Separators

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/api-reference-format-function.md

Shows how to use the format function with custom configuration for currency symbol, thousands separator, decimal separator, and precision.

```typescript
const config = {
  prefix: 'R$ ',
  thousands: '.',
  decimal: ',',
  precision: 2,
};

const result = format(12345.67, config);
// result: 'R$ 12.345,67'
```

--------------------------------

### Configure USD Currency Formatting

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/QUICK-REFERENCE.md

Use this configuration for standard US Dollar formatting with a dollar sign prefix, comma thousands separator, and period decimal separator.

```javascript
const config = {
  prefix: '$ ',
  thousands: ',',
  decimal: '.',
  precision: 2,
};
```

--------------------------------

### Handling Blank Values with format()

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/api-reference-format-function.md

Demonstrates how the format function handles zero or blank values when `allowBlank` and `treatZeroAsBlank` options are enabled, returning an empty string.

```typescript
const config = {
  precision: 2,
  allowBlank: true,
  treatZeroAsBlank: true,
};

const result = format(0, config);
// result: '' (zero treated as blank)
```

--------------------------------

### Configure Browserslist for BigInt Support

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/installation-and-setup.md

Specify 'es2020' and relevant browser versions in your .browserslistrc file to ensure BigInt compatibility.

```plaintext
es2020
safari14
```

--------------------------------

### v-money3 Configuration Options

Source: https://github.com/jonathanpmartins/v-money3/blob/main/README.md

Default configuration object for v-money3. All fields are optional except precision. Customize masking, limits, and input behavior.

```javascript
const config = {
  masked: false,
  prefix: '',
  suffix: '',
  thousands: ',',
  decimal: '.',
  precision: 2,
  disableNegative: false,
  disabled: false,
  min: null,
  max: null,
  setMaxIfBigger: true,
  allowBlank: false,
  treatZeroAsBlank: true,
  minimumNumberOfCharacters: 0,
  shouldRound: true,
  focusOnRight: false,
}
```

--------------------------------

### Parsing Formatted Currency with Custom Options

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/api-reference-unformat-function.md

Shows how to use unformat with a custom configuration object to parse a string with a specific currency format, including prefix, thousands separator, decimal separator, and precision.

```typescript
const config = {
  prefix: 'R$ ',
  thousands: '.',
  decimal: ',',
  precision: 2,
};

const result = unformat('R$ 12.345,67', config);
// result: '12345.67'
```

--------------------------------

### Basic Usage with Configuration

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/api-reference-money3-directive.md

Applies the Money3 directive to a native input element using a configuration object. Ensure to use `v-model.lazy` for updates on blur.

```vue
<script setup>
import { Money3Directive } from 'v-money3';

const config = {
  prefix: 'R$ ',
  thousands: '.',
  decimal: ',',
  precision: 2,
};
</script>

<template>
  <input 
    v-model.lazy="amount" 
    v-money3="config"
  />
</template>
```

--------------------------------

### Configure Babel for BigInt Support

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/installation-and-setup.md

Ensure your Babel configuration targets ES2020 environments by setting the appropriate preset and targets.

```json
{
  "presets": [
    ["@babel/preset-env", { "targets": { "browsers": ["es2020"] } }]
  ]
}
```

--------------------------------

### format() Function Signature

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/api-reference-format-function.md

The format() function converts input values into display-friendly strings with currency formatting, separators, and constraints applied. It accepts a value, an optional configuration object, and an internal caller label.

```APIDOC
## format() Function

### Description
Converts input values into display-friendly strings with currency formatting, separators, and constraints applied.

### Signature
```typescript
function format(
  input: string | number | null | undefined,
  opt: VMoneyOptions | ExtractPropTypes<never> = defaults,
  caller: string = '',
): string
```

### Parameters

#### input
- **Type**: `string | number | null | undefined`
- **Required**: yes
- **Description**: The value to format. Can be a number, string representation of a number, or null/undefined.

#### opt
- **Type**: `VMoneyOptions` (or `ExtractPropTypes<never>`)
- **Required**: no
- **Default**: `defaults`
- **Description**: Configuration object with formatting, display, and constraint options. See [Configuration](../configuration.md).

#### caller
- **Type**: `string`
- **Required**: no
- **Default**: `''`
- **Description**: Internal debug label identifying which code path invoked the function.

### Return Type
Returns a formatted `string` ready for display. The format depends on the configuration:
- When `masked` is true: returns the fully formatted display string (e.g., "R$ 12,345.67")
- When `masked` is false: returns the numeric value as a fixed string (e.g., "12345.67")

If `allowBlank` is true and the value is zero or blank, returns empty string.

### Behavior
The function processes input in the following order:
1. Input normalization
2. Prefix/suffix stripping
3. Sign extraction
4. Digit extraction
5. Decimal insertion
6. Min/max clamping
7. Display formatting
8. Zero-as-blank handling

### Examples

#### Basic usage with defaults
```typescript
import { format } from 'v-money3';

const result = format(12345.67);
// result: '12345.67'
```

#### With currency symbol and custom separators
```typescript
const config = {
  prefix: 'R$ ',
  thousands: '.',
  decimal: ',',
  precision: 2,
};

const result = format(12345.67, config);
// result: 'R$ 12.345,67'
```

#### With min/max constraints
```typescript
const config = {
  prefix: '$',
  precision: 2,
  min: 0,
  max: 1000,
};

const result = format(2000, config);
// result: '$1,000.00' (clamped to max)
```

#### Handling blank values
```typescript
const config = {
  precision: 2,
  allowBlank: true,
  treatZeroAsBlank: true,
};

const result = format(0, config);
// result: '' (zero treated as blank)
```

#### With percentage suffix
```typescript
const config = {
  suffix: ' %',
  precision: 1,
  disableNegative: true,
};

const result = format(50.5, config);
// result: '50.5 %'
```

### Throws
Does not throw exceptions. Malformed or invalid inputs are silently handled.

### Notes
- Uses `BigNumber` internally for arbitrary-precision arithmetic.
- When `shouldRound` is false, values are truncated.
- Restricted characters are automatically removed from `prefix`, `suffix`, `decimal`, and `thousands` options.
- `minimumNumberOfCharacters` option pads the display with leading zeros.
- See [VMoneyOptions type](../types.md) for complete configuration reference.
```

--------------------------------

### format() Function

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/README.md

Converts input values to formatted display strings.

```APIDOC
## format() Function

### Description

This standalone function takes a numeric value or a string representation of a number and converts it into a human-readable, formatted currency string.

### Usage

```javascript
import { format } from 'v-money3';

const formattedValue = format(1234.56);
console.log(formattedValue); // Example output: "$1,234.56"
```

### Parameters

- **value** (number | string) - The numeric value or string to format.
- **options** (object) - Optional configuration options for formatting (e.g., currency symbol, decimal places). (Details would be in `configuration.md`)

### Returns

(string) - The formatted currency string.
```

--------------------------------

### BigNumber Arithmetic and Comparison

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/api-reference-bignumber-class.md

Demonstrates creating BigNumber instances for precise calculations and performing comparisons. Note that direct multiplication is not exposed, requiring manual simulation if needed. This class is intended for use with v-money3's internal format/unformat functions.

```typescript
import BigNumber from 'v-money3';

// Arbitrary precision: no floating-point errors
const price = new BigNumber('0.1');
const quantity = new BigNumber('3');

// Manual multiplication simulation (library doesn't expose multiply)
console.log(price.toString()); // '0.1'

// Min/max constraint example
const maxPrice = new BigNumber('1000.00');
const currentPrice = new BigNumber('500.00');

if (currentPrice.lessThan(maxPrice)) {
  console.log('Price is within limits');
}
```

--------------------------------

### V-Money3 Source File Structure

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/module-structure.md

This snippet shows the directory structure of the V-Money3 source code, detailing the purpose of each file.

```tree
src/
├── index.ts              # Entry point
├── options.ts            # Type definitions and defaults
├── BigNumber.ts          # Arbitrary precision arithmetic
├── Utils.ts              # Utility functions
├── format.ts             # Formatting function
├── unformat.ts           # Parsing function
├── component.vue         # Vue 3 component
├── directive.ts          # Vue 3 directive
└── shims-vue.d.ts        # TypeScript Vue shims

```

--------------------------------

### Control Blank Input Behavior

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/configuration.md

Use 'allowBlank' to permit empty input. When 'allowBlank' is true, 'treatZeroAsBlank' determines if zero displays as empty or '0.00'.

```typescript
{ allowBlank: false }
```

```typescript
{ allowBlank: true }
```

```typescript
{ allowBlank: true, treatZeroAsBlank: true }
```

```typescript
{ allowBlank: true, treatZeroAsBlank: false }
```

--------------------------------

### Importing from v-money3 Package

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/module-structure.md

Import different modules like the plugin, components, directives, functions, classes, and types from the v-money3 package.

```typescript
import money from 'v-money3';                    // Plugin
import { Money3Component } from 'v-money3';     // Component
import { Money3Directive } from 'v-money3';     // Directive
import { format } from 'v-money3';              // Function
import { unformat } from 'v-money3';            // Function
import { BigNumber } from 'v-money3';           // Class
import { type VMoneyOptions } from 'v-money3';  // Type
```

--------------------------------

### Basic Currency Input with v-money3 Component

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/INDEX.md

Use the `money3` component for basic currency input with specified precision and prefix.

```vue
<money3 v-model="amount" :precision="2" prefix="$" />
```

--------------------------------

### Basic Currency Input

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/api-reference-money3-component.md

Demonstrates basic currency input with default settings. The value emitted to the model is an unformatted numeric string.

```vue
<template>
  <money3 
    v-model="amount"
    :precision="2"
    prefix="$"
  />
  <p>Value: {{ amount }}</p>
</template>

<script>
import { Money3Component } from 'v-money3';

export default {
  components: { money3: Money3Component },
  data() {
    return {
      amount: '1234.56'
    };
  }
};
</script>
```

--------------------------------

### format() Function

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/_DOCUMENTATION_SUMMARY.txt

The format() function is used for real-time currency formatting. It takes a value and configuration options to return a formatted currency string. It ensures format/unformat round-trip consistency.

```APIDOC
## format()

### Description
Formats a given value into a currency string based on specified options. This function is part of the core functionality ensuring real-time currency formatting and round-trip consistency with unformat.

### Method
Function

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
format(1234.56, { decimal: '.', thousands: ',', prefix: '$ ' })
```

### Response
#### Success Response
- **formattedValue** (string) - The formatted currency string.

#### Response Example
```json
{
  "formattedValue": "$ 1,234.56"
}
```
```

--------------------------------

### Applying Money3 to Wrapper Components

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/api-reference-money3-directive.md

Demonstrates how to apply the Money3 directive to common wrapper components like Vuetify's `v-text-field`, Nuxt UI's `UInput`, and Element Plus's `el-input`. The directive automatically finds the inner input element.

```html
<v-text-field v-money3="config" v-model="amount" />
<UInput v-money3="config" v-model="amount" />
<el-input v-money3="config" v-model="amount" />
```

--------------------------------

### Format Input with VMoneyOptions

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/QUICK-REFERENCE.md

Use the format function to convert string, number, null, or undefined input into a formatted currency string based on provided options. Requires VMoneyOptions.

```typescript
format(
  input: string | number | null | undefined,
  options: VMoneyOptions
): string
```

--------------------------------

### Percentage Input with v-money3

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/README.md

Configure v-money3 for percentage input by setting appropriate precision, min/max values, and disabling negative input. The 'percent' ref will hold the value as a number.

```vue
<template>
  <money3 
    v-model.number="percent"
    :precision="1"
    :min="0"
    :max="100"
    :disable-negative="true"
    suffix=" %"
  />
</template>

<script setup>
import { Money3Component } from 'v-money3';
import { ref } from 'vue';

const percent = ref(50.0); // Returns as number
</script>
```

--------------------------------

### Basic Component Usage with v-money3

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/README.md

Use the Money3Component for basic currency input formatting within a Vue template. Ensure 'v-money3' is imported and registered.

```vue
<template>
  <money3 
    v-model="amount"
    :precision="2"
    prefix="$"
  />
</template>

<script setup>
import { Money3Component } from 'v-money3';
import { ref } from 'vue';

const amount = ref('1234.56');
</script>
```

--------------------------------

### Percentage Input with Limits

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/api-reference-money3-directive.md

Implement percentage input with defined minimum and maximum values, and disable negative inputs. The 'modelModifiers.number' option ensures the bound value is a number.

```html
<template>
  <input 
    v-model.lazy.number="percent"
    v-money3="config"
    placeholder="0%"
  />
</template>

<script setup>
import { Money3Directive } from 'v-money3';
import { ref } from 'vue';

const config = {
  suffix: '%',
  precision: 0,
  min: 0,
  max: 100,
  disableNegative: true,
  modelModifiers: { number: true },
};

const percent = ref(50);
</script>
```

--------------------------------

### Configure Brazilian Real (R$) Formatting

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/QUICK-REFERENCE.md

Configure v-money3 for Brazilian Real with 'R$' prefix, period thousands separator, and comma decimal separator.

```javascript
const config = {
  prefix: 'R$ ',
  thousands: '.',
  decimal: ',',
  precision: 2,
};
```

--------------------------------

### Use v-money3 Utility Functions in Non-Vue Frameworks

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/installation-and-setup.md

Import and use the format and unformat utility functions from v-money3 in non-Vue frameworks.

```typescript
import { format, unformat } from 'v-money3';

const displayValue = format(1234.56, { precision: 2, prefix: '$' });
```

--------------------------------

### Enable Debugging in Configuration

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/README.md

Enable verbose logging for debugging formatting issues by setting the 'debug' option to true in the configuration object. This logs every format/unformat operation to the console.

```javascript
const config = {
  debug: true,  // Logs every format/unformat operation to console
  // ...other options
};
```

--------------------------------

### Max Constraint with Rejection

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/api-reference-money3-directive.md

Configure the directive to reject input exceeding a maximum value instead of clamping it, using 'setMaxIfBigger: false'. This is useful for enforcing strict limits.

```html
<template>
  <input 
    v-model.lazy="budget"
    v-money3="config"
    placeholder="Up to $5,000"
  />
</template>

<script setup>
import { Money3Directive } from 'v-money3';
import { ref } from 'vue';

const config = {
  prefix: '$',
  thousands: ',',
  decimal: '.',
  precision: 2,
  max: 5000,
  setMaxIfBigger: false, // Reject overages instead of clamping
};

const budget = ref('0.00');
</script>
```

--------------------------------

### Create v-money3 Plugin File

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/installation-and-setup.md

Create the v-money3.ts plugin file to register the money directive with your Vue app.

```typescript
import money from 'v-money3';

export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.vueApp.use(money);
});
```

--------------------------------

### Usage with Money3 Component

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/types.md

Shows how to configure the Money3 component using props, including formatting options like prefix, precision, thousands, and decimal separators. The `masked` property controls the output format.

```typescript
import { Money3Component, type VMoneyOptions } from 'v-money3';

const props = {
  modelValue: '1234.56',
  prefix: '$',
  precision: 2,
  thousands: ',',
  decimal: '.',
  masked: false,
} satisfies Partial<VMoneyOptions>;
```

--------------------------------

### Browser Target Configuration

Source: https://github.com/jonathanpmartins/v-money3/blob/main/README.md

Ensure your browser targets include 'es2020' and 'safari14' to avoid 'Big integer literals' errors.

```json
[
  "es2020",
  "safari14"
]
```

--------------------------------

### Percentage Input

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/api-reference-money3-component.md

Configures the input for percentage values, including precision, min/max range, and disabling negative input.

```vue
<template>
  <money3 
    v-model.number="percent"
    :precision="1"
    :min="0"
    :max="100"
    :disable-negative="true"
    suffix=" %"
  />
</template>

<script setup>
import { Money3Component } from 'v-money3';
import { ref } from 'vue';

const percent = ref(50.0);
</script>
```

--------------------------------

### Troubleshooting: Registering App Components and Directives

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/installation-and-setup.md

Ensure the money plugin or Money3Component/Money3Directive is correctly registered with your Vue application instance.

```typescript
// Verify plugin registration
app.use(money);
// OR explicitly register
app.component('money3', Money3Component);
app.directive('money3', Money3Directive);
```

--------------------------------

### Enable Debugging

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/QUICK-REFERENCE.md

Set the debug option to true to enable console logging for debugging purposes.

```javascript
const config = {
  debug: true,  // Enable console logging
  // ...other options
};
```

--------------------------------

### Global Plugin Registration (Vue 3)

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/installation-and-setup.md

Register v-money3 as a global plugin to make the `<money3>` component and `v-money3` directive available throughout your application. No additional imports are needed in components.

```typescript
import { createApp } from 'vue';
import money from 'v-money3';

const app = createApp({});

app.use(money);
```

--------------------------------

### v-money3 Exports

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/QUICK-REFERENCE.md

Lists all available exports from the v-money3 library, including plugins, components, directives, functions, classes, types, and backwards compatibility aliases.

```typescript
// Plugin
import money from 'v-money3';

// Components
import { Money3Component } from 'v-money3';

// Directives
import { Money3Directive } from 'v-money3';

// Functions
import { format, unformat } from 'v-money3';

// Classes
import BigNumber from 'v-money3';

// Types
import { type VMoneyOptions } from 'v-money3';

// Backwards compat aliases
import { 
  Money3,     // = Money3Component
  VMoney3,    // = Money3Directive
  Money,      // = Money3Component
  VMoney      // = Money3Directive
} from 'v-money3';
```

--------------------------------

### Local Component Registration (Vue SFC)

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/installation-and-setup.md

Register the `<money3>` component locally within a Single File Component. This is useful for components that only need the money component.

```vue
<template>
  <money3 v-model="amount" :precision="2" />
</template>

<script setup>
import { Money3Component } from 'v-money3';
import { ref } from 'vue';

const amount = ref('1234.56');
</script>
```

--------------------------------

### Setting Min/Max Limits for Input

Source: https://github.com/jonathanpmartins/v-money3/blob/main/README.md

Constrain the input value within a specified numeric range using the 'min' and 'max' props. Both bounds are optional. The 'max' prop defaults to clamping values above the ceiling.

```html
<money3
  v-model="amount"
  :min="0"
  :max="1000"
  :precision="2"
/>
```

--------------------------------

### v-money3 Imports

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/INDEX.md

Import various components, directives, functions, classes, types, and aliases from the v-money3 library.

```typescript
// Plugin (registers both component and directive)
import money from 'v-money3';

// Component
import { Money3Component } from 'v-money3';

// Directive
import { Money3Directive } from 'v-money3';

// Functions
import { format, unformat } from 'v-money3';

// Class
import BigNumber from 'v-money3';

// Types
import { type VMoneyOptions } from 'v-money3';

// Backwards compatibility aliases
import { Money3, VMoney3, Money, VMoney } from 'v-money3';
```

--------------------------------

### Instantiate BigNumber from String, Number, or BigInt

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/api-reference-bignumber-class.md

Demonstrates creating BigNumber instances using string, number, and BigInt values. Note that BigInt constructor does not support decimal values.

```typescript
import BigNumber from 'v-money3';

// From string
const bn1 = new BigNumber('12345.67');

// From number
const bn2 = new BigNumber(12345.67);

// From BigInt (no decimal support in constructor)
const bn3 = new BigNumber(12345n);
```

--------------------------------

### VMoneyOptions Interface Definition

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/types.md

Defines the complete configuration interface for v-money3 components, directives, and standalone functions. It includes options for formatting, precision, and input behavior.

```typescript
export interface VMoneyOptions {
  debug: boolean;
  masked: boolean;
  prefix: string;
  suffix: string;
  thousands: string;
  decimal: string;
  precision: number;
  disableNegative: boolean;
  disabled: boolean;
  min: number | string | null;
  max: number | string | null;
  setMaxIfBigger: boolean;
  allowBlank: boolean;
  treatZeroAsBlank: boolean;
  minimumNumberOfCharacters: number;
  modelModifiers: any;
  shouldRound: boolean;
  focusOnRight: boolean;
  lazy: boolean;
  [key: string]: any;
}
```

--------------------------------

### Use v-money3 as a Component

Source: https://github.com/jonathanpmartins/v-money3/blob/main/README.md

Integrate the <money3> component into your Vue template. Ensure it's registered globally or locally. The 'config' object should contain your desired formatting options.

```html
<template>
  <money3 v-model="amount" v-bind="config"></money3> {{ amount }}
</template>

<script>
  import { Money3Component } from 'v-money3'

  export default {
    components: { money3: Money3Component },
    data () {
      return {
        amount: '12345.67',
        config: { /* see Configuration above for all fields + defaults */ }
      }
    }
  }
</script>
```

--------------------------------

### Import Arbitrary Precision Arithmetic for v-money3

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/README.md

Import the BigNumber utility for handling arbitrary-precision arithmetic, ensuring exact monetary calculations in your Vue 3 application.

```typescript
import BigNumber from 'v-money3';
```

--------------------------------

### Configure Vite for BigInt Support

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/installation-and-setup.md

Set the build target to 'es2020' in your Vite configuration file (vite.config.ts) to enable BigInt support.

```typescript
export default {
  build: {
    target: 'es2020',
  },
};
```

--------------------------------

### Component Data Flow in v-money3

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/module-structure.md

Illustrates the sequence of events from user input to parent v-model update within a v-money3 component.

```plaintext
User Input
    ↓
Money3Directive.onInput()
    ↓
format() or unformat()
    ↓
Money3Component.change()
    ↓
emit('update:model-value')
    ↓
Parent v-model
```

--------------------------------

### Standalone Formatting and Unformatting Functions

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/INDEX.md

Utilize the `format` and `unformat` functions for standalone currency manipulation with custom options.

```typescript
const display = format(1234.56, { prefix: '$', precision: 2 });
const value = unformat(display, { prefix: '$', precision: 2 });
```

--------------------------------

### Allow Blank Input

Source: https://github.com/jonathanpmartins/v-money3/blob/main/_autodocs/api-reference-money3-component.md

Enables blank input for the currency field, allowing the model value to be null, empty, or a number. `treatZeroAsBlank` is also demonstrated.

```vue
<template>
  <money3 
    v-model.number="optional"
    :precision="2"
    :allow-blank="true"
    :treat-zero-as-blank="true"
    prefix="$"
  />
</template>

<script setup>
import { Money3Component } from 'v-money3';
import { ref } from 'ref';

const optional = ref(null); // Can be null, empty, or a number
</script>
```