ngxsmk-tel-input 0.0.7 → 0.0.8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +203 -34
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,63 +1,232 @@
|
|
|
1
|
-
#
|
|
1
|
+
# ngxsmk-tel-input
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
An Angular **telephone input** with country dropdown, flags, formatting and validation.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
* UI: [`intl-tel-input`](https://github.com/jackocnr/intl-tel-input)
|
|
6
|
+
* Parsing/validation: [`libphonenumber-js`](https://github.com/catamphetamine/libphonenumber-js)
|
|
7
|
+
* Forms: Implements **ControlValueAccessor** (Reactive & Template‑driven)
|
|
8
|
+
* Output: Emits **E.164** (e.g. `+14155550123`) when valid
|
|
6
9
|
|
|
7
|
-
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
## Requirements
|
|
13
|
+
|
|
14
|
+
* Angular **17 – 19**
|
|
15
|
+
* Node **18** or **20**
|
|
16
|
+
|
|
17
|
+
> Peer deps: `@angular/* >=17 <20`
|
|
18
|
+
|
|
19
|
+
---
|
|
20
|
+
|
|
21
|
+
## Install
|
|
8
22
|
|
|
9
23
|
```bash
|
|
10
|
-
|
|
24
|
+
npm i ngxsmk-tel-input intl-tel-input libphonenumber-js
|
|
11
25
|
```
|
|
12
26
|
|
|
13
|
-
|
|
27
|
+
### Add styles & flags (in your **app**, not the library)
|
|
28
|
+
|
|
29
|
+
Add `intl-tel-input` CSS and copy flag images via `angular.json`:
|
|
30
|
+
|
|
31
|
+
```jsonc
|
|
32
|
+
{
|
|
33
|
+
"projects": {
|
|
34
|
+
"<your-app-name>": {
|
|
35
|
+
"architect": {
|
|
36
|
+
"build": {
|
|
37
|
+
"options": {
|
|
38
|
+
"styles": [
|
|
39
|
+
"node_modules/intl-tel-input/build/css/intlTelInput.css"
|
|
40
|
+
],
|
|
41
|
+
"assets": [
|
|
42
|
+
{ "glob": "**/*", "input": "node_modules/intl-tel-input/build/img", "output": "assets/intl-tel-input/img" }
|
|
43
|
+
]
|
|
44
|
+
}
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
}
|
|
48
|
+
}
|
|
49
|
+
}
|
|
50
|
+
```
|
|
14
51
|
|
|
15
|
-
|
|
16
|
-
|
|
52
|
+
Optional flag URL override (put in your app’s global styles):
|
|
53
|
+
|
|
54
|
+
```css
|
|
55
|
+
.iti__flag { background-image: url("/assets/intl-tel-input/img/flags.png"); }
|
|
56
|
+
@media (-webkit-min-device-pixel-ratio: 2), (min-resolution: 192dpi) {
|
|
57
|
+
.iti__flag { background-image: url("/assets/intl-tel-input/img/flags@2x.png"); }
|
|
58
|
+
}
|
|
17
59
|
```
|
|
18
60
|
|
|
19
|
-
|
|
61
|
+
Restart the dev server after changes.
|
|
62
|
+
|
|
63
|
+
---
|
|
64
|
+
|
|
65
|
+
## Quick Start (Reactive Forms)
|
|
66
|
+
|
|
67
|
+
```ts
|
|
68
|
+
// app.component.ts
|
|
69
|
+
import { Component } from '@angular/core';
|
|
70
|
+
import { FormBuilder, ReactiveFormsModule, Validators } from '@angular/forms';
|
|
71
|
+
import { NgxsmkTelInputComponent } from 'ngxsmk-tel-input';
|
|
72
|
+
|
|
73
|
+
@Component({
|
|
74
|
+
selector: 'app-root',
|
|
75
|
+
standalone: true,
|
|
76
|
+
imports: [ReactiveFormsModule, NgxsmkTelInputComponent],
|
|
77
|
+
template: `
|
|
78
|
+
<form [formGroup]="fg" style="max-width:420px;display:grid;gap:12px">
|
|
79
|
+
<ngxsmk-tel-input
|
|
80
|
+
formControlName="phone"
|
|
81
|
+
label="Phone"
|
|
82
|
+
hint="Include area code"
|
|
83
|
+
[initialCountry]="'US'"
|
|
84
|
+
[preferredCountries]="['US','GB','AU']"
|
|
85
|
+
(countryChange)="onCountry($event)">
|
|
86
|
+
</ngxsmk-tel-input>
|
|
87
|
+
|
|
88
|
+
<p class="err" *ngIf="fg.get('phone')?.hasError('phoneInvalid') && fg.get('phone')?.touched">
|
|
89
|
+
Please enter a valid phone number.
|
|
90
|
+
</p>
|
|
91
|
+
|
|
92
|
+
<pre>Value: {{ fg.value | json }}</pre>
|
|
93
|
+
</form>
|
|
94
|
+
`
|
|
95
|
+
})
|
|
96
|
+
export class AppComponent {
|
|
97
|
+
fg = this.fb.group({ phone: ['', Validators.required] });
|
|
98
|
+
constructor(private readonly fb: FormBuilder) {}
|
|
99
|
+
onCountry(e: { iso2: string }) { console.log('country:', e.iso2); }
|
|
100
|
+
}
|
|
101
|
+
```
|
|
20
102
|
|
|
21
|
-
|
|
103
|
+
**Value semantics**
|
|
22
104
|
|
|
23
|
-
|
|
24
|
-
|
|
105
|
+
* Valid → control value is **E.164** string (e.g. `+14155550123`)
|
|
106
|
+
* Empty/invalid → value is **`null`**; validator sets `{ phoneInvalid: true }`
|
|
107
|
+
|
|
108
|
+
---
|
|
109
|
+
|
|
110
|
+
## Template‑driven
|
|
111
|
+
|
|
112
|
+
```html
|
|
113
|
+
<form #f="ngForm">
|
|
114
|
+
<ngxsmk-tel-input name="phone" [(ngModel)]="phone"></ngxsmk-tel-input>
|
|
115
|
+
</form>
|
|
116
|
+
<!-- phone is an E.164 string or null -->
|
|
25
117
|
```
|
|
26
118
|
|
|
27
|
-
|
|
119
|
+
---
|
|
120
|
+
|
|
121
|
+
## API
|
|
122
|
+
|
|
123
|
+
### Inputs
|
|
124
|
+
|
|
125
|
+
| Name | Type | Default | Description |
|
|
126
|
+
| ---------------------- | -------------------------------------- | ---------------------- | ------------------------------------------------------------ |
|
|
127
|
+
| `initialCountry` | `CountryCode \| 'auto'` | `'US'` | Starting country (`'auto'` uses a stubbed US by default). |
|
|
128
|
+
| `preferredCountries` | `CountryCode[]` | `['US','GB']` | Pinned at the top. |
|
|
129
|
+
| `onlyCountries` | `CountryCode[]` | — | Limit selectable countries. |
|
|
130
|
+
| `nationalMode` | `boolean` | `false` | Display national format in the box; value still emits E.164. |
|
|
131
|
+
| `separateDialCode` | `boolean` | `false` | Show dial code separately. |
|
|
132
|
+
| `allowDropdown` | `boolean` | `true` | Enable/disable dropdown. |
|
|
133
|
+
| `placeholder` | `string` | `'Enter phone number'` | Native placeholder. |
|
|
134
|
+
| `autocomplete` | `string` | `'tel'` | Native autocomplete. |
|
|
135
|
+
| `disabled` | `boolean` | `false` | Disable input. |
|
|
136
|
+
| `label` | `string` | — | Label text. |
|
|
137
|
+
| `hint` | `string` | — | Helper text. |
|
|
138
|
+
| `errorText` | `string` | — | Custom error text. |
|
|
139
|
+
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Sizing preset. |
|
|
140
|
+
| `variant` | `'outline' \| 'filled' \| 'underline'` | `'outline'` | Visual style. |
|
|
141
|
+
| `showClear` | `boolean` | `true` | Show clear (×) button. |
|
|
142
|
+
| `autoFocus` | `boolean` | `false` | Focus on init. |
|
|
143
|
+
| `selectOnFocus` | `boolean` | `false` | Select all text on focus. |
|
|
144
|
+
| `formatOnBlur` | `boolean` | `true` | Pretty‑print on blur (national if `nationalMode`). |
|
|
145
|
+
| `showErrorWhenTouched` | `boolean` | `true` | Only show error style after blur. |
|
|
146
|
+
| `dropdownAttachToBody` | `boolean` | `true` | Append dropdown to `<body>` to avoid clipping. |
|
|
147
|
+
| `dropdownZIndex` | `number` | `2000` | Z‑index for dropdown panel. |
|
|
148
|
+
|
|
149
|
+
> `CountryCode` is the ISO‑2 code from `libphonenumber-js` (e.g., `US`, `GB`).
|
|
150
|
+
|
|
151
|
+
### Outputs
|
|
152
|
+
|
|
153
|
+
| Event | Payload | Description |
|
|
154
|
+
| ---------------- | ---------------------------------------------------------- | ---------------------------------- |
|
|
155
|
+
| `countryChange` | `{ iso2: CountryCode }` | When the selected country changes. |
|
|
156
|
+
| `validityChange` | `boolean` | Emits when validity toggles. |
|
|
157
|
+
| `inputChange` | `{ raw: string; e164: string \| null; iso2: CountryCode }` | Emitted on each input. |
|
|
158
|
+
|
|
159
|
+
### Public methods
|
|
160
|
+
|
|
161
|
+
* `focus(): void`
|
|
162
|
+
* `selectCountry(iso2: CountryCode): void`
|
|
163
|
+
|
|
164
|
+
---
|
|
165
|
+
|
|
166
|
+
## Theming
|
|
167
|
+
|
|
168
|
+
The component exposes CSS variables for easy theming. Example:
|
|
169
|
+
|
|
170
|
+
```html
|
|
171
|
+
<ngxsmk-tel-input style="
|
|
172
|
+
--tel-border:#cbd5e1;
|
|
173
|
+
--tel-ring:#22c55e;
|
|
174
|
+
--tel-radius:14px;
|
|
175
|
+
--tel-dd-item-hover: rgba(34,197,94,.12);
|
|
176
|
+
--tel-dd-z: 3000;
|
|
177
|
+
"></ngxsmk-tel-input>
|
|
178
|
+
```
|
|
28
179
|
|
|
29
|
-
|
|
180
|
+
Key tokens:
|
|
30
181
|
|
|
31
|
-
|
|
182
|
+
* Input: `--tel-bg`, `--tel-fg`, `--tel-border`, `--tel-border-hover`, `--tel-ring`, `--tel-placeholder`, `--tel-error`, `--tel-radius`, `--tel-focus-shadow`
|
|
183
|
+
* Dropdown: `--tel-dd-bg`, `--tel-dd-border`, `--tel-dd-shadow`, `--tel-dd-radius`, `--tel-dd-item-hover`, `--tel-dd-search-bg`, `--tel-dd-z`
|
|
32
184
|
|
|
33
|
-
|
|
34
|
-
```bash
|
|
35
|
-
cd dist/ngxsmk-tel-input
|
|
36
|
-
```
|
|
185
|
+
Dark mode: wrap in a `.dark` container – tokens adapt.
|
|
37
186
|
|
|
38
|
-
|
|
39
|
-
```bash
|
|
40
|
-
npm publish
|
|
41
|
-
```
|
|
187
|
+
---
|
|
42
188
|
|
|
43
|
-
##
|
|
189
|
+
## SSR
|
|
44
190
|
|
|
45
|
-
|
|
191
|
+
* `intl-tel-input` is lazy‑loaded **only in the browser** using `isPlatformBrowser` guards.
|
|
192
|
+
* No direct `window`/`document` usage on the server path.
|
|
46
193
|
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
194
|
+
---
|
|
195
|
+
|
|
196
|
+
## Troubleshooting
|
|
197
|
+
|
|
198
|
+
* **Unstyled UI / bullets** → Add CSS + assets in `angular.json`, restart dev server.
|
|
199
|
+
* **Flags missing** → Verify the images were copied to `/assets/intl-tel-input/img` or add the CSS override.
|
|
200
|
+
* **`TS2307: Cannot find module 'ngxsmk-tel-input'`** → Build the lib first; or add a `paths` alias to your app’s `tsconfig` if consuming locally.
|
|
201
|
+
* **Peer dependency conflict** → App Angular version must satisfy `>=17 <20`.
|
|
50
202
|
|
|
51
|
-
|
|
203
|
+
---
|
|
52
204
|
|
|
53
|
-
|
|
205
|
+
## Local dev & publish
|
|
54
206
|
|
|
55
207
|
```bash
|
|
56
|
-
|
|
208
|
+
# Build the library
|
|
209
|
+
ng build ngxsmk-tel-input
|
|
210
|
+
|
|
211
|
+
# Test via tarball in another app
|
|
212
|
+
cd dist/ngxsmk-tel-input && npm pack
|
|
213
|
+
# in your app
|
|
214
|
+
npm i ../path-to/dist/ngxsmk-tel-input/ngxsmk-tel-input-<version>.tgz
|
|
215
|
+
|
|
216
|
+
# Publish (from the built dist folder)
|
|
217
|
+
# bump version in projects/ngxsmk-tel-input/package.json
|
|
218
|
+
ng build ngxsmk-tel-input
|
|
219
|
+
cd dist/ngxsmk-tel-input
|
|
220
|
+
npm publish --access public
|
|
57
221
|
```
|
|
58
222
|
|
|
59
|
-
|
|
223
|
+
---
|
|
224
|
+
|
|
225
|
+
## License
|
|
226
|
+
|
|
227
|
+
[MIT](./LICENSE)
|
|
60
228
|
|
|
61
|
-
##
|
|
229
|
+
## Credits
|
|
62
230
|
|
|
63
|
-
|
|
231
|
+
* UI: `intl-tel-input`
|
|
232
|
+
* Parsing/validation: `libphonenumber-js`
|