@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.
# 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
[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.# 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
Record<string,*>: 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() 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: 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
string: Original URL.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
string: The full URL.Returns
string|void: The authority 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
string: The full URLReturns
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
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
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
string: The full URL.Returns
string|void: The protocol part of the URL.# getQueryArg
Returns a single query argument of the url
Usage
const foo = getQueryArg( 'https://wordpress.org?foo=bar&bar=baz', 'foo' ); // bar
Parameters
string: URL.string: Query arg name.Returns
QueryArgParsed|void: Query arg value.# getQueryArgs
Returns an object of query arguments of the given URL. If the given URL is invalid or has no querystring, an empty object is returned.
Usage
const foo = getQueryArgs( 'https://wordpress.org?foo=bar&bar=baz' );
// { "foo": "bar", "bar": "baz" }
Parameters
string: URL.Returns
QueryArgs: Query args object.# getQueryString
Returns the query string part of the URL.
Usage
const queryString = getQueryString( 'http://localhost:8080/this/is/a/test?query=true#fragment' ); // 'query=true'
Parameters
string: The full URL.Returns
string|void: The query string part of the URL.# hasQueryArg
Determines whether the URL contains a given query arg.
Usage
const hasBar = hasQueryArg( 'https://wordpress.org?foo=bar&bar=baz', 'bar' ); // true
Parameters
string: URL.string: Query arg name.Returns
boolean: Whether or not the URL contains the query arg.# isEmail
Determines whether the given string looks like an email.
Usage
const isEmail = isEmail( 'hello@wordpress.org' ); // true
Parameters
string: The string to scrutinise.Returns
boolean: Whether or not it looks like an email.# isURL
Determines whether the given string looks like a URL.
Related
Usage
const isURL = isURL( 'https://wordpress.org' ); // true
Parameters
string: The string to scrutinise.Returns
boolean: Whether or not it looks like a URL.# isValidAuthority
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.# isValidFragment
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.# isValidPath
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# isValidProtocol
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:).# isValidQueryString
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.# prependHTTP
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 test.Returns
string: The updated URL.# removeQueryArgs
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 Args.Returns
string: Updated URL.# safeDecodeURI
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.# safeDecodeURIComponent
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.
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.