Overview
Zod provides two functions for URL validation:
z.url() - Validates any URL with a protocolz.httpUrl() - Validates HTTP/HTTPS URLs specifically
import { z } from "zod";
const urlSchema = z.url();
const httpUrlSchema = z.httpUrl();
~/workspace/source/packages/zod/src/v4/classic/schemas.ts:513-523
z.url()
Validates URLs with any protocol scheme.
Basic Usage
const schema = z.url();
schema.parse("https://example.com"); // ✓ passes
schema.parse("http://localhost"); // ✓ passes
schema.parse("ftp://files.example.com"); // ✓ passes
schema.parse("c:"); // ✓ passes (Windows drive)
schema.parse("not-a-url"); // ✗ throws
Valid URL Examples
const schema = z.url();
// Standard URLs
schema.parse("http://google.com");
schema.parse("https://google.com");
// With path and query parameters
schema.parse("https://google.com/asdf?asdf=ljk3lk4&asdf=234#asdf");
// With authentication
schema.parse("https://anonymous:[email protected]/en-US/docs/Web/API/URL/password");
// Localhost
schema.parse("https://localhost");
schema.parse("http://localhost");
// Local domains
schema.parse("https://my.local");
schema.parse("http://aslkfjdalsdfkjaf");
// Other protocols
schema.parse("c:"); // Windows drive
Invalid URL Examples
const schema = z.url();
schema.safeParse("asdf").success; // false
schema.safeParse("https:/").success; // false
schema.safeParse("[email protected]").success; // false - email is not a URL
schema.safeParse("https://").success; // false - incomplete
Custom Error Message
const schema = z.url("Please provide a valid URL");
const result = schema.safeParse("invalid");
if (!result.success) {
console.log(result.error.issues[0].message);
// "Please provide a valid URL"
}
Parameters
z.url(params?: string | URLParams)
string: Custom error messageURLParams: Object with:
message?: string: Custom error messageprotocol?: RegExp: Custom protocol validation patternhostname?: RegExp: Custom hostname validation pattern
z.httpUrl()
Validates URLs with HTTP or HTTPS protocol specifically.
Basic Usage
const schema = z.httpUrl();
schema.parse("https://example.com"); // ✓ passes
schema.parse("http://example.com"); // ✓ passes
schema.parse("ftp://files.example.com"); // ✗ throws - not HTTP(S)
Valid Examples
const schema = z.httpUrl();
schema.parse("http://example.com");
schema.parse("https://example.com");
schema.parse("https://subdomain.example.com/path?query=value#hash");
schema.parse("http://localhost:3000");
Custom Error Message
const schema = z.httpUrl("Must be a valid HTTP or HTTPS URL");
The URL validator preserves the original input exactly as provided. It does not normalize, encode, or modify the URL string in any way.
Examples
API Endpoint Validation
const apiConfigSchema = z.object({
baseUrl: z.httpUrl(),
timeout: z.number(),
});
apiConfigSchema.parse({
baseUrl: "https://api.example.com",
timeout: 5000
}); // ✓ passes
Website URL with Additional Constraints
const websiteSchema = z.httpUrl()
.refine(
(url) => url.startsWith("https://"),
"Only HTTPS URLs are allowed"
);
websiteSchema.parse("https://example.com"); // ✓ passes
websiteSchema.parse("http://example.com"); // ✗ throws
const formSchema = z.object({
website: z.url("Please enter a valid URL").optional(),
email: z.email("Please enter a valid email"),
});
const result = formSchema.safeParse({
website: "not a url",
email: "[email protected]"
});
// Returns error for invalid website URL
URL with Query Parameters
const schema = z.httpUrl();
// Preserves original input including special characters
const input = "https://example.com?key=NUXOmHqWNVTapJkJJHw8BfD155AuqhH_qju_5fNmQ4ZHV7u8";
const output = schema.parse(input);
console.log(output === input); // true - preserved exactly
Return Type
Returns a ZodURL schema that validates and returns strings.
type Output = string;
type Input = string;
The URL validator checks if the string is a valid URL format but does not verify that the URL is accessible or that the domain exists.