uppy/docs/sources/companion-plugins/url.mdx

---
slug: /url
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

import UppyCdnExample from '/src/components/UppyCdnExample';

# Import from URL

The `@uppy/url` plugin allows users to import files from the internet. Paste any
URL and it will be added!

:::tip

[Try out the live example](/examples) or take it for a spin in
[StackBlitz](https://stackblitz.com/edit/vitejs-vite-zaqyaf?file=main.js).

:::

## When should I use this?

When you want to let users import files any URL.

A [Companion](/docs/companion) instance is required for the URL plugin to work.
This saves the user bandwidth, especially helpful if they are on a mobile
connection.

You can self-host Companion or get a hosted version with any
[Transloadit plan](https://transloadit.com/pricing/).

:::note

Companion has
[Server Side Request Forgery](https://owasp.org/www-community/attacks/Server_Side_Request_Forgery)
(SSRF) protections built-in so you don’t have to worry about the security
implications of arbitrary URLs.

:::

<Tabs>
  <TabItem value="npm" label="NPM" default>

```shell
npm install @uppy/url
```

  </TabItem>

  <TabItem value="yarn" label="Yarn">

```shell
yarn add @uppy/url
```

  </TabItem>

  <TabItem value="cdn" label="CDN">
    <UppyCdnExample>
      {`
        import { Uppy, Url } from "{{UPPY_JS_URL}}"
        const uppy = new Uppy()
        uppy.use(Url, {
          // Options
        })
      `}
    </UppyCdnExample>
  </TabItem>
</Tabs>

## Use

Using `@uppy/url` only requires setup in Uppy.

### Use in Uppy

```js {10-13} showLineNumbers
import Uppy from '@uppy/core';
import Dashboard from '@uppy/dashboard';
import Url from '@uppy/url';

import '@uppy/core/dist/style.min.css';
import '@uppy/dashboard/dist/style.min.css';
import "@uppy/url/dist/style.min.css";

new Uppy()
	.use(Dashboard, { inline: true, target: '#dashboard' })
	.use(Url, { companionUrl: 'https://your-companion.com' });
```

### Use in Companion

Companion supports this plugin out-of-the-box, however it must be enabled in
Companion with the `enableUrlEndpoint` / `COMPANION_ENABLE_URL_ENDPOINT` option.

## API

### Options

#### `id`

A unique identifier for this plugin (`string`, default: `'Url'`).

#### `title`

Title / name shown in the UI, such as Dashboard tabs (`string`, default:
`'Url'`).

#### `target`

DOM element, CSS selector, or plugin to place the drag and drop area into
(`string`, `Element`, `Function`, or `UIPlugin`, default:
[`Dashboard`](/docs/dashboard)).

#### `companionUrl`

URL to a [Companion](/docs/companion) instance (`string`, default: `null`).

#### `companionHeaders`

Custom headers that should be sent along to [Companion](/docs/companion) on
every request (`Object`, default: `{}`).

#### `companionAllowedHosts`

The valid and authorised URL(s) from which OAuth responses should be accepted
(`string` or `RegExp` or `Array`, default: `companionUrl`).

This value can be a `string`, a `RegExp` pattern, or an `Array` of both. This is
useful when you have your [Companion](/docs/companion) running on several hosts.
Otherwise, the default value should do fine.

#### `companionCookiesRule`

This option correlates to the
[RequestCredentials value](https://developer.mozilla.org/en-US/docs/Web/API/Request/credentials)
(`string`, default: `'same-origin'`).

This tells the plugin whether to send cookies to [Companion](/docs/companion).

#### `locale`

```js
export default {
	strings: {
		pluginNameUrl: 'Url',
	},
};
```