URL

The @wordpress/url package provides a comprehensive collection of utilities for manipulating URLs in JavaScript. It includes functions for working with query strings, validating URL components, and parsing URL parts.

Installation

You can install the package using npm:

npm install @wordpress/url --save

This package assumes your code will run in an ES2015+ environment. If you’re targeting environments with limited support for modern JavaScript features, include the polyfill from @wordpress/babel-preset-default.

Query String Utilities

addQueryArgs( url, args )

Appends arguments as querystring to the provided URL. If the URL already includes query arguments, the arguments are merged with (and take precedent over) the existing set.

string

required

URL to which arguments should be appended. If omitted, only the resulting querystring is returned.

object

required

Query arguments to apply to URL.

string

URL with arguments applied.

import { addQueryArgs } from '@wordpress/url';

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

buildQueryString( data )

Generates URL-encoded query string using input query data. This function behaves equivalent to PHP’s http_build_query, configured with encoding type PHP_QUERY_RFC3986 (spaces as %20).

object

required

Data to encode.

string

Query string.

import { buildQueryString } from '@wordpress/url';

const queryString = buildQueryString( {
	simple: 'is ok',
	arrays: [ 'are', 'fine', 'too' ],
	objects: {
		evenNested: {
			ok: 'yes',
		},
	},
} );
// Result: "simple=is%20ok&arrays%5B0%5D=are&arrays%5B1%5D=fine&arrays%5B2%5D=too&objects%5BevenNested%5D%5Bok%5D=yes"

getQueryArg( url, arg )

Returns a single query argument of the URL.

string

required

URL to parse.

string

required

Query arg name.

string | undefined

Query arg value.

import { getQueryArg } from '@wordpress/url';

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

getQueryArgs( url )

Returns an object of query arguments of the given URL. If the URL is invalid or has no querystring, an empty object is returned.

string

required

URL to parse.

object

Query args object.

import { getQueryArgs } from '@wordpress/url';

const args = getQueryArgs( 'https://wordpress.org?foo=bar&bar=baz' );
// Result: { "foo": "bar", "bar": "baz" }

getQueryString( url )

Returns the query string part of the URL.

string

required

The full URL.

string | void

The query string part of the URL.

import { getQueryString } from '@wordpress/url';

const queryString = getQueryString(
	'http://localhost:8080/this/is/a/test?query=true#fragment'
);
// Result: "query=true"

hasQueryArg( url, arg )

Determines whether the URL contains a given query arg.

string

required

URL to check.

string

required

Query arg name.

boolean

Whether or not the URL contains the query arg.

import { hasQueryArg } from '@wordpress/url';

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

removeQueryArgs( url, …args )

Removes arguments from the query string of the URL.

string

required

URL to modify.

string[]

required

Query arg names to remove.

string

Updated URL.

import { removeQueryArgs } from '@wordpress/url';

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

URL Parsing

getProtocol( url )

Returns the protocol part of the URL.

string

required

The full URL.

string | void

The protocol part of the URL.

import { getProtocol } from '@wordpress/url';

const protocol1 = getProtocol( 'tel:012345678' ); // "tel:"
const protocol2 = getProtocol( 'https://wordpress.org' ); // "https:"

getAuthority( url )

Returns the authority part of the URL.

string

required

The full URL.

string | void

The authority part of the URL.

import { getAuthority } from '@wordpress/url';

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

getPath( url )

Returns the path part of the URL.

string

required

The full URL.

string | void

The path part of the URL.

import { getPath } from '@wordpress/url';

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"

getPathAndQueryString( url )

Returns the path part and query string part of the URL.

string

required

The full URL.

string

The path part and query string part of the URL.

import { getPathAndQueryString } from '@wordpress/url';

const pathAndQuery = getPathAndQueryString(
	'http://localhost:8080/this/is/a/test?query=true'
);
// Result: "/this/is/a/test?query=true"

getFragment( url )

Returns the fragment part of the URL.

string

required

The full URL.

string | void

The fragment part of the URL.

import { getFragment } from '@wordpress/url';

