WordPress.org

@wordpress/url Edit

A collection of utilities to manipulate URLs.

Installation 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.

Top ↑

Usage Usage

addQueryArgs addQueryArgs

src/index.js#L242-L264

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 Object: Query arguments to apply to URL.

Returns

string: URL with arguments applied.

Top ↑

filterURLForDisplay filterURLForDisplay

src/index.js#L379-L389

Returns a URL for display.

Usage

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

Parameters

  • url string: Original URL.

Returns

string: Displayed URL.

Top ↑

getAuthority getAuthority

src/index.js#L79-L84

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: The authority part of the URL.

Top ↑

getFragment getFragment

src/index.js#L199-L204

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: The fragment part of the URL.

Top ↑

getPath getPath

src/index.js#L119-L124

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: The path part of the URL.

Top ↑

getProtocol getProtocol

src/index.js#L39-L44

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: The protocol part of the URL.

Top ↑

getQueryArg getQueryArg

src/index.js#L279-L284

Returns a single query argument of the url

Usage

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

Parameters

  • url string: URL
  • arg string: Query arg name

Returns

(Array|string): Query arg value.

Top ↑

getQueryString getQueryString

src/index.js#L159-L164

Returns the query string part of the URL.

Usage

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'

Parameters

  • url string: The full URL.

Returns

?string: The query string part of the URL.

Top ↑

hasQueryArg hasQueryArg

src/index.js#L299-L301

Determines whether the URL contains a given query arg.

Usage

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

Parameters

  • url string: URL
  • arg string: Query arg name

Returns

boolean: Whether or not the URL contains the query arg.

Top ↑

isURL isURL

src/index.js#L22-L24

Determines whether the given string looks like a URL.

Usage

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

Parameters

  • url string: The string to scrutinise.

Returns

boolean: Whether or not it looks like a URL.

Top ↑

isValidAuthority isValidAuthority

src/index.js#L99-L104

Checks for invalid characters within the provided authority.

Usage

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

Parameters

  • authority string: A string containing the URL authority.

Returns

boolean: True if the argument contains a valid authority.

Top ↑

isValidFragment isValidFragment

src/index.js#L219-L224

Checks for invalid characters within the provided fragment.

Usage

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

Parameters

  • fragment string: The url fragment.

Returns

boolean: True if the argument contains a valid fragment.

Top ↑

isValidPath isValidPath

src/index.js#L139-L144

Checks for invalid characters within the provided path.

Usage

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

Parameters

  • path string: The URL path.

Returns

boolean: True if the argument contains a valid path

Top ↑

isValidProtocol isValidProtocol

src/index.js#L59-L64

Tests if a url protocol is valid.

Usage

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

Parameters

  • protocol string: The url protocol.

Returns

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

Top ↑

isValidQueryString isValidQueryString

src/index.js#L179-L184

Checks for invalid characters within the provided query string.

Usage

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

Parameters

  • queryString string: The query string.

Returns

boolean: True if the argument contains a valid query string.

Top ↑

prependHTTP prependHTTP

src/index.js#L338-L344

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

Usage

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

Parameters

  • url string: The URL to test

Returns

string: The updated URL

Top ↑

removeQueryArgs removeQueryArgs

src/index.js#L316-L324

Removes arguments from the query string of the url

Usage

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

Parameters

  • url string: URL
  • args ...string: Query Args

Returns

string: Updated URL

Top ↑

safeDecodeURI safeDecodeURI

src/index.js#L359-L365

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

Usage

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

Parameters

  • uri string: URI to decode.

Returns

string: Decoded URI if possible.

Top ↑

safeDecodeURIComponent safeDecodeURIComponent

src/index.js#L399-L405

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

Parameters

  • uriComponent string: URI component to decode.

Returns

string: Decoded URI component if possible.

Code is Poetry.

Skip to toolbar