0
# is-url-superb
1

2
is-url-superb provides a simple and reliable utility for validating whether a given string is a valid URL. It leverages the native JavaScript URL constructor for validation, ensuring robust and standards-compliant URL checking with support for both strict and lenient validation modes.
3

4
## Package Information
5

6
- **Package Name**: is-url-superb
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install is-url-superb`
10

11
## Core Imports
12

13
```typescript
14
import isUrl from 'is-url-superb';
15
```
16

17
For importing types (when needed):
18

19
```typescript
20
import isUrl, { type Options } from 'is-url-superb';
21
```
22

23
## Basic Usage
24

25
```typescript
26
import isUrl from 'is-url-superb';
27

28
// Basic URL validation
29
isUrl('https://sindresorhus.com');
30
//=> true
31

32
isUrl('unicorn');
33
//=> false
34

35
// Lenient mode - allows URLs without protocol
36
isUrl('example.com');
37
//=> false
38

39
isUrl('example.com', {lenient: true});
40
//=> true
41
```
42

43
## Capabilities
44

45
### URL Validation
46

47
Validates whether a string is a properly formatted URL using the native URL constructor.
48

49
```typescript { .api }
50
/**
51
 * Check if a string is a URL
52
 * @param url - The string to validate as a URL
53
 * @param options - Configuration options (optional)
54
 * @returns Returns true if the string is a valid URL, false otherwise
55
 * @throws Throws TypeError if input is not a string
56
 */
57
function isUrl(url: string, options?: Options): boolean;
58
```
59

60
**Parameters:**
61

62
- `url` (string): The string to validate as a URL
63
- `options` (Options, optional): Configuration options, defaults to `{lenient: false}` if not provided
64

65
**Behavior:**
66
- Trims whitespace from the input string
67
- Returns `false` if the string contains spaces
68
- Uses native URL constructor for validation
69
- In lenient mode, automatically prepends 'https://' to URLs without protocol
70
- Strict mode (default) requires protocol to be present
71

72
**Error Handling:**
73
- Throws `TypeError` if the input is not a string
74

75
**Usage Examples:**
76

77
```typescript
78
import isUrl from 'is-url-superb';
79

80
// Valid URLs
81
isUrl('https://sindresorhus.com');           // => true
82
isUrl('  https://sindresorhus.com  ');       // => true (trims whitespace)
83
isUrl('http://example.com/path');            // => true
84
isUrl('ftp://files.example.com');            // => true
85

86
// Invalid URLs  
87
isUrl('unicorn');                            // => false
88
isUrl('abc https://sindresorhus.com');       // => false (contains spaces)
89
isUrl('https://sindresorhus.com abc');       // => false (contains spaces)
90
isUrl('https://sindresorhus.com/abc def');   // => false (contains spaces)
91
isUrl('//sindresorhus.com');                 // => false (no protocol)
92

93
// Lenient mode examples
94
isUrl('//sindresorhus.com', {lenient: true});    // => true
95
isUrl('localhost', {lenient: true});              // => true
96
isUrl('192.168.0.1', {lenient: true});           // => true
97
isUrl('www.example.com', {lenient: true});       // => true
98

99
// Error cases
100
isUrl(123);                                  // => TypeError: Expected a string
101
isUrl(null);                                 // => TypeError: Expected a string
102
```
103

104
## Types
105

106
```typescript { .api }
107
/**
108
 * Configuration options for URL validation
109
 */
110
interface Options {
111
  /**
112
   * Allow URLs without a protocol by automatically prepending 'https://'
113
   * @default false
114
   */
115
  readonly lenient?: boolean;
116
}
117
```
118

119
## Environment Requirements
120

121
- **Node.js**: >= 12
122
- **Module System**: ES Module (supports CommonJS via require)
123
- **Dependencies**: None (uses native URL constructor)
124
- **Browser Support**: Modern browsers supporting URL constructor