🔢 svelte-number-formatter

A powerful, reactive number formatter utility for Svelte + TypeScript with comprehensive validation, real-time formatting, and extensive customization options.

✨ Features

• Live number formatting for inputs (12,345.67, $1,000.00, 85%, etc.)
• Input validation with custom error messages and warnings
• Multiple formatting styles (decimal, currency, percentage)
• Locale-aware formatting with automatic browser detection
• Real-time reactive updates with Svelte store integration
• Comprehensive input cleaning and sanitization
• Min/max value validation with custom ranges
• Prefix/suffix support for custom formatting
• Strict mode for rejecting invalid input
• Increment/decrement utilities for stepper controls
• TypeScript support with full type definitions

📦 Installation

From npm (public)

npm install svelte-number-formatter

From GitHub Packages

npm install @dev-henen/svelte-number-formatter --registry=https://npm.pkg.github.com

📁 GitHub Repository: github.com/dev-henen/svelte-number-formatter

🚀 Getting Started

import { NumberFormatter } from 'svelte-number-formatter';

const formatter = new NumberFormatter();

✨ Basic Usage in a Svelte Component

<script lang="ts">
	import { NumberFormatter } from 'svelte-number-formatter';
	const formatter = new NumberFormatter();
</script>

<input bind:value={formatter.handler} />
<p>Raw: {formatter.raw}</p>
<p>Formatted: {formatter.formatted}</p>
<p>Numeric Value: {formatter.value}</p>

or, using a local value:

<script lang="ts">
	import { NumberFormatter } from 'svelte-number-formatter';
	const formatter = new NumberFormatter();
	let value = formatter.formatted;
	$: formatter.handler = value;
</script>

<input bind:value={value} />
<p>Raw: {formatter.raw}</p>
<p>Formatted: {formatter.formatted}</p>

🔧 Constructor

new NumberFormatter(initial?, options?)

Create a new formatter with optional initial value and formatting options.

const formatter = new NumberFormatter("1234.56", {
	style: 'currency',
	currency: 'USD',
	decimals: 2,
	useGrouping: true
});

📊 Properties

| Property | Type | Description | | ----------- | -------- | -------------------------------------------------- | | handler | string | Input setter that auto-updates raw + formatted | | raw | string | The numeric value stripped of symbols | | formatted | string | The value formatted for display (12,345.67) | | value | number | The parsed numeric value |

Reactive Stores

| Store | Type | Description | | -------------- | ----------------------- | ------------------------------------- | | validation | Readable<ValidationResult> | Current validation state | | isEditing | Readable<boolean> | Whether input is currently being edited | | numericValue | Readable<number> | Parsed numeric value as store |

🔁 Setting .handler = "12345" will automatically update .raw, .formatted, and .value.

⚙️ Configuration Options

setOptions(options: Partial<FormatOptions>)

Update formatting options dynamically:

formatter.setOptions({
	style: 'currency',
	currency: 'EUR',
	decimals: 2,
	min: 0,
	max: 10000
});

FormatOptions

type FormatOptions = {
	locale?: string;                           // e.g., "en-US", "de-DE"
	useGrouping?: boolean;                     // thousand separators (default: true)
	decimals?: number;                         // decimal places (default: 0)
	currency?: string;                         // e.g., "USD", "EUR"
	style?: "decimal" | "currency" | "percent"; // formatting style
	allowNegative?: boolean;                   // allow negative numbers (default: true)
	allowDecimal?: boolean;                    // allow decimal input (default: true)
	min?: number;                              // minimum value
	max?: number;                              // maximum value
	prefix?: string;                           // custom prefix
	suffix?: string;                           // custom suffix
	placeholder?: string;                      // placeholder for empty values
	strict?: boolean;                          // reject invalid input (default: false)
};

🎯 Methods

Core Methods

format(value: string | number): string

Format a raw number programmatically:

formatter.format("123456.789"); // → "123,456.79" or "$123,456.79"

setValue(value: string | number): void

Set the value programmatically:

formatter.setValue(1234.56);

reset(): void

Clear all values and reset validation state:

formatter.reset();

Validation Methods

isValid(): boolean

Check if current value is valid:

if (formatter.isValid()) {
	// proceed with valid value
}

getValidation(): ValidationResult

Get detailed validation information:

const validation = formatter.getValidation();
console.log(validation.isValid, validation.error, validation.warning);

Utility Methods

increment(step?: number): void

Increment the current value:

formatter.increment(1);    // +1
formatter.increment(10);   // +10

decrement(step?: number): void

Decrement the current value:

formatter.decrement(1);    // -1
formatter.decrement(5);    // -5

focus(): void / blur(): void

Simulate focus/blur for form integration:

formatter.focus();  // sets isEditing to true
formatter.blur();   // sets isEditing to false

📡 Subscription Methods

Enhanced Subscription

Subscribe to all formatter state changes:

const unsubscribe = formatter.subscribe(({ raw, formatted, value, validation, isEditing }) => {
	console.log("Raw:", raw);
	console.log("Formatted:", formatted);
	console.log("Value:", value);
	console.log("Valid:", validation.isValid);
	console.log("Editing:", isEditing);
});

Convenience Subscriptions

subscribeFormatted(run: Subscriber<string>): Unsubscriber

