ngx-otp-code/README.md

Customizable OTP input component for Angular with Web OTP support.

# ngx-otp-inputs

> Angular OTP (One Time Password) input component with Web OTP support, reactive forms integration and flexible configuration.

[![npm version](https://img.shields.io/npm/v/ngx-otp-code.svg)](https://www.npmjs.com/package/ngx-otp-code)
[![Downloads](https://img.shields.io/npm/dw/ngx-otp-code.svg)](https://www.npmjs.com/package/ngx-otp-code)
 
---

## ✨ Major Features

✅ Customizable length (e.g. 4, 6, etc.)  
✅ Numeric or alphanumeric codes  
✅ Masked or plain text inputs  
✅ Web OTP API integration (auto-read codes from SMS)  
✅ Compatible with Reactive Forms (ControlValueAccessor)  
✅ Easy error handling via outputs  
✅ Standalone Angular Component  
✅ Lightweight and dependency-free (except Angular itself)

---

## 🚀 Installation

Install the package via npm:

```bash
npm install --save ngx-otp-code
```

or with yarn:

```bash
yarn add ngx-otp-code
```

##  ⚙️ Basic Usage
### Import the Component

If you’re using Angular standalone components:

```typescript
import { NgxOtpCodeComponent } from 'ngx-otp-code';
```

Or import the module in your NgModule:

```typescript
import { NgxOtpModule } from 'ngx-otp-code';

@NgModule({
  imports: [NgxOtpInputsModule]
})
export class YourModule {}
```

##  ✅ Example with Reactive Forms
// your.component.ts
```typescript
import { Component } from '@angular/core';
import { FormBuilder, FormGroup } from '@angular/forms';

@Component({
  selector: 'app-my-form',
  templateUrl: './my-form.component.html'
})
export class MyFormComponent {
  form: FormGroup;

  otpConfig = {
    length: 6,
    inputType: 'number',
    autoFocus: true,
    placeholder: '*',
    mask: false,
    useWebOtp: true
  };

  constructor(private fb: FormBuilder) {
    this.form = this.fb.group({
      otp: ['']
    });
  }

  submit() {
    console.log(this.form.value.otp);
  }

  handleOtpError(msg: string) {
    console.error(msg);
  }

  handleCodeFilled(code: string) {
    console.log('OTP complete:', code);
  }
}
```

### Template
```html
<form [formGroup]="form" (ngSubmit)="submit()">
  <ngx-otp-code
    formControlName="otp"
    [config]="otpConfig"
    (error)="handleOtpError($event)"
    (codeFilled)="handleCodeFilled($event)"
  ></ngx-otp-code>

  <button type="submit">Submit</button>
</form>
```

## 🔧 Configuration Options
### Pass a single config object to customize behavior:

| Property      | Type      | Default    | Description                        |            |
| ------------- | --------- | ---------- | ---------------------------------- | ---------- |
| `length`      | `number`  | `6`        | Number of OTP inputs               |            |
| `inputType`   | \`'text'  | 'number'\` | `'text'`                           | Input type |
| `placeholder` | `string`  | `''`       | Placeholder for each input box     |            |
| `autoFocus`   | `boolean` | `true`     | Autofocus first input              |            |
| `isAlpha`     | `boolean` | `false`    | Allow letters and numbers          |            |
| `mask`        | `boolean` | `false`    | Mask input values (password style) |            |
| `useWebOtp`   | `boolean` | `false`    | Enable Web OTP API                 |            |


## 📤 Outputs
### (error)
Emits a string describing any error, e.g. invalid paste:

```typescript
(error)="handleOtpError($event)"
```

### (codeFilled)
Emits the complete OTP code as soon as all digits are filled:

```typescript
(codeFilled)="handleCodeFilled($event)"
```


## 🔐 Web OTP API
This component supports the Web OTP API for automatically reading codes from SMS messages.

✅ Works only over HTTPS
✅ Not supported in all browsers

Enable it by setting:

```html
[config]="{ useWebOtp: true }"
```


---

## 🎨 Custom Styling

`ngx-otp-code` is designed to be styled exclusively via CSS classes for full flexibility and theme compatibility. There are **no inline styles** in the component, giving you full control over its appearance.

---


### Default Classes

By default, the component generates these classes:

- `.otp-container` → wraps all input fields.
- `.otp-input` → applied to every input field.

---


### Custom Classes

You can provide your own classes via the `config` object:

- `containerClass` → custom class for the container.
- `inputClass` → custom class for all inputs.


Example:

```html
<ngx-otp-code
  [config]="{
    length: 6,
    inputType: 'text',
    mask: false,
    placeholder: '*',
    inputClass: 'my-otp-input',
    containerClass: 'my-otp-container'
  }"
  [formControl]="otpControl">
</ngx-otp-inputs>
```

## 🎯 Styling Tips
✅ Define your styles globally or in SCSS files used in your Angular app.
✅ Use Angular’s ViewEncapsulation to control whether styles are global or component-scoped.
✅ Create themes or dark mode simply by switching classes.

## 🎯 Compatibility
Angular 17+

Modern browsers



## 📦 License
MIT © 2025



---

## ☕ Buy Me a Coffee

If you find this library helpful, you can support my work:

[![Buy Me A Coffee](https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png)](https://buymeacoffee.com/leonardomatiz)

👉 [Buy Me a Coffee](https://buymeacoffee.com/leonardomatiz)






## 🔎 Keywords

angular, otp, web-otp, otp-input, code-input, pin-input, one-time-password, ngx-otp-inputs, angular-library, two-factor-auth, authentication