0
# URL Encoding & Decoding
1

2
Comprehensive encoding and decoding functions for different URL components with proper handling of special characters, spaces, and international characters. Each function is optimized for specific URL components to ensure proper encoding while maintaining readability and compatibility.
3

4
## Capabilities
5

6
### General Encoding & Decoding
7

8
Basic encoding and decoding functions for URL components.
9

10
```typescript { .api }
11
/**
12
 * Encodes characters that need to be encoded in URL path, search and hash sections
13
 * @param text - String or number to encode
14
 * @returns URL-encoded string
15
 */
16
function encode(text: string | number): string;
17

18
/**
19
 * Decodes text using decodeURIComponent, returns original text if decoding fails
20
 * @param text - String or number to decode (defaults to empty string)
21
 * @returns Decoded string
22
 */
23
function decode(text?: string | number): string;
24
```
25

26
**Usage Examples:**
27

28
```typescript
29
import { encode, decode } from "ufo";
30

31
// Basic encoding
32
const encoded = encode("hello world");
33
// "hello%20world"
34

35
const special = encode("path/with special#chars");
36
// "path/with%20special%23chars"
37

38
// Safe decoding (won't throw on malformed input)
39
const decoded = decode("hello%20world");
40
// "hello world"
41

42
const malformed = decode("invalid%2");
43
// "invalid%2" (returns original on error)
44
```
45

46
### Path Encoding & Decoding
47

48
Specialized encoding for URL path components with proper slash handling.
49

50
```typescript { .api }
51
/**
52
 * Encodes characters for URL path section
53
 * @param text - String or number to encode for path
54
 * @returns Path-encoded string
55
 */
56
function encodePath(text: string | number): string;
57

58
/**
59
 * Decodes path section with consistent slash encoding handling
60
 * @param text - Path string to decode
61
 * @returns Decoded path string
62
 */
63
function decodePath(text: string): string;
64

65
/**
66
 * Encodes path parameters (includes slash encoding)
67
 * @param text - String or number to encode as path parameter
68
 * @returns Parameter-encoded string
69
 */
70
function encodeParam(text: string | number): string;
71
```
72

73
**Usage Examples:**
74

75
```typescript
76
import { encodePath, decodePath, encodeParam } from "ufo";
77

78
// Path encoding preserves forward slashes
79
const path = encodePath("/api/users/user name");
80
// "/api/users/user%20name"
81

82
// Parameter encoding encodes slashes too
83
const param = encodeParam("user/name");
84
// "user%2Fname"
85

86
// Decode path components
87
const decoded = decodePath("/api/users%2Fprofile");
88
// "/api/users/profile"
89
```
90

91
### Query Encoding & Decoding
92

93
Specialized encoding for query string components with proper space and plus handling.
94

95
```typescript { .api }
96
/**
97
 * Encodes query values with proper space/plus handling
98
 * @param input - Query value to encode (various types supported)
99
 * @returns Query-encoded string
100
 */
101
function encodeQueryValue(input: QueryValue): string;
102

103
/**
104
 * Decodes query values with plus-to-space conversion
105
 * @param text - Query value string to decode
106
 * @returns Decoded query value
107
 */
108
function decodeQueryValue(text: string): string;
109

110
/**
111
 * Encodes query keys including equals sign encoding
112
 * @param text - Query key to encode
113
 * @returns Encoded query key
114
 */
115
function encodeQueryKey(text: string | number): string;
116

117
/**
118
 * Decodes query keys with plus-to-space conversion
119
 * @param text - Query key to decode
120
 * @returns Decoded query key
121
 */
122
function decodeQueryKey(text: string): string;
123

124
type QueryValue = string | number | undefined | null | boolean | Array<QueryValue> | Record<string, any>;
125
```
126

127
**Usage Examples:**
128

129
```typescript
130
import { encodeQueryValue, decodeQueryValue, encodeQueryKey, decodeQueryKey } from "ufo";
131

132
// Query value encoding (spaces become +)
133
const value = encodeQueryValue("hello world");
134
// "hello+world"
135

136
const complex = encodeQueryValue({ key: "value with spaces" });
137
// "%7B%22key%22%3A%22value+with+spaces%22%7D"
138

139
// Query key encoding
140
const key = encodeQueryKey("search query");
141
// "search+query"
142

143
const keyWithEquals = encodeQueryKey("key=value");
144
// "key%3Dvalue"
145

146
// Decoding (+ becomes space)
147
const decodedValue = decodeQueryValue("hello+world");
148
// "hello world"
149

150
const decodedKey = decodeQueryKey("search+term");
151
// "search term"
152
```
153

154
### Hash Encoding
155

156
Specialized encoding for URL hash/fragment sections.
157

158
```typescript { .api }
159
/**
160
 * Encodes characters for URL hash section
161
 * @param text - String to encode for hash
162
 * @returns Hash-encoded string
163
 */
164
function encodeHash(text: string): string;
165
```
166

167
**Usage Examples:**
168

169
```typescript
170
import { encodeHash } from "ufo";
171

172
const hash = encodeHash("section with spaces");
173
// "section%20with%20spaces"
174

175
const withSpecial = encodeHash("user{profile}^section");
176
// "user{profile}^section" (some chars preserved for readability)
177
```
178

179
### Host Encoding
180

181
International domain name encoding using Punycode.
182

183
```typescript { .api }
184
/**
185
 * Encodes hostname using Punycode for international domain names
186
 * @param name - Hostname to encode (defaults to empty string)
187
 * @returns ASCII-encoded hostname
188
 */
189
function encodeHost(name?: string): string;
190
```
191

192
**Usage Examples:**
193

194
```typescript
195
import { encodeHost } from "ufo";
196

197
// International domain encoding
198
const international = encodeHost("пример.рф");
199
// "xn--e1afmkfd.xn--p1ai"
200

201
const mixed = encodeHost("bücher.example.com");
202
// "xn--bcher-kva.example.com"
203

204
// Regular domains pass through
205
const regular = encodeHost("example.com");
206
// "example.com"
207

208
// Email-style hostnames
209
const email = encodeHost("user@пример.рф");
210
// "user@xn--e1afmkfd.xn--p1ai"
211
```
212

213
## Component-Specific Encoding Guidelines
214

215
Different URL components require different encoding strategies:
216

217
- **Path**: Preserves forward slashes, encodes spaces and special characters
218
- **Path Parameters**: Encodes everything including forward slashes
219
- **Query Keys**: Encodes spaces as `+`, encodes `=` sign
220
- **Query Values**: Encodes spaces as `+`, handles complex data types
221
- **Hash**: Preserves some special characters for readability
222
- **Host**: Uses Punycode for international domain names
223

224
All decoding functions are safe and will return the original input if decoding fails, preventing errors in malformed URLs.