const fragment = getFragment(
	'http://localhost:8080/this/is/a/test?query=true#fragment'
);
// Result: "#fragment"

getFilename( url )

Returns the filename part of the URL.

string

required

The full URL.

string | void

The filename part of the URL.

import { getFilename } from '@wordpress/url';

const filename1 = getFilename( 'http://localhost:8080/this/is/a/test.jpg' ); // "test.jpg"
const filename2 = getFilename( '/this/is/a/test.png' ); // "test.png"

URL Validation

isURL( url )

Determines whether the given string looks like a URL.

string

required

The string to scrutinise.

boolean

Whether or not it looks like a URL.

import { isURL } from '@wordpress/url';

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

isEmail( email )

Determines whether the given string looks like an email.

string

required

The string to scrutinise.

boolean

Whether or not it looks like an email.

import { isEmail } from '@wordpress/url';

const result = isEmail( 'hello@wordpress.org' ); // true

isPhoneNumber( phoneNumber )

Determines whether the given string looks like a phone number.

string

required

The string to scrutinize.

boolean

Whether or not it looks like a phone number.

import { isPhoneNumber } from '@wordpress/url';

const result = isPhoneNumber( '+1 (555) 123-4567' ); // true

isValidProtocol( protocol )

Tests if a URL protocol is valid.

string

required

The URL protocol.

boolean

True if the argument is a valid protocol (e.g. http:, tel:).

import { isValidProtocol } from '@wordpress/url';

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

isValidAuthority( authority )

Checks for invalid characters within the provided authority.

string

required

A string containing the URL authority.

boolean

True if the argument contains a valid authority.

import { isValidAuthority } from '@wordpress/url';

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

isValidPath( path )

Checks for invalid characters within the provided path.

string

required

The URL path.

boolean

True if the argument contains a valid path.

import { isValidPath } from '@wordpress/url';

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

isValidQueryString( queryString )

Checks for invalid characters within the provided query string.

string

required

The query string.

boolean

True if the argument contains a valid query string.

import { isValidQueryString } from '@wordpress/url';

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

isValidFragment( fragment )

Checks for invalid characters within the provided fragment.

string

required

The URL fragment.

boolean

True if the argument contains a valid fragment.

import { isValidFragment } from '@wordpress/url';

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

URL Manipulation

prependHTTP( url )

Prepends “http://” to a URL, if it looks like something that is meant to be a TLD.

string

required

The URL to test.

string

The updated URL.

import { prependHTTP } from '@wordpress/url';

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

prependHTTPS( url )

Prepends “https://” to a URL, if it looks like something that is meant to be a TLD.

string

required

The URL to test.

string

The updated URL.

This function will not replace “http://” with “https://“.

import { prependHTTPS } from '@wordpress/url';

const actualURL = prependHTTPS( 'wordpress.org' );
// Result: "https://wordpress.org"

filterURLForDisplay( url, maxLength )

Returns a URL for display purposes.

string

required

Original URL.

number | null

URL length limit.

string

Displayed URL.

import { filterURLForDisplay } from '@wordpress/url';

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

const imageUrl = filterURLForDisplay(
	'https://www.wordpress.org/wp-content/uploads/img.png',
	20
);
// Result: "…ent/uploads/img.png"

cleanForSlug( string )

Performs basic cleanup of a string for use as a post slug. This approximates what sanitize_title_with_dashes() does in WordPress core.

string

required

Title or slug to be processed.

string

Processed string.

import { cleanForSlug } from '@wordpress/url';

const slug = cleanForSlug( 'Hello World!' );
// Result: "hello-world"

This function converts Latin-1 Supplement and Latin Extended-A letters to basic Latin letters, removes combining diacritical marks, converts whitespace/periods/slashes to hyphens, removes non-word characters except hyphens, and converts to lowercase.

normalizePath( path )

Returns a normalized path where equal query parameter values will be treated as identical, regardless of order.

string

required

Original path.

string

Normalized path.

Safe Decoding

safeDecodeURI( uri )

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

string

required

URI to decode.

