URL utils for humans
npm install ufo[![npm version][npm-version-src]][npm-version-href]
[![npm downloads][npm-downloads-src]][npm-downloads-href]
[![bundle][bundle-src]][bundle-href]
[![Codecov][codecov-src]][codecov-href]
URL utils for humans.
Install using npm or your favourite package manager:
Install package:
``shnpm
npm install ufo
Import utils:
js
// ESM
import { normalizeURL, joinURL } from "ufo";// CommonJS
const { normalizeURL, joinURL } = require("ufo");
// Deno
import { parseURL } from "https://unpkg.com/ufo/dist/index.mjs";
`Encoding Utils
$3
Decodes text using
. Returns the original text if it fails.$3
Decodes path section of URL (consistent with encodePath for slash encoding).
$3
Decodes query key (consistent with
encodeQueryKey for plus encoding).$3
Decodes query value (consistent with
encodeQueryValue for plus encoding).$3
Encodes characters that need to be encoded in the path, search and hash sections of the URL.
$3
Encodes characters that need to be encoded in the hash section of the URL.
$3
Encodes hostname with punycode encoding.
$3
Encodes characters that need to be encoded in the path section of the URL as a param. This function encodes everything
encodePath does plus the slash (/) character.$3
Encodes characters that need to be encoded in the path section of the URL.
$3
Encodes characters that need to be encoded for query values in the query section of the URL and also encodes the
= character.$3
Encodes characters that need to be encoded for query values in the query section of the URL.
Parsing Utils
$3
Takes a string of the form
username:password and returns an object with the username and password decoded.$3
Parses a URL and returns last segment in path as filename.
If
{ strict: true } is passed as the second argument, it will only return the last segment only if ending with an extension.Example:
`js
// Result: filename.ext
parseFilename("http://example.com/path/to/filename.ext");// Result: undefined
parseFilename("/path/to/.hidden-file", { strict: true });
`$3
Takes a string, and returns an object with two properties:
and port.Example:
`js
parseHost("foo.com:8080");
// { hostname: 'foo.com', port: '8080' }
`$3
Splits the input string into three parts, and returns an object with those three parts.
Example:
js
parsePath("http://foo.com/foo?test=123#token");
// { pathname: 'http://foo.com/foo', search: '?test=123', hash: '#token' }
`$3
Takes a URL string and returns an object with the URL's
, auth, host, pathname, search, and hash.Example:
`js
parseURL("http://foo.com/foo?test=123#token");
// { protocol: 'http:', auth: '', host: 'foo.com', pathname: '/foo', search: '?test=123', hash: '#token' }parseURL("foo.com/foo?test=123#token");
// { pathname: 'foo.com/foo', search: '?test=123', hash: '#token' }
parseURL("foo.com/foo?test=123#token", "https://");
// { protocol: 'https:', auth: '', host: 'foo.com', pathname: '/foo', search: '?test=123', hash: '#token' }
`$3
Takes a
object and returns the stringified URL.Example:
`js
const obj = parseURL("http://foo.com/foo?test=123#token");
obj.host = "bar.com";stringifyParsedURL(obj); // "http://bar.com/foo?test=123#token"
`Query Utils
$3
Encodes a pair of key and value into a url query string value.
If the value is an array, it will be encoded as multiple key-value pairs with the same key.
Example:
js
encodeQueryItem('message', 'Hello World')
// 'message=Hello+World'encodeQueryItem('tags', ['javascript', 'web', 'dev'])
// 'tags=javascript&tags=web&tags=dev'
`$3
Parses and decodes a query string into an object.
The input can be a query string with or without the leading
.Example:
`js
parseQuery("?foo=bar&baz=qux");
// { foo: "bar", baz: "qux" }parseQuery("tags=javascript&tags=web&tags=dev");
// { tags: ["javascript", "web", "dev"] }
`$3
Stringfies and encodes a query object into a query string.
Example:
js
stringifyQuery({ foo: 'bar', baz: 'qux' })
// 'foo=bar&baz=qux'stringifyQuery({ foo: 'bar', baz: undefined })
// 'foo=bar'
`Utils
$3
$3
Removes double slashes from the URL.
Example:
js
cleanDoubleSlashes("//foo//bar//"); // "/foo/bar/"cleanDoubleSlashes("http://example.com/analyze//http://localhost:3000//");
// Returns "http://example.com/analyze/http://localhost:3000/"
`$3
Removes the query section of the URL.
Example:
js
filterQuery("/foo?bar=1&baz=2", (key) => key !== "bar"); // "/foo?baz=2"
`$3
Parses and decodes the query object of an input URL into an object.
Example:
js
getQuery("http://foo.com/foo?test=123&unicode=%E5%A5%BD");
// { test: "123", unicode: "好" }
`$3
Checks if the input has a leading slash (e.g.
).$3
Checks if the input has a protocol.
You can use
{ acceptRelative: true } to accept relative URLs as valid protocol.Example:
`js
hasProtocol('https://example.com'); // truehasProtocol("//example.com"); // false
hasProtocol('//example.com', { acceptRelative: true }); // true
hasProtocol("ftp://example.com"); // true
hasProtocol('data:text/plain'); // true
hasProtocol('data:text/plain', { strict: true }); // false
`$3
Checks if the input has a trailing slash.
Example:
js
hasTrailingSlash("/foo/"); // truehasTrailingSlash("/foo"); // false
hasTrailingSlash("/foo?query=true", true); // false
hasTrailingSlash("/foo/?query=true", true); // true
`$3
Checks if the input URL is empty or
.$3
Checks if two paths are equal regardless of encoding, trailing slash, and leading slash differences.
You can make slash check strict by setting
{ trailingSlash: true, leadingSlash: true } as options.You can make encoding check strict by setting
{ encoding: true } as options.Example:
`js
isEqual("/foo", "foo"); // true
isEqual("foo/", "foo"); // true
isEqual("/foo bar", "/foo%20bar"); // true// Strict compare
isEqual("/foo", "foo", { leadingSlash: true }); // false
isEqual("foo/", "foo", { trailingSlash: true }); // false
isEqual("/foo bar", "/foo%20bar", { encoding: true }); // false
`$3
Checks if the input URL is neither empty nor
.$3
Check if a path starts with
./ or ../.Example:
`js
isRelative("./foo"); // true
`$3
Check if two paths are equal or not. Trailing slash and encoding are normalized before comparison.
Example:
js
isSamePath("/foo", "/foo/"); // true
`$3
Checks if the input protocol is any of the dangerous
, data:, javascript: or vbscript: protocols.Example:
`js
isScriptProtocol("javascript:alert(1)"); // trueisScriptProtocol("data:text/html,hello"); // true
isScriptProtocol("blob:hello"); // true
isScriptProtocol("vbscript:alert(1)"); // true
isScriptProtocol("https://example.com"); // false
`$3
Joins multiple URL segments into a single URL and also handles relative paths with
and ../.Example:
`js
joinRelativeURL("/a", "../b", "./c"); // "/b/c"
`$3
Joins multiple URL segments into a single URL.
Example:
js
joinURL("a", "/b", "/c"); // "a/b/c"
`$3
Normalizes the input URL:
- Ensures the URL is properly encoded - Ensures pathname starts with a slash - Preserves protocol/host if provided
Example:
js
normalizeURL("test?query=123 123#hash, test");
// Returns "test?query=123%20123#hash,%20test"normalizeURL("http://localhost:3000");
// Returns "http://localhost:3000"
`$3
Resolves multiple URL segments into a single URL.
Example:
js
resolveURL("http://foo.com/foo?test=123#token", "bar", "baz");
// Returns "http://foo.com/foo/bar/baz?test=123#token"
`$3
Ensures the URL or pathname starts with base.
If input already starts with base, it will not be added again.
Example:
js
withBase("/foo/bar", "/foo"); // "/foo/bar"withBase("/foo/bar", "/baz"); // "/baz/foo/bar"
`$3
Adds or replaces the fragment section of the URL.
Example:
js
withFragment("/foo", "bar"); // "/foo#bar"
withFragment("/foo#bar", "baz"); // "/foo#baz"
withFragment("/foo#bar", ""); // "/foo"
`$3
Adds or replaces the URL protocol to
.Example:
`js
withHttp("https://example.com"); // http://example.com
`$3
Adds or replaces the URL protocol to
.Example:
`js
withHttps("http://example.com"); // https://example.com
`$3
Ensures the URL or pathname has a leading slash.
Example:
js
withLeadingSlash("foo"); // "/foo"
`$3
Removes the base from the URL or pathname.
If input does not start with base, it will not be removed.
Example:
js
withoutBase("/foo/bar", "/foo"); // "/bar"
`$3
Removes the fragment section from the URL.
Example:
js
withoutFragment("http://example.com/foo?q=123#bar")
// Returns "http://example.com/foo?q=123"
`$3
Removes the host from the URL while preserving everything else.
Example:
js
withoutHost("http://example.com/foo?q=123#bar")
// Returns "/foo?q=123#bar"
`$3
Removes leading slash from the URL or pathname.
Example:
js
withoutLeadingSlash("/foo"); // "foo"
`$3
Removes the protocol from the input.
Example:
js
withoutProtocol("http://example.com"); // "example.com"
`$3
Removes the trailing slash from the URL or pathname.
If second argument is
, it will only remove the trailing slash if it's not part of the query or fragment with cost of more expensive operations.Example:
`js
withoutTrailingSlash("/foo/"); // "/foo"withoutTrailingSlash("/path/?query=true", true); // "/path?query=true"
`$3
Adds or replaces protocol of the input URL.
Example:
js
withProtocol("http://example.com", "ftp://"); // "ftp://example.com"
`$3
Add/Replace the query section of the URL.
Example:
js
withQuery("/foo?page=a", { token: "secret" }); // "/foo?page=a&token=secret"
`$3
Ensures the URL ends with a trailing slash.
If second argument is
, it will only add the trailing slash if it's not part of the query or fragment with cost of more expensive operation.Example:
`js
withTrailingSlash("/foo"); // "/foo/"withTrailingSlash("/path?query=true", true); // "/path/?query=true"
``Special thanks to Eduardo San Martin Morote (posva) for encoding utilities
[npm-version-src]: https://img.shields.io/npm/v/ufo?style=flat&colorA=18181B&colorB=F0DB4F
[npm-version-href]: https://npmjs.com/package/ufo
[npm-downloads-src]: https://img.shields.io/npm/dm/ufo?style=flat&colorA=18181B&colorB=F0DB4F
[npm-downloads-href]: https://npmjs.com/package/ufo
[codecov-src]: https://img.shields.io/codecov/c/gh/unjs/ufo/main?style=flat&colorA=18181B&colorB=F0DB4F
[codecov-href]: https://codecov.io/gh/unjs/ufo
[bundle-src]: https://img.shields.io/bundlephobia/minzip/ufo?style=flat&colorA=18181B&colorB=F0DB4F
[bundle-href]: https://bundlephobia.com/result?p=ufo