const unsubscribe = formatter.subscribeFormatted(formatted => {
	console.log("Formatted:", formatted);
});

subscribeRaw(run: Subscriber<string>): Unsubscriber

const unsubscribe = formatter.subscribeRaw(raw => {
	console.log("Raw:", raw);
});

subscribeValue(run: Subscriber<number>): Unsubscriber

const unsubscribe = formatter.subscribeValue(value => {
	console.log("Value:", value);
});

🔍 Validation System

The formatter includes a comprehensive validation system:

ValidationResult Type

type ValidationResult = {
	isValid: boolean;
	error?: string;     // Validation error message
	warning?: string;   // Warning message (non-blocking)
};

Example with Validation

<script lang="ts">
	import { NumberFormatter } from 'svelte-number-formatter';
	
	const formatter = new NumberFormatter("", {
		min: 0,
		max: 100,
		decimals: 2,
		strict: true
	});
	
	let validation = formatter.getValidation();
	$: validation = $formatter.validation;
</script>

<input bind:value={formatter.handler} />

{#if !validation.isValid}
	<p class="error">{validation.error}</p>
{/if}

{#if validation.warning}
	<p class="warning">{validation.warning}</p>
{/if}

🌍 Localization Examples

Currency Formatting

// US Dollar
const usdFormatter = new NumberFormatter("1234.56", {
	style: 'currency',
	currency: 'USD',
	locale: 'en-US'
});
// → "$1,234.56"

// Euro
const eurFormatter = new NumberFormatter("1234.56", {
	style: 'currency',
	currency: 'EUR',
	locale: 'de-DE'
});
// → "1.234,56 €"

Percentage Formatting

const percentFormatter = new NumberFormatter("0.85", {
	style: 'percent',
	decimals: 1
});
// → "85.0%"

Custom Prefix/Suffix

const customFormatter = new NumberFormatter("42", {
	prefix: "Score: ",
	suffix: " pts",
	useGrouping: false
});
// → "Score: 42 pts"

🎛️ Advanced Usage Examples

Stepper Input Component

<script lang="ts">
	import { NumberFormatter } from 'svelte-number-formatter';
	
	const formatter = new NumberFormatter("0", {
		min: 0,
		max: 100,
		decimals: 0
	});
</script>

<div class="stepper">
	<button on:click={() => formatter.decrement()}>-</button>
	<input bind:value={formatter.handler} />
	<button on:click={() => formatter.increment()}>+</button>
</div>

<p>Value: {formatter.value}</p>

Form Integration with Validation

<script lang="ts">
	import { NumberFormatter } from 'svelte-number-formatter';
	
	const priceFormatter = new NumberFormatter("", {
		style: 'currency',
		currency: 'USD',
		decimals: 2,
		min: 0,
		max: 999999,
		strict: true
	});
	
	$: isValid = $priceFormatter.validation.isValid;
</script>

<form>
	<label>
		Price:
		<input 
			bind:value={priceFormatter.handler}
			class:invalid={!isValid}
		/>
	</label>
	
	{#if !isValid}
		<span class="error">{$priceFormatter.validation.error}</span>
	{/if}
	
	<button type="submit" disabled={!isValid}>
		Submit
	</button>
</form>

🔧 Static Utility Methods

NumberFormatter.formatValue(value, options?): string

Format a value without creating a formatter instance:

const formatted = NumberFormatter.formatValue(1234.56, {
	style: 'currency',
	currency: 'USD'
});
// → "$1,234.56"

NumberFormatter.parseValue(formattedValue): number

Parse a formatted value back to a number:

const value = NumberFormatter.parseValue("$1,234.56");
// → 1234.56

📚 Common Use Cases

1. Financial Applications

const moneyFormatter = new NumberFormatter("", {
	style: 'currency',
	currency: 'USD',
	decimals: 2,
	min: 0
});

2. Percentage Inputs

const percentFormatter = new NumberFormatter("", {
	style: 'percent',
	decimals: 1,
	min: 0,
	max: 1
});

3. Quantity Inputs

const quantityFormatter = new NumberFormatter("1", {
	decimals: 0,
	min: 1,
	max: 999,
	useGrouping: false
});

4. Scientific Notation

const scientificFormatter = new NumberFormatter("", {
	decimals: 3,
	useGrouping: false,
	allowNegative: true
});

🌐 Browser Compatibility

• Locale Detection: Automatically detects browser locale via navigator.language
• SSR Support: Defaults to "en-US" in server-side environments
• Modern Browsers: Uses Intl.NumberFormat for reliable formatting
• Fallback: Graceful degradation if formatting fails

🧠 Notes

• handler acts as a two-way reactive setter for <input> elements
• Validation runs automatically on every input change
• Strict mode (strict: true) rejects invalid input entirely
• Non-strict mode allows invalid input but marks it as invalid
• Locale is automatically detected from browser settings
• All stores are reactive and integrate seamlessly with Svelte's reactivity system

🔗 Links

• 📁 GitHub: https://github.com/dev-henen/svelte-number-formatter
• 📦 NPM: https://www.npmjs.com/package/svelte-number-formatter
• 📦 GitHub Package: https://github.com/dev-henen/svelte-number-formatter/packages

📜 License

MIT © dev-henen

🙌 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.