string

Decoded URI if possible.

import { safeDecodeURI } from '@wordpress/url';

const badUri = safeDecodeURI( '%z' );
// Result: "%z" (does not throw an Error)

safeDecodeURIComponent( uriComponent )

Safely decodes a URI component with decodeURIComponent. Returns the URI component unmodified if decodeURIComponent throws an error.

string

required

URI component to decode.

string

Decoded URI component if possible.

Complete Example

import { addQueryArgs, getQueryArgs, removeQueryArgs } from '@wordpress/url';

// Add query parameters
let url = addQueryArgs( 'https://example.com', {
	page: 2,
	filter: 'active'
} );
// Result: "https://example.com?page=2&filter=active"

// Get query parameters
const params = getQueryArgs( url );
// Result: { page: "2", filter: "active" }

// Remove query parameters
url = removeQueryArgs( url, 'filter' );
// Result: "https://example.com?page=2"

import { 
	getProtocol, 
	getAuthority, 
	getPath,
	getQueryString,
	getFragment
} from '@wordpress/url';

const url = 'https://wordpress.org/plugins/gutenberg/?tab=reviews#top';

console.log( getProtocol( url ) );        // "https:"
console.log( getAuthority( url ) );       // "wordpress.org"
console.log( getPath( url ) );            // "plugins/gutenberg"
console.log( getQueryString( url ) );     // "tab=reviews"
console.log( getFragment( url ) );        // "#top"

import { isURL, isEmail, isPhoneNumber } from '@wordpress/url';

function handleInput( value ) {
	if ( isURL( value ) ) {
		console.log( 'This is a URL' );
	} else if ( isEmail( value ) ) {
		console.log( 'This is an email' );
	} else if ( isPhoneNumber( value ) ) {
		console.log( 'This is a phone number' );
	}
}

handleInput( 'https://wordpress.org' );  // "This is a URL"
handleInput( 'hello@wordpress.org' );    // "This is an email"
handleInput( '+1 (555) 123-4567' );      // "This is a phone number"

Version

Current version: 4.40.0

​URL

​Installation

​Query String Utilities

​addQueryArgs( url, args )

​buildQueryString( data )

​getQueryArg( url, arg )

​getQueryArgs( url )

​getQueryString( url )

​hasQueryArg( url, arg )

​removeQueryArgs( url, …args )

​URL Parsing

​getProtocol( url )

​getAuthority( url )

​getPath( url )

​getPathAndQueryString( url )

​getFragment( url )

​getFilename( url )

​URL Validation

​isURL( url )

​isEmail( email )

​isPhoneNumber( phoneNumber )

​isValidProtocol( protocol )

​isValidAuthority( authority )

​isValidPath( path )

​isValidQueryString( queryString )

​isValidFragment( fragment )

​URL Manipulation

​prependHTTP( url )

​prependHTTPS( url )

​filterURLForDisplay( url, maxLength )

​cleanForSlug( string )

​normalizePath( path )

​Safe Decoding

​safeDecodeURI( uri )

​safeDecodeURIComponent( uriComponent )

​Complete Example

​Version

​Links

URL

Installation

Query String Utilities

addQueryArgs( url, args )

buildQueryString( data )

getQueryArg( url, arg )

getQueryArgs( url )

getQueryString( url )

hasQueryArg( url, arg )

removeQueryArgs( url, …args )

URL Parsing

getProtocol( url )

getAuthority( url )

getPath( url )

getPathAndQueryString( url )

getFragment( url )

getFilename( url )

URL Validation

isURL( url )

isEmail( email )

isPhoneNumber( phoneNumber )

isValidProtocol( protocol )

isValidAuthority( authority )

isValidPath( path )

isValidQueryString( queryString )

isValidFragment( fragment )

URL Manipulation

prependHTTP( url )

prependHTTPS( url )

filterURLForDisplay( url, maxLength )

cleanForSlug( string )

normalizePath( path )

Safe Decoding

safeDecodeURI( uri )

safeDecodeURIComponent( uriComponent )

Complete Example

Version

Links