@wordpress/url
Advanced tools
A collection of utilities to manipulate URLs.
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.
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
?string: URL to which arguments should be appended. If omitted, only the resulting querystring is returned.Object: Query arguments to apply to URL.Returns
string: URL with arguments applied.
Returns a URL for display.
Usage
const displayUrl = filterURLForDisplay( 'https://www.wordpress.org/gutenberg/' ); // wordpress.org/gutenberg
Parameters
string: Original URL.Returns
string: Displayed URL.
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
string: The full URL.Returns
?string: The authority part of the URL.
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
string: The full URLReturns
?string: The fragment part of the URL.
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
string: The full URL.Returns
?string: The path part of the URL.
Returns the protocol part of the URL.
Usage
const protocol1 = getProtocol( 'tel:012345678' ); // 'tel:'
const protocol2 = getProtocol( 'https://wordpress.org' ); // 'https:'
Parameters
string: The full URL.Returns
?string: The protocol part of the URL.
Returns a single query argument of the url
Usage
const foo = getQueryArg( 'https://wordpress.org?foo=bar&bar=baz', 'foo' ); // bar
Parameters
string: URLstring: Query arg nameReturns
(Array|string): Query arg value.
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
string: The full URL.Returns
?string: The query string part of the URL.
Determines whether the URL contains a given query arg.
Usage
const hasBar = hasQueryArg( 'https://wordpress.org?foo=bar&bar=baz', 'bar' ); // true
Parameters
string: URLstring: Query arg nameReturns
boolean: Whether or not the URL contains the query arg.
Determines whether the given string looks like a URL.
Usage
const isURL = isURL( 'https://wordpress.org' ); // true
Parameters
string: The string to scrutinise.Returns
boolean: Whether or not it looks like a URL.
Checks for invalid characters within the provided authority.
Usage
const isValid = isValidAuthority( 'wordpress.org' ); // true
const isNotValid = isValidAuthority( 'wordpress#org' ); // false
Parameters
string: A string containing the URL authority.Returns
boolean: True if the argument contains a valid authority.
Checks for invalid characters within the provided fragment.
Usage
const isValid = isValidFragment( '#valid-fragment' ); // true
const isNotValid = isValidFragment( '#invalid-#fragment' ); // false
Parameters
string: The url fragment.Returns
boolean: True if the argument contains a valid fragment.
Checks for invalid characters within the provided path.
Usage
const isValid = isValidPath( 'test/path/' ); // true
const isNotValid = isValidPath( '/invalid?test/path/' ); // false
Parameters
string: The URL path.Returns
boolean: True if the argument contains a valid path
Tests if a url protocol is valid.
Usage
const isValid = isValidProtocol( 'https:' ); // true
const isNotValid = isValidProtocol( 'https :' ); // false
Parameters
string: The url protocol.Returns
boolean: True if the argument is a valid protocol (e.g. http:, tel:).
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
string: The query string.Returns
boolean: True if the argument contains a valid query string.
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
string: The URL to testReturns
string: The updated URL
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
string: URL...string: Query ArgsReturns
string: Updated URL
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
string: URI to decode.Returns
string: Decoded URI if possible.
Safely decodes a URI component with decodeURIComponent. Returns the URI component unmodified if
decodeURIComponent throws an error.
Parameters
string: URI component to decode.Returns
string: Decoded URI component if possible.
FAQs
WordPress URL utilities.
The npm package @wordpress/url receives a total of 89,645 weekly downloads. As such, @wordpress/url popularity was classified as popular.
We found that @wordpress/url demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.