NgxSeparadorMiles

A lightweight Angular directive for formatting numbers with thousands separators in input fields. Tested and recommended for Angular 21.x projects (with backward compatibility to Angular 19.2.0+).

🌐 Live Demo

Check out the live examples and implementation guide on GitHub Pages.

Features

• ✅ Automatic thousands separator formatting as you type
• ✅ Configurable decimal and thousands separators
• ✅ Optional decimal support
• ✅ Works seamlessly with Angular Reactive Forms
• ✅ Signal-based configuration
• ✅ Maintains cursor position during formatting
• ✅ Handles copy/paste operations gracefully
• ✅ Type-safe implementation
• ✅ Zero dependencies (except Angular peer dependencies)

Compatibilidad Angular

| Versión ngx-separador-miles | Versión Angular | Estado | |----------------------------|-----------------|--------| | 0.0.1 - 0.0.2 | 19.2.0+ | ✅ Soportado | | 0.0.3 | 19.2.0 - 21.x | ✅ Actual (Recomendado) | | 0.1.x | 22.x | 📅 Planeado | | 1.0.x | 23.x | 📅 Planeado |

Nota: La versión 0.0.3 mantiene compatibilidad retroactiva con Angular 19.2.0+ pero está probada y optimizada para proyectos Angular 21.x.

Requisitos mínimos:

• Angular: >=19.2.0
• TypeScript: 5.7+
• Navegadores modernos (ES2022+)

Installation

Install the package via npm:

npm install ngx-separador-miles --save

Usage

Basic Example

Import the directive in your component:

import { Component, inject } from '@angular/core';
import { FormBuilder, ReactiveFormsModule } from '@angular/forms';
import { SeparadorMilesAccessor } from 'ngx-separador-miles';

@Component({
  selector: 'app-example',
  standalone: true,
  imports: [ReactiveFormsModule, SeparadorMilesAccessor],
  template: `
    <form [formGroup]="form">
      <label for="amount">Amount</label>
      <input 
        id="amount" 
        formControlName="amount" 
        libSeparadorMiles 
        type="text" 
      />
      <p>Value: {{ form.value.amount }}</p>
    </form>
  `
})
export class ExampleComponent {
  private fb = inject(FormBuilder);

  form = this.fb.group({
    amount: [5250000]
  });
}

Advanced Configuration

You can customize the separator behavior using signal-based configuration:

import { Component, inject } from '@angular/core';
import { FormBuilder, ReactiveFormsModule } from '@angular/forms';
import { SeparadorMilesAccessor } from 'ngx-separador-miles';

@Component({
  selector: 'app-advanced-example',
  standalone: true,
  imports: [ReactiveFormsModule, SeparadorMilesAccessor],
  template: `
    <form [formGroup]="form">
      <label for="price">Price (with decimals)</label>
      <input 
        id="price" 
        formControlName="price" 
        libSeparadorMiles
        [libSeparadorMiles.config]="{
          thousandSeparator: ',',
          decimalSeparator: '.',
          allowDecimals: true
        }"
        type="text" 
      />
      <p>Value: {{ form.value.price }}</p>
    </form>
  `
})
export class AdvancedExampleComponent {
  private fb = inject(FormBuilder);

  form = this.fb.group({
    price: [1234567.89]
  });
}

Configuration Options

The directive accepts a configuration object with the following properties:

| Property | Type | Default | Description | |----------|------|---------|-------------| | thousandSeparator | string | '.' | Character used to separate thousands (e.g., '.', ',', ' ') | | decimalSeparator | string | ',' | Character used for decimal point (e.g., ',', '.') | | allowDecimals | boolean | false | Whether to allow decimal values | | currency | string | undefined | Currency symbol (reserved for future use) |

Common Configurations

European Format (default):

{
  thousandSeparator: '.',
  decimalSeparator: ',',
  allowDecimals: true
}
// Example: 1.234.567,89

US Format:

{
  thousandSeparator: ',',
  decimalSeparator: '.',
  allowDecimals: true
}
// Example: 1,234,567.89

Space Separator:

{
  thousandSeparator: ' ',
  decimalSeparator: ',',
  allowDecimals: true
}
// Example: 1 234 567,89

API Reference

Directive Selector

selector: 'input[libSeparadorMiles]'

ControlValueAccessor Implementation

The directive implements Angular's ControlValueAccessor interface, making it fully compatible with:

• Reactive Forms (FormControl, FormGroup)
• Template-driven Forms (ngModel)
• Form validation
• Disabled states

Methods

The directive automatically handles:

• Value formatting: Formats the value when programmatically set via form controls
• User input: Sanitizes and formats input as the user types
• Blur events: Ensures proper formatting when the input loses focus
• Cursor positioning: Maintains cursor position during real-time formatting

Building the Library

To build the library for production:

ng build ngx-separador-miles

The compiled library will be available in the dist/ngx-separador-miles directory.

Building and Publishing

1. Build the library:

   ng build ngx-separador-miles

2. Navigate to the distribution directory:

   cd dist/ngx-separador-miles

3. Publish to npm:

   npm publish

Development

Running Tests

Execute the unit tests:

ng test ngx-separador-miles

Local Development

To test the library locally in your Angular application:

1. Build the library:

   ng build ngx-separador-miles --watch

2. In your consuming application, link to the local build:

   npm link ../path/to/ngx-common-prosmart/dist/ngx-separador-miles

License

This library is part of the ngx-common-prosmart project.

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

Support

For issues, questions, or feature requests, please visit the GitHub repository.

Additional Resources

• Live Examples & Implementation Guide - Interactive demos and detailed implementation instructions
• GitHub Repository - Source code and issue tracking