Skip to content

Commit 7b1bc5f

Browse files
code-farmzcode-farmz
authored
Merge pull request #125 from code-farmz/feature/reactiveForms
Feature/reactive forms
2 parents 134dfda + 5589a09 commit 7b1bc5f

File tree

7 files changed

+399
-506
lines changed

7 files changed

+399
-506
lines changed

‎README.md‎

Lines changed: 137 additions & 232 deletions
Original file line numberDiff line numberDiff line change
@@ -1,259 +1,164 @@
1-
## ng-otp-input
2-
[![npm version](https://badge.fury.io/js/ng-otp-input.svg)](https://badge.fury.io/js/ng-otp-input) [![npm](https://img.shields.io/npm/dw/ng-otp-input.svg?logo=npm)](https://www.npmjs.com/package/ng-otp-input) [![npm](https://img.shields.io/bundlephobia/minzip/ng-otp-input)](https://www.npmjs.com/package/ng-otp-input)
31

2+
[![npm version](https://badge.fury.io/js/ng-otp-input.svg)](https://badge.fury.io/js/ng-otp-input) [![npm](https://img.shields.io/npm/dw/ng-otp-input.svg?logo=npm)](https://www.npmjs.com/package/ng-otp-input) [![npm](https://img.shields.io/bundlephobia/minzip/ng-otp-input)](https://www.npmjs.com/package/ng-otp-input)
43

5-
A fully customizable, one-time password input component for the web built with Angular.
4+
A fully customizable, one-time password (OTP) input component for the web built with Angular.
65

76
![GIPHY](https://media.giphy.com/media/TdpKuX7H1KBvvR2Hpu/giphy.gif)
87

8+
[**Demo**](https://code-farmz.github.io/ng-otp-input) | [**Edit on StackBlitz**](https://stackblitz.com/github/code-farmz/ng-otp-input)
99

10-
<a href="https://code-farmz.github.io/ng-otp-input" target="_blank">Demo</a>
10+
---
1111

12-
<a href="https://stackblitz.com/github/code-farmz/ng-otp-input" target="_blank">Edit on Stackbliz</a>
1312
## Installation
1413

15-
#### For angular latest angular version(V16 and above)
14+
#### For Angular 16 and above:
15+
16+
```bash
17+
npm install --save ng-otp-input
18+
```
19+
20+
#### For Angular 12 to 15:
21+
22+
```bash
23+
npm install --save [email protected]
24+
```
25+
26+
#### For Angular 11 and below:
1627

17-
npm install --save ng-otp-input
28+
```bash
29+
npm install --save [email protected]
30+
```
1831

19-
#### For angular version(V12 till V15)
32+
---
2033

21-
npm install --save [email protected]
22-
23-
#### For older angular version use v1.8.1(V11 and below)
34+
## Major Changes in v2
2435

25-
npm install --save [email protected]
36+
- Requires Angular 16 or above.
37+
- Emits `null` instead of an empty string if no value is supplied.
38+
- Fully supports **Reactive Forms** (`formControl` and `ngModel` are supported from v2.0.3 onwards).
39+
- Deprecated the custom `formCtrl` input property. Use `formControl` instead.
2640

27-
## Breaking changes in V2
41+
---
2842

29-
* V2 require angular 16 or above
30-
* Component will now emit `null` instead of empty string if no value supplied
3143
## Usage
32-
Add NgOtpInputModule to imports `module.ts` something like
33-
34-
import { NgOtpInputModule } from 'ng-otp-input';
35-
@NgModule({
36-
...
37-
imports: [ ...other modules,
38-
NgOtpInputModule]
39-
})
40-
41-
For Standlone components you can directly import NgOtpComponent
42-
43-
import { NgOtpInputComponent} from 'ng-otp-input';
44-
@Component({
45-
...,
46-
imports: [NgOtpInputComponent]
47-
})
48-
49-
Add component to your page:
50-
51-
52-
53-
<ng-otp-input (onInputChange)="onOtpChange($event)" [config]="{length:5}"></ng-otp-input>
54-
55-
or
56-
57-
<ng-otp-input [formCtrl]="YourFormControl" [config]="{length:5}"></ng-otp-input>
58-
59-
## API
60-
61-
<table>
62-
<tr>
63-
<th>Name</th>
64-
<th>Type</th>
65-
<th>Required</th>
66-
<th>default</th>
67-
<th>Description</th>
68-
</tr>
69-
<tr>
70-
<td>onOtpChange</td>
71-
<td>Output</td>
72-
<td>false</td>
73-
<td>--</td>
74-
<td>Function that will receive the otp.Not required if formCtrl is passed</td>
75-
</tr>
76-
<tr>
77-
<td>onBlur</td>
78-
<td>Output</td>
79-
<td>false</td>
80-
<td>--</td>
81-
<td>Triggered on focus out of the component</td>
82-
</tr>
83-
<tr>
84-
<td>setValue</td>
85-
<td>function</td>
86-
<td>false</td>
87-
<td>--</td>
88-
<td>Call setValue method of component to update component value. See example below</td>
89-
</tr>
90-
<tr>
91-
<td>formCtrl</td>
92-
<td>FormControl</td>
93-
<td>false</td>
94-
<td>--</td>
95-
<td>If there value will be set to the passed form control no need to subscribe to onOtpChange</td>
96-
</tr>
97-
<tr>
98-
<td>config</td>
99-
<td>object</td>
100-
<td>true</td>
101-
<td>{length:4}</td>
102-
<td>Various configuration options to customize the component</td>
103-
</tr>
104-
</table>
105-
106-
<u>**Config options**</u>
107-
<table>
108-
<tr>
109-
<th>Name</th>
110-
<th>Type</th>
111-
<th>Required</th>
112-
<th>default</th>
113-
<th>Description</th>
114-
</tr>
115-
<tr>
116-
<td>allowNumbersOnly</td>
117-
<td>bool</td>
118-
<td>false</td>
119-
<td>--</td>
120-
<td>set true to allow only numbers as input</td>
121-
</tr>
122-
<tr>
123-
<td>disableAutoFocus</td>
124-
<td>bool</td>
125-
<td>false</td>
126-
<td>--</td>
127-
<td>First input will be auto focused on component load and to next empty input on setValue excecution.Set this flag to true to prevent this behaviour</td>
128-
</tr>
129-
<tr>
130-
<td>containerClass</td>
131-
<td>string</td>
132-
<td>false</td>
133-
<td>--</td>
134-
<td>Class applied to container element.</td>
135-
</tr>
136-
<tr>
137-
<td>containerStyles</td>
138-
<td>object</td>
139-
<td>false</td>
140-
<td>--</td>
141-
<td>Style applied to container element.Check https://angular.io/api/common/NgStyle for more info.</td>
142-
</tr>
143-
<tr>
144-
<td>inputStyles</td>
145-
<td>object</td>
146-
<td>false</td>
147-
<td>--</td>
148-
<td>Style applied to each input.Check https://angular.io/api/common/NgStyle for more info.</td>
149-
</tr>
150-
<tr>
151-
<td>inputClass</td>
152-
<td>string</td>
153-
<td>false</td>
154-
<td>--</td>
155-
<td>Class applied to each input.</td>
156-
</tr>
157-
<tr>
158-
<tr>
159-
<td>isPasswordInput</td>
160-
<td>bool</td>
161-
<td>false</td>
162-
<td>--</td>
163-
<td>set true for password type input</td>
164-
</tr>
165-
<td>length</td>
166-
<td>number</td>
167-
<td>true</td>
168-
<td>4</td>
169-
<td>Number of OTP inputs to be rendered.</td>
170-
</tr>
171-
<tr>
172-
<tr>
173-
<td>letterCase</td>
174-
<td>string</td>
175-
<td>--</td>
176-
<td>--</td>
177-
<td>Set value to Upper or Lower to change the otp to upper case or lower case</td>
178-
</tr>
179-
<tr>
180-
<td>placeholder</td>
181-
<td>string</td>
182-
<td>false</td>
183-
<td>--</td>
184-
<td>input placeholder</td>
185-
</tr>
186-
<tr>
187-
<td>separator</td>
188-
<td>char</td>
189-
<td>false</td>
190-
<td>--</td>
191-
<td>Separator char that will be added between inputs</td>
192-
</tr>
193-
<tr>
194-
<td>showError</td>
195-
<td>bool</td>
196-
<td>false</td>
197-
<td>--</td>
198-
<td>If set to true and `formCtrl` is supplied and `formCtrl` is invalid and touced/dirty class error-input will be added to all the inputs and border will trun red</td>
199-
</tr>
200-
</table>
201-
202-
<u>**Updating component value using setValue method**</u>
203-
204-
Component value can be updated using `setValue` method of the component example:-
205-
206-
207-
1. get component reference using [@ViewChild](https://angular.io/api/core/ViewChild)
208-
209-
For version 1.7.7 and latest
210-
211-
@ViewChild(NgOtpInputComponent, { static: false}) ngOtpInput:NgOtpInputComponent;
212-
213-
For version older than 1.7.7
214-
215-
<ng-otp-input #ngOtpInput ></ng-otp-input> //add hash to ng-otp-input component```
216-
@ViewChild('ngOtpInput') ngOtpInputRef:any;
217-
218-
219-
220-
2. call `setValue` method when you want to set the value of component like
221-
222-
yourMethod(){
223-
this.ngOtpInputRef.setValue(yourValue);
224-
//yourvalue can be any string or number
225-
}
226-
227-
<u>**Disable inputs**</u>
228-
229-
Inputs can be disabled by getting the otp form instance of the component and calling disable method
230-
231-
1.Get the component ref in the same way as done in SetValue method above
232-
2.Call disable method of otpForm as follow
233-
234-
``` this.ngOtpInputRef.otpForm.disable(); ```
235-
236-
<u>**Focus to Specific box**</u>
237-
238-
1.Get the component ref in the same way as done in SetValue method above
239-
240-
2.Get the box id and call ```focusTo``` method as follow
241-
242-
```
243-
let eleId=this.ngOtpInputRef.getBoxId(0);
244-
this.ngOtpInputRef.focusTo(eleId);
44+
45+
### Import the Module
46+
47+
For **Modules**:
48+
49+
```typescript
50+
import { NgOtpInputModule } from 'ng-otp-input';
51+
52+
@NgModule({
53+
imports: [
54+
...otherModules,
55+
NgOtpInputModule,
56+
],
57+
})
58+
export class AppModule {}
24559
```
24660

247-
## License
61+
For **Standalone Components**:
24862

249-
[![NPM](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/code-farmz/ng-otp-input/blob/master/LICENSE)
63+
```typescript
64+
import { NgOtpInputComponent } from 'ng-otp-input';
25065

251-
## Contributing
66+
@Component({
67+
standalone: true,
68+
imports: [NgOtpInputComponent],
69+
})
70+
export class YourComponent {}
71+
```
72+
73+
### Add the Component to Your Template
74+
75+
```html
76+
<!-- With Event Binding -->
77+
<ng-otp-input (onInputChange)="onOtpChange($event)" [config]="{ length: 5 }"></ng-otp-input>
78+
79+
<!-- Using Reactive FormControl (v2.0.3 and above) -->
80+
<ng-otp-input [formControl]="yourFormControl" [config]="{ length: 5 }"></ng-otp-input>
81+
```
82+
83+
---
84+
85+
## API Reference
86+
87+
### Component Inputs/Outputs
25288

253-
Add a star to show your support and feel free to open [issues](https://github.com/code-farmz/ng-otp-input/issues/new) and [pull requests](https://github.com/code-farmz/ng-otp-input/compare)!
89+
| Name | Type | Required | Default | Description |
90+
|-----------------|----------|----------|---------|-----------------------------------------------------------------------------|
91+
| `disabled` | boolean | No | `false` | Disables all inputs when set to `true`. |
92+
| `onOtpChange` | `Output` | No | -- | Emits the OTP value on change. Not required if using `formControl`. |
93+
| `onBlur` | `Output` | No | -- | Triggered when focus is lost from the component. |
94+
| `setValue` | function | No | -- | Allows programmatic setting of the component value. |
95+
| `config` | object | Yes | `{ length: 4 }` | Configuration object for customization (see **Config Options** below). |
25496

97+
---
25598

99+
### Config Options
256100

101+
| Name | Type | Required | Default | Description |
102+
|-------------------|---------|----------|------------|----------------------------------------------------------------------------------------------|
103+
| `allowNumbersOnly` | boolean | No | `false` | Restricts input to numeric values only. |
104+
| `disableAutoFocus` | boolean | No | `false` | Prevents automatic focus on load or when setting the value. |
105+
| `containerClass` | string | No | -- | Adds a custom CSS class to the container element. |
106+
| `containerStyles` | object | No | -- | Customizes the container styles. Check [NgStyle](https://angular.io/api/common/NgStyle). |
107+
| `inputStyles` | object | No | -- | Customizes the styles of individual inputs. |
108+
| `inputClass` | string | No | -- | Adds a custom CSS class to each input box. |
109+
| `isPasswordInput` | boolean | No | `false` | Masks input as password fields. |
110+
| `length` | number | Yes | `4` | Sets the number of OTP inputs to render. |
111+
| `letterCase` | string | No | -- | Converts input to `Upper` or `Lower` case. |
112+
| `placeholder` | string | No | -- | Sets a placeholder for each input box. |
113+
| `separator` | char | No | -- | Inserts a separator character between input boxes. |
114+
| `showError` | boolean | No | `false` | Highlights inputs with red borders if `formControl` is invalid, dirty, or touched. |
257115

116+
---
117+
118+
## Advanced Features
119+
120+
### Updating Component Value
121+
122+
- Use `formControl` or `ngModel` (v2.0.3 and above) for updates.
123+
- For earlier versions, use `setValue`:
124+
125+
```typescript
126+
@ViewChild(NgOtpInputComponent, { static: false }) ngOtpInput: NgOtpInputComponent;
127+
128+
updateOtpValue() {
129+
this.ngOtpInput.setValue('12345'); // Replace with your OTP value.
130+
}
131+
```
132+
133+
---
134+
135+
### Disabling Inputs
136+
137+
- Use the `disabled` property or set the `FormControl` to a disabled state (v2.0.3+).
138+
- For earlier versions, use `disable` method:
139+
140+
```typescript
141+
this.ngOtpInput.otpForm.disable();
142+
```
143+
144+
---
145+
146+
### Focus on a Specific Input
147+
148+
```typescript
149+
const eleId = this.ngOtpInput.getBoxId(0);
150+
this.ngOtpInput.focusTo(eleId);
151+
```
152+
153+
---
154+
155+
## License
156+
157+
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/code-farmz/ng-otp-input/blob/master/LICENSE)
158+
159+
---
160+
161+
## Contributing
258162

163+
Show your support by starring the repo! Feel free to open [issues](https://github.com/code-farmz/ng-otp-input/issues/new) or contribute via [pull requests](https://github.com/code-farmz/ng-otp-input/compare).
259164

0 commit comments

Comments
 (0)