# react-native-url-polyfill
> A lightweight and trustworthy URL polyfill for React Native
Latest version **4.0.0** (published 2026-07-14) · MIT license · 0 weekly downloads
## Install
```sh
npm install react-native-url-polyfill
pnpm add react-native-url-polyfill
yarn add react-native-url-polyfill
bun add react-native-url-polyfill
```
## Health
**Score 70/100 (B)** — status: active.
Positive: has types; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.
Warnings: low downloads; no esm support.
## Facts
| | |
|---|---|
| Version | 4.0.0 |
| Published | 2026-07-14 |
| First published | 2019-11-25 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 33.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 411 |
| Author | Nicolas Charpentier |
| Maintainers | charpeni |
| Keywords | URL, URLSearchParams, polyfill, react native, whatwg-url |
## Links
- npm: https://www.npmjs.com/package/react-native-url-polyfill
- Repository: https://github.com/charpeni/react-native-url-polyfill
- Issues: https://github.com/charpeni/react-native-url-polyfill/issues
- npm.io page: https://npm.io/package/react-native-url-polyfill
## Alternatives
- [base64url](https://npm.io/package/base64url.md) — 6.1M weekly downloads
- [get-installed-path](https://npm.io/package/get-installed-path.md) — 502.9K weekly downloads
- [@uppy/url](https://npm.io/package/@uppy/url.md) — 185.8K weekly downloads
- [@d3fc/d3fc-shape](https://npm.io/package/@d3fc/d3fc-shape.md) — 16.2K weekly downloads
- [localizer](https://npm.io/package/localizer.md) — 226 weekly downloads
## Recent versions
- 4.0.0 (latest) — 2026-07-14
- 1.2.0-rc.1 (next) — 2020-07-09
- 3.0.0 — 2025-09-24
- 2.0.0 — 2023-07-13
- 1.3.0 — 2021-03-04
- 1.2.0 — 2020-07-24
- 1.2.0-rc.0 — 2020-06-09
- 1.1.2 — 2020-03-06
- 1.1.2-rc.0 — 2020-03-06
- 1.1.1 — 2020-02-10
- 1.1.0 — 2020-02-10
- 1.0.0 — 2019-11-25
## README
# React Native URL Polyfill
[](https://www.npmjs.org/package/react-native-url-polyfill)
[](https://www.npmjs.org/package/react-native-url-polyfill)
[](https://circleci.com/gh/charpeni/react-native-url-polyfill)
[](https://github.com/charpeni/react-native-url-polyfill/blob/main/LICENSE)
A lightweight and trustworthy URL polyfill for React Native, based on the WHATWG [URL Standard](https://url.spec.whatwg.org/) optimized for React Native.
- **Lightweight**. Ships its own dependency-free implementation of the URL Standard where Unicode hostname support has been left out to keep the bundle small. Written in TypeScript, published as minified plain JavaScript.
- **Trustworthy**. Follows the URL Standard spec, and relies on unit tests generated from [Web Platform Tests](https://github.com/web-platform-tests/wpt/tree/master/url) and Detox e2e tests within [React Native](https://github.com/facebook/react-native). Types are verified to stay interchangeable with Node.js's built-in `URL` and `whatwg-url`.
- **Blob support**. Supports React Native's Blob without additional steps.
- **Hermes support**. Supports [Hermes](https://github.com/facebook/hermes), a JavaScript engine optimized for running React Native.
- **Expo support**. Supports [Expo](https://expo.dev/).
- **Web support**. Most of the time, this polyfill isn't useful on web and therefore using `react-native-url-polyfill/auto` will be no-op on web.
> [!IMPORTANT]
> As mentioned above, Unicode support has been stripped out to keep this polyfill lightweight on mobile. Therefore, [non-ASCII characters](https://unicode.org/reports/tr46/) aren't supported in the hostname.
## Why do we need this?
React Native does include [a polyfill for `URL`](https://github.com/facebook/react-native/blob/8c0c860e38f57e18296f689e47dfb4a54088c260/Libraries/Blob/URL.js#L115-L222), but this polyfill is homemade—in order to keep it light-weight—and was initially created to handle specific use cases.
Meanwhile, React Native has grown around that polyfill, then some unexpected errors have arisen.
> [!NOTE]
> Known issues (non-exhaustive) with React Native's URL are:
>
> - URL cannot handle "localhost" domain for base url [react-native#26019](https://github.com/facebook/react-native/issues/26019).
> - URL implementation should add a trailing slash to the base [react-native#25717](https://github.com/facebook/react-native/issues/25717).
> - URL incorrectly adds trailing slash [react-native#24428](https://github.com/facebook/react-native/issues/24428).
> - Creating an instance of URL like: `new URL('http://facebook.com')` throws an exception [react-native#16434](https://github.com/facebook/react-native/issues/16434).
That's why you may need this external dependency. If you use [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL) within your app, you should look at the installation steps below!
> [!NOTE]
> Adding `react-native-url-polyfill` to React Native source code only adds 📦 **25.19 kB (+3%)** (as of RN 0.86.0) to the JavaScript bundle.
## Installation
First, you need to install the polyfill, which can be done with [Yarn](https://yarnpkg.com/), [npm](https://www.npmjs.com/), and others.
```bash
yarn add react-native-url-polyfill
```
Then, the polyfill can be used in multiple ways. Pick your preferred option.
> [!TIP]
> 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.
```javascript
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.
```javascript
import { setupURLPolyfill } from 'react-native-url-polyfill';
setupURLPolyfill();
```
### Option 3 (_Convenient_ / ponyfill)
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.
```javascript
import { URL, URLSearchParams } from 'react-native-url-polyfill';
const url = new URL('https://github.com');
const searchParams = new URLSearchParams('q=GitHub');
```
## Benchmarks
Run the URL workloads on Node with `yarn benchmark [samples]`, or on the
optimized standalone Hermes runtime bundled with React Native with
`yarn benchmark:hermes [samples]`. The Hermes command currently relies on the
standalone runtime shipped for supported host platforms (macOS in React Native
0.81.4); `HERMES_BIN` and `HERMESC_BIN` can point to another matching binary pair.
These desktop standalone-Hermes measurements are not representative of device
performance. Unsupported optional implementations and operations are reported
and skipped.
## License
react-native-url-polyfill is [MIT licensed](LICENSE).
---
_Source: https://npm.io/package/react-native-url-polyfill · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._