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 such language features and APIs, you should include the polyfill shipped in @wordpress/babel-preset-default in your code.

Usage

addQueryArgs

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.

Usage

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

Parameters

• url string: URL to which arguments should be appended. If omitted, only the resulting querystring is returned.
• args Record< string, unknown >: Query arguments to apply to URL.

Returns

• string: URL with arguments applied.

buildQueryString

Generates URL-encoded query string using input query data.

It is intended to behave equivalent as PHP’s http_build_query, configured with encoding type PHP_QUERY_RFC3986 (spaces as %20).

Usage

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

Parameters

• data Record< string, unknown >: Data to encode.

Returns

• string: Query string.

cleanForSlug

Performs some basic cleanup of a string for use as a post slug.

This replicates some of what sanitize_title_with_dashes() does in WordPress core, but is only designed to approximate what the slug will be.

Converts Latin-1 Supplement and Latin Extended-A letters to basic Latin letters. Removes combining diacritical marks. Converts whitespace, periods, and forward slashes to hyphens. Removes any remaining non-word characters except hyphens. Converts remaining string to lowercase. It does not account for octets, HTML entities, or other encoded characters.

Parameters

• string string: Title or slug to be processed.

Returns

• string: Processed string.

filterURLForDisplay

Returns a URL for display.

Usage

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

Parameters

• url string: Original URL.
• maxLength number | null: URL length.

Returns

• string: Displayed URL.

getAuthority

Returns the authority part of the URL.

Usage

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

Parameters

• url string: The full URL.

Returns

• string | void: The authority part of the URL.

getFilename

Returns the filename part of the URL.

Usage

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

Parameters

• url string: The full URL.

Returns

• string | void: The filename part of the URL.

getFragment

Returns the fragment part of the URL.

Usage

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'

Parameters

• url string: The full URL

Returns

• string | void: The fragment part of the URL.

getPath

Returns the path part of the URL.

Usage

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'

Parameters

• url string: The full URL.

Returns

• string | void: The path part of the URL.

getPathAndQueryString

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

Usage

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

Parameters

• url string: The full URL.

Returns

• string: The path part and query string part of the URL.

getProtocol

Returns the protocol part of the URL.

Usage

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

Parameters

• url string: The full URL.

Returns

• string | void: The protocol part of the URL.

getQueryArg