@wordpress/url

URL

A collection of utilities to manipulate URLs.

Installation

Install the module

npm install @wordpress/url --save

This package assumes that your code will run in an ES2015+ environment. If you're using an environment that has limited or no support for ES2015+ such as lower versions of IE then using core-js or @babel/polyfill will add support for these methods. Learn more about it in Babel docs.

Usage

isURL

const isURL = isURL( 'https://wordpress.org' ); // true

Checks whether the URL is an HTTP or HTTPS URL.

getProtocol

const protocol1 = getProtocol( 'tel:[phone]' ); // 'tel:'
const protocol2 = getProtocol( 'https://wordpress.org' ); // 'https:'

Returns the protocol part of the provided URL.

isValidProtocol

const isValid = isValidProtocol( 'https:' ); // true
const isNotValid = isValidProtocol( 'https :' ); // false

Returns true if the provided protocol is valid. Returns false if the protocol contains invalid characters.

getAuthority

const authority1 = getAuthority( 'https://wordpress.org/help/' ); // 'wordpress.org'
const authority2 = getAuthority( 'https://localhost:8080/test/' ); // 'localhost:8080'

Returns the authority part of the provided URL.

isValidAuthority

const isValid = isValidAuthority( 'wordpress.org' ); // true
const isNotValid = isValidAuthority( 'wordpress#org' ); // false

Returns true if the provided authority is valid. Returns false if the protocol contains invalid characters.

getPath

const path1 = getPath( 'http://localhost:8080/this/is/a/test?query=true' ); // 'this/is/a/test'
const path2 = getPath( 'https://wordpress.org/help/faq/' ); // 'help/faq'

Returns the path part of the provided URL.

isValidPath

const isValid = isValidPath( 'test/path/' ); // true
const isNotValid = isValidPath( '/invalid?test/path/' ); // false

Returns true if the provided path is valid. Returns false if the path contains invalid characters.

getQueryString

const queryString1 = getQueryString( 'http://localhost:8080/this/is/a/test?query=true#fragment' ); // 'query=true'
const queryString2 = getQueryString( 'https://wordpress.org#fragment?query=false&search=hello' ); // 'query=false&search=hello'

Returns the query string part of the provided URL.

isValidQueryString

const isValid = isValidQueryString( 'query=true&another=false' ); // true
const isNotValid = isValidQueryString( 'query=true?another=false' ); // false

Returns true if the provided query string is valid. Returns false if the query string contains invalid characters.

getFragment

const fragment1 = getFragment( 'http://localhost:8080/this/is/a/test?query=true#fragment' ); // '#fragment'
const fragment2 = getFragment( 'https://wordpress.org#another-fragment?query=true' ); // '#another-fragment'

Returns the fragment part of the provided URL.

isValidFragment

const isValid = isValidFragment( '#valid-fragment' ); // true
const isNotValid = isValidFragment( '#invalid-#fragment' ); // false

Returns true if the provided fragment is valid. Returns false if the fragment contains invalid characters.

addQueryArgs

const newURL = addQueryArgs( 'https://google.com', { q: 'test' } ); // https://google.com/?q=test

Adds a query string argument to the provided URL.

prependHTTP

const actualURL = prependHTTP( 'wordpress.org' ); // http://wordpress.org

Prepends the provided partial URL with the http:// protocol.

getQueryArg

const foo = getQueryArg( 'https://wordpress.org?foo=bar&bar=baz', 'foo' ); // bar

Retrieve a query string argument from the provided URL.

hasQueryArg

const hasBar = hasQueryArg( 'https://wordpress.org?foo=bar&bar=baz', 'bar' ); // true

Checks whether a URL contains the given query string argument.

removeQueryArgs

const newUrl = removeQueryArgs( 'https://wordpress.org?foo=bar&bar=baz&baz=foobar', 'foo', 'bar' ); // https://wordpress.org?baz=foobar

Removes one or more query string arguments from the given URL.

safeDecodeURI

const badUri = safeDecodeURI( '%z' ); // does not throw an Error, simply returns '%z'

Safely decodes a URI with decodeURI. Returns the URI unmodified if decodeURI throws an Error.

filterURLForDisplay

const displayUrl = filterURLForDisplay( 'https://www.wordpress.org/gutenberg/' ); // wordpress.org/gutenberg

Returns a URL for display, without protocol, www subdomain, or trailing slash.