React Native URL Polyfill

react-native-url-polyfill is a full implementation of the WHATWG URL Standard optimized for React Native.

  • Lightweight. Uses a forked version of whatwg-url (whatwg-url-without-unicode) where unicode support has been stripped out — Going down from 372 KB to 40.9 KB.
  • Trustworthy. Follows closely the URL Standard spec, and relys on unit tests and Detox e2e tests within React Native.
  • Blob support. Supports React Native's Blob without additional steps.
  • Hermes support. Supports Hermes, a JavaScript engine optimized for running React Native on Android.


First, you need to install the polyfill, which can be done with Yarn or npm.


yarn add react-native-url-polyfill


npm install --save react-native-url-polyfill

Then, the polyfill can be used in multiple ways. Pick your preferred option.

ℹ️ To verify if the polyfill has been correctly applied, you can check if the global variable REACT_NATIVE_URL_POLYFILL contains the current package and version like: react-native-url-polyfill@CURRENT_VERSION.

Option 1 (Simple)

Locate your JavaScript entry-point file, commonly called index.js at the root of your React Native project.

Then, import react-native-url-polyfill/auto at the top of your entry-point file, the polyfill will be automatically applied.

import 'react-native-url-polyfill/auto';

Option 2 (Flexible)

If you want to apply the polyfill when you're ready, you can import setupURLPolyfill and call it yourself.

⚠️ Metro doesn't support optional imports.

If you do not apply the polyfill, it will still be added to your JavaScript bundle.
Even if it's wrapped in a condition, Metro won't strip it in production.

import { setupURLPolyfill } from 'react-native-url-polyfill';


Option 3 (Convenient)

If you prefer not to apply this polyfill over React Native's default URL, you can still import those classes manually when you want them.

import { URL, URLSearchParams } from 'react-native-url-polyfill';

const url = new URL('');
const searchParams = new URLSearchParams('q=GitHub');