uppy/docs/presets/remote-sources.mdx

---
sidebar_position: 1
slug: /remote-sources
---

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

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

# Remote sources

`@uppy/remote-sources` is a preset plugin (meaning it bundles and sets up other
plugins) to add all the available remote sources, such Instagram, Google Drive,
Dropbox, and others to Uppy Dashboard in one package.

:::note

Remote Sources requires Dashboard and automatically installs all its plugins to
it.

:::

## When should I use it?

`@uppy/remote-sources` aims to simplify the setup for adding Companion plugins,
when you want to share the configuration between plugins. If you want your users
to upload files from any of the remote sources that Uppy offers, this plugin is
recommended.

A [Companion](/docs/companion) instance is required for the Remote Sources
plugin to work. Companion handles authentication with the remote services (such
as Facebook, Dropbox, etc.), downloads the files, and uploads them to the
destination. 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/).

## Install

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

```shell
npm install @uppy/remote-sources
```

  </TabItem>

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

```shell
yarn add @uppy/remote-sources
```

  </TabItem>

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

## Use

```js {10} showLineNumbers
import Uppy from '@uppy/core';
import Dashboard from '@uppy/dashboard';
import RemoteSources from '@uppy/remote-sources';

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

new Uppy();
  .use(Dashboard);
  .use(RemoteSources, { companionUrl: 'https://your-companion-url' });
```

### Use with Transloadit

```js
import { COMPANION_URL, COMPANION_ALLOWED_HOSTS } from '@uppy/transloadit';
import RemoteSources from '@uppy/remote-sources';

uppy.use(RemoteSources, {
	companionUrl: COMPANION_URL,
	companionAllowedHosts: COMPANION_ALLOWED_HOSTS,
});
```

You may also hit rate limits, because the OAuth application is shared between
everyone using Transloadit.

To solve that, you can use your own OAuth keys with Transloadit’s hosted
Companion servers by using Transloadit Template Credentials. [Create a Template
Credential][template-credentials] on the Transloadit site. Select “Companion
OAuth” for the service, and enter the key and secret for the provider you want
to use. Then you can pass the name of the new credentials to that provider:

```js
import { COMPANION_URL, COMPANION_ALLOWED_HOSTS } from '@uppy/transloadit';
import RemoteSources from '@uppy/remote-sources';

uppy.use(RemoteSources, {
	companionUrl: COMPANION_URL,
	companionAllowedHosts: COMPANION_ALLOWED_HOSTS,
	companionKeysParams: {
		GoogleDrive: { key: '...', credentialsName: '...' },
		Dropbox: { key: '...', credentialsName: '...' },
		// ...etc
	},
});
```

## API

### Options

#### `id`

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

#### `sources`

List of remote sources that will be enabled (`array`, default:
`['Box', 'Dropbox', 'Facebook', 'GoogleDrive','Instagram', 'OneDrive', 'Unsplash', 'Url', 'Zoom']`).

You don’t need to specify them manually or change them, but if you want to alter
the order in which they appear in the Dashboard, or disable some sources, this
option is for you.

```js
uppy.use(RemoteSources, {
	companionUrl: 'https://your-companion-url',
	sources: ['Instagram', 'GoogleDrive', 'Unsplash', 'Url'],
});
```

#### `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 authorized URL(s)/URL pattern(s) from which OAuth responses should
be accepted (`string | RegExp | Array<string | RegExp>`, Default:
`companionUrl`).

This value can be a `string`, a `RegExp` object, or an array of both.

This is useful when you have your [Companion](/docs/companion) running on
several hosts. Otherwise, the default value, which is `companionUrl`, should do
fine.

#### `companionCookiesRule`

This option correlates to the [`Request.credentials` value][], which tells the plugin
whether to send cookies to [Companion](/docs/companion) (`string`, default: `same-origin`).

#### `target`

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

[`request.credentials` value]:
	https://developer.mozilla.org/en-US/docs/Web/API/Request/credentials
[template-credentials]:
	https://transloadit.com/docs/#how-to-create-template-credentials