0
# IP Regex
1

2
IP Regex provides comprehensive regular expression functionality for matching and validating IP addresses in both IPv4 and IPv6 formats. It offers flexible configuration options including exact matching and boundary detection for precise validation and text processing.
3

4
## Package Information
5

6
- **Package Name**: ip-regex
7
- **Package Type**: npm
8
- **Language**: JavaScript with TypeScript definitions
9
- **Installation**: `npm install ip-regex`
10

11
## Core Imports
12

13
```typescript
14
import ipRegex from 'ip-regex';
15
```
16

17
For CommonJS:
18

19
```javascript
20
const ipRegex = require('ip-regex');
21
```
22

23
For ES modules in JavaScript:
24

25
```javascript
26
import ipRegex from 'ip-regex';
27
```
28

29
## Basic Usage
30

31
```javascript
32
import ipRegex from 'ip-regex';
33

34
// Contains an IP address?
35
ipRegex().test('unicorn 192.168.0.1');
36
//=> true
37

38
// Is an IP address?
39
ipRegex({exact: true}).test('unicorn 192.168.0.1');
40
//=> false
41

42
// Extract all IP addresses from text
43
'unicorn 192.168.0.1 cake 1:2:3:4:5:6:7:8 rainbow'.match(ipRegex());
44
//=> ['192.168.0.1', '1:2:3:4:5:6:7:8']
45

46
// IPv6 validation
47
ipRegex.v6({exact: true}).test('1:2:3:4:5:6:7:8');
48
//=> true
49

50
// Boundary detection prevents false positives
51
ipRegex({includeBoundaries: true}).test('192.168.0.2000000000');
52
//=> false
53
```
54

55
## Capabilities
56

57
### Main IP Regex Function
58

59
Returns a regular expression for matching both IPv4 and IPv6 addresses.
60

61
```typescript { .api }
62
/**
63
 * Regular expression for matching IP addresses
64
 * @param options - Configuration options
65
 * @returns A regex for matching both IPv4 and IPv6
66
 */
67
declare const ipRegex: {
68
  (options?: Options): RegExp;
69
  v4(options?: Options): RegExp;
70
  v6(options?: Options): RegExp;
71
};
72

73
export default ipRegex;
74
```
75

76
### IPv4 Regex Function
77

78
Returns a regular expression for matching IPv4 addresses only.
79

80
```typescript { .api }
81
/**
82
 * @param options - Configuration options
83
 * @returns A regex for matching IPv4
84
 */
85
ipRegex.v4(options?: Options): RegExp;
86
```
87

88
### IPv6 Regex Function
89

90
Returns a regular expression for matching IPv6 addresses only.
91

92
```typescript { .api }
93
/**
94
 * @param options - Configuration options
95
 * @returns A regex for matching IPv6
96
 */
97
ipRegex.v6(options?: Options): RegExp;
98
```
99

100
**Usage Examples:**
101

102
```javascript
103
import ipRegex from 'ip-regex';
104

105
// IPv4 only matching
106
const ipv4Text = 'Server at 192.168.1.1 and backup at 10.0.0.1';
107
const ipv4Addresses = ipv4Text.match(ipRegex.v4());
108
//=> ['192.168.1.1', '10.0.0.1']
109

110
// IPv6 only matching
111
const ipv6Address = '2001:0DB8:85A3:0000:0000:8A2E:0370:7334';
112
ipRegex.v6({exact: true}).test(ipv6Address);
113
//=> true
114

115
// Mixed IPv4 and IPv6 extraction
116
const mixedText = 'IPv4: 192.168.1.1, IPv6: ::1, another IPv4: 127.0.0.1';
117
const allIPs = mixedText.match(ipRegex());
118
//=> ['192.168.1.1', '::1', '127.0.0.1']
119
```
120

121
## Types
122

123
```typescript { .api }
124
interface Options {
125
  /**
126
   * Only match an exact string. Useful with RegExp#test() to check if a string is an IP address.
127
   * (false matches any IP address in a string)
128
   * @default false
129
   */
130
  readonly exact?: boolean;
131

132
  /**
133
   * Include boundaries in the regex. When true, '192.168.0.2000000000' will report as an invalid IPv4 address.
134
   * If this option is not set, the mentioned IPv4 address would report as valid (ignoring the trailing zeros).
135
   * @default false
136
   */
137
  readonly includeBoundaries?: boolean;
138
}
139
```
140

141
## Configuration Options
142

143
### exact option
144

145
When set to `true`, the regex will only match complete strings that are valid IP addresses. This is useful for validation:
146

147
```javascript
148
// Validation mode - entire string must be an IP
149
ipRegex({exact: true}).test('192.168.1.1');     //=> true
150
ipRegex({exact: true}).test('prefix 192.168.1.1'); //=> false
151

152
// Search mode (default) - finds IPs within text
153
ipRegex().test('prefix 192.168.1.1 suffix');   //=> true
154
```
155

156
### includeBoundaries option
157

158
When set to `true`, includes word boundaries to prevent false positives with trailing digits:
159

160
```javascript
161
// Without boundaries (default) - may match partial numbers
162
'192.168.0.2000000000'.match(ipRegex());
163
//=> ['192.168.0.200'] (matches first valid part)
164

165
// With boundaries - prevents false positives
166
'192.168.0.2000000000'.match(ipRegex({includeBoundaries: true}));
167
//=> null (no match due to trailing digits)
168

169
// Proper IP addresses still match correctly
170
'Valid IP: 192.168.0.200 here'.match(ipRegex({includeBoundaries: true}));
171
//=> ['192.168.0.200']
172
```
173

174
## Common Use Cases
175

176
### IP Address Validation
177

178
```javascript
179
function isValidIP(ip) {
180
  return ipRegex({exact: true}).test(ip);
181
}
182

183
isValidIP('192.168.1.1');           //=> true
184
isValidIP('not an ip');             //=> false
185
isValidIP('192.168.1.1.extra');     //=> false
186
```
187

188
### IPv6 Zone ID Support
189

190
The regex supports IPv6 zone identifiers (scope IDs):
191

192
```javascript
193
ipRegex.v6({exact: true}).test('fe80::1%eth0');     //=> true
194
ipRegex.v6({exact: true}).test('::1%1');            //=> true
195
```
196

197
### Text Processing and Extraction
198

199
```javascript
200
function extractIPs(text) {
201
  return text.match(ipRegex()) || [];
202
}
203

204
const logEntry = 'Connection from 192.168.1.100 to 2001:db8::1 failed';
205
const foundIPs = extractIPs(logEntry);
206
//=> ['192.168.1.100', '2001:db8::1']
207
```
208

209
### Safe IP Detection with Boundaries
210

211
```javascript
212
function findRealIPs(text) {
213
  return text.match(ipRegex({includeBoundaries: true})) || [];
214
}
215

216
// Prevents false matches in serial numbers, IDs, etc.
217
const serialNumber = 'Device-192168001001-Rev2';
218
findRealIPs(serialNumber);  //=> [] (no false positive)
219

220
const realLog = 'Connected to 192.168.1.1 successfully';
221
findRealIPs(realLog);       //=> ['192.168.1.1']
222
```