Currency Input

<pa-currency-input> | PaCurrencyInput

A specialized input component for handling currency values with automatic formatting, validation, and locale-aware display. Built on top of vue-currency-input for robust currency handling and formatting capabilities.

vue

<pa-currency-input v-model="amount" />

CAUTION

Many of the custom validations are not working for this component and were not working at the time of this documentation's writing.

When to Use Currency Input vs Regular Input

Use `pa-currency-input` when you need:

Automatic currency formatting: Displays currency symbols, thousands separators, and decimal precision
Real-time formatting: Formats values as users type, showing proper currency display
Locale-aware display: Supports different currency symbols (USD $, EUR €, GBP £, etc.)
Smart focus behavior: Hides formatting during editing for easier input, shows formatting on blur
Precise decimal handling: Built-in precision control for currency calculations
Currency-specific validation: Validates amounts according to currency standards

Use regular `pa-input` (type="number") when you need:

Simple numeric input: Basic number entry without currency formatting
Generic calculations: Mathematical operations not related to money
Custom number formatting: When you want to handle formatting yourself
Non-monetary values: Quantities, percentages, scores, or other numeric data

Comparison Example

Currency Input - Automatic formatting:

Regular Input - Basic number:

vue

<template>
  <div>
    <!-- Currency input: Shows $1,234.56 formatting -->
    <pa-currency-input v-model="price" placeholder="Enter price..." />
    
    <!-- Regular input: Shows 1234.56 without formatting -->
    <pa-input type="number" v-model="quantity" placeholder="Enter quantity..." />
  </div>
</template>

Examples

Basic Usage

vue

<template>
  <pa-currency-input v-model="amount" placeholder="Enter amount..." />
</template>

<script setup>
import { ref } from 'vue'

const amount = ref(null)
</script>

Sizes

Use the size prop to change the input size.

vue

<template>
  <div>
    <pa-currency-input size="sm" v-model="smallAmount" placeholder="Small currency input" />
    <pa-currency-input v-model="mediumAmount" placeholder="Medium currency input (default)" />
    <pa-currency-input size="lg" v-model="largeAmount" placeholder="Large currency input" />
  </div>
</template>

States

Currency inputs can be disabled or readonly.

vue

<template>
  <div>
    <pa-currency-input v-model="normalAmount" placeholder="Normal currency input" />
    <pa-currency-input disabled v-model="disabledAmount" placeholder="Disabled currency input" />
    <pa-currency-input readonly v-model="readonlyAmount" />
  </div>
</template>

Required Fields

Use the required prop to mark fields as mandatory.

vue

<template>
  <div>
    <pa-currency-input required v-model="requiredAmount" placeholder="Required amount" />
    <pa-currency-input v-model="optionalAmount" placeholder="Optional amount" />
  </div>
</template>

Number Constraints

For currency inputs, you can set min, max, and step constraints.

vue

<template>
  <div>
    <pa-currency-input 
      v-model="rangeAmount" 
      :min="0" 
      :max="10000" 
      placeholder="Enter amount $0 - $10,000" 
    />
    <pa-currency-input 
      v-model="stepAmount" 
      :step="5" 
      placeholder="Multiples of $5" 
    />
  </div>
</template>

Custom Currency Options

Configure currency display, precision, and formatting using the options prop.

vue

<template>
  <div style="display: flex; flex-direction: column; gap: 1rem;">
    <pa-currency-input v-model="audAmount" placeholder="Default AUD" />
    <pa-currency-input 
      v-model="usdAmount" 
      :options="usdOptions" 
      placeholder="USD with 2 decimals" 
    />
    <pa-currency-input 
      v-model="eurAmount" 
      :options="eurOptions" 
      placeholder="EUR no decimals or grouping" 
    />
  </div>
</template>

<script setup>
import { ref } from 'vue'

const audAmount = ref(null)
const usdAmount = ref(null)
const eurAmount = ref(null)

const usdOptions = {
  currency: 'USD',
  precision: 2
}

const eurOptions = {
  currency: 'EUR',
  precision: 0,
  useGrouping: false
}
</script>

Importing

typescript

import { PaCurrencyInput } from '@payadvantage/ui_components'

Properties

Name	Description	Reflects	Type	Default
`modelValue`	The currency input's value (used with v-model).	no	`number \| null`	`null`
`size`	The input's size. Only xs, sm, lg, xl have corresponding CSS classes; md is default with no modifier.	no	`string`	`'md'`
`placeholder`	Placeholder text for the input.	no	`string`	`''`
`disabled`	Disables the input.	no	`boolean`	`false`
`readonly`	Makes the input readonly.	no	`boolean`	`false`
`required`	Marks the input as required.	no	`boolean`	`false`
`name`	The input's name attribute.	no	`string`	`''`
`type`	The input type attribute (typically 'currency' for currency inputs).	no	`string`	`'currency'`
`min`	Minimum value for currency inputs.	no	`number \| null`	`null`
`max`	Maximum value for currency inputs.	no	`number \| null`	`null`
`maxlength`	Maximum length for the input.	no	`number \| null`	`null`
`step`	Step value for currency inputs.	no	`number \| null`	`null`
`pattern`	Pattern for input validation.	no	`string \| null`	`null`
`options`	Currency formatting options from vue-currency-input.	no	`CurrencyInputOptions`	`defaultCurrencyOptions`
`sfSelector`	Custom selector for testing frameworks.	no	`string`	`''`

Events

Name	Description	Event Detail
`update:modelValue`	Emitted when the currency input's value changes (for v-model).	New value
`focus`	Emitted when the input receives focus.	Focus event
`blur`	Emitted when the input loses focus.	Blur event
`keyup`	Emitted when a key is released.	Keyboard event
`keydown`	Emitted when a key is pressed.	Keyboard event
`select`	Emitted when text is selected.	Select event

Slots

The currency input component does not support slots.

Dependencies

Bootstrap CSS: Uses Bootstrap's form control styling system for consistent appearance
Validation Mixin: Includes built-in validation capabilities with visual feedback
vue-currency-input: Uses vue-currency-input library for advanced currency formatting and handling
Vue 3: Requires Vue 3 for v-model and reactive features

Design Notes

The currency input component provides:

Currency formatting: Automatic formatting based on locale and currency settings
Flexible sizing: Five size variants from xs to xl for different contexts
Advanced options: Comprehensive currency display and precision configuration
Built-in validation: Automatic validation with visual feedback states
Form integration: Seamless v-model support and form validation

This component is ideal for:

Financial forms and payment interfaces
Price entry and budget management
E-commerce and billing systems
Currency conversion and calculation tools

Accessibility Notes

Uses semantic HTML input elements for proper screen reader support
Maintains focus states for keyboard navigation
Supports ARIA attributes and validation messages
Required fields are properly marked for assistive technologies
Validation states are communicated visually and programmatically
Currency symbols and formatting are announced by screen readers

Currency Options

The options prop accepts a CurrencyInputOptions object with the following default configuration:

typescript

{
  currency: 'AUD',
  currencyDisplay: 'narrowSymbol',
  precision: 2,
  hideCurrencySymbolOnFocus: true,
  hideGroupingSeparatorOnFocus: true,
  hideNegligibleDecimalDigitsOnFocus: true,
  autoDecimalDigits: false,
  useGrouping: true,
  accountingSign: false
}

Common configuration options include:

currency: ISO 4217 currency code (e.g., 'USD', 'EUR', 'GBP')
precision: Number of decimal places to display
useGrouping: Whether to use thousands separators
currencyDisplay: How to display the currency symbol ('symbol', 'narrowSymbol', 'code', 'name')
hideCurrencySymbolOnFocus: Hide currency symbol when focused for easier editing

Currency Input ​

When to Use Currency Input vs Regular Input ​

Use pa-currency-input when you need: ​

Use regular pa-input (type="number") when you need: ​

Comparison Example ​

Examples ​

Basic Usage ​

Sizes ​

States ​

Required Fields ​

Number Constraints ​

Custom Currency Options ​

Importing ​

Properties ​

Events ​

Slots ​

Dependencies ​

Design Notes ​

Accessibility Notes ​

Currency Options ​