# Vue File Picker

The [File Picker](https://www.npmjs.com/package/@apideck/file-picker-js) is an open-source, plug-and-play, component that connects to many cloud storage APIs and offers easy file uploads and downloads between your app and any cloud storage service.
This NPM package works with the [File Storage API](https://developers.apideck.com/apis/file-storage/reference) and allows your users to select, search and upload files to multiple services.

This guide will get you up and running with the File Picker component. To get started, follow these 3 steps:

- [Step 1: Setup Apideck](#step-1-setup-apideck)
- [Step 2: Create a session](#step-2-create-a-session)
- [Step 3: Add File Picker](#step-3-add-file-picker)

## Step 1: Setup Apideck

### Create an account

If you haven't already, head over to our [Signup page](https://www.apideck.com/signup?products=unify&source=docs-vue-file-picker) and create an account. Choose an application name and a subdomain. Afterward, you will be redirected to the Apideck dashboard.

### Enable Unified APIs and connectors

Go to the [Unified APIs](https://platform.apideck.com/configuration) page in the Apideck dashboard. Choose one or more Unified APIs to enable. You'll see a list of the available connectors for each Unified API. Choose a couple of connectors to enable. The Unified APIs and connectors you select become available to your users in [Vault](https://developers.apideck.com/apis/vault/reference).

### Get your API key and Application ID

Go to the [API Keys](https://platform.apideck.com/configuration/api-keys) page in the Apideck dashboard. Copy your application ID and API key.
If your API key ever gets compromised, you can regenerate it on this page.

![API keys overview](/get-started/api-keys.png)

## Step 2: Create a session

Vault lets your users (called consumers in Apideck) easily connect and configure integrations. You can create a consumer through a Vault session through the following endpoint https://developers.apideck.com/apis/vault/reference#tag/Sessions.

Most of the time, this is an ID of your internal data model that represents a user or account in your system. E.g., account:12345. If the consumer doesn't exist yet, Vault will upsert a consumer based on your ID.

> **Note 🚨**
>
> Session creation should always happen server-side to prevent token leakage.

Use the API call below to create a session for a consumer. This will return a Vault URL that you forward to a consumer to connect integrations.

```sh meta=terminal
curl --request POST \
  --url 'https://unify.apideck.com/vault/sessions' \
  --header 'Authorization: Bearer {API_KEY}' \
  --header 'x-apideck-app-id: {APP_ID}' \
  --header 'x-apideck-consumer-id: {CONSUMER_ID}' \
```

You can also use our Node SDK to create a session.

```sh meta=terminal
yarn add @apideck/unify
```

Below is an example of creating a Serverless Function to create a session inside a Next.js project:

```ts meta=/api/vault/sessions.ts
import { VercelRequest, VercelResponse } from '@vercel/node'
import { Apideck } from '@apideck/unify'

const createSession = async (_: VercelRequest, res: VercelResponse) => {
  const apideck = new Apideck({
    apiKey: process.env.API_KEY ?? '',
    appId: process.env.APP_ID ?? '',
    consumerId: 'test-consumer'
  })
  const { data } = await apideck.vault.sessions.create({
    session: {}
  })

  res.json(data)
}

export default createSession
```

The returned `data` object will include the `session_token` that you can use pass as the `token` prop to the `FilePicker` component.

## Step 3: Add the File Picker

### Package

```sh
npm install @apideck/vue-file-picker
```

### Usage

Pass the JWT you got from the Vault session to `@apideck/vue-file-picker`, call the slot prop `open` to open the FilePicker modal.

```vue
<script setup lang="ts">
import { FilePicker } from '@apideck/vue-file-picker'

const sessionJwt = 'REPLACE_WITH_SESSION_TOKEN'

function onSelect(file: File) {
  console.log('selected file:', file)
}
</script>

<template>
  <main>
    <FilePicker :token="sessionJwt" :on-select="onSelect" v-slot="filePickerProps">
      <button @click="filePickerProps.open()">Open</button>
    </FilePicker>
  </main>
</template>
```

If you want to get notified when the modal opens and closes, you can provide the `onReady` and `onClose` options.

```vue
<script setup lang="ts">
import { FilePicker } from '@apideck/vue-file-picker'

const sessionJwt = 'REPLACE_WITH_SESSION_TOKEN'

function onSelect(file: File) {
  console.log('selected file:', file)
}

function onClose() {
  console.log('closed!')
}

function onReady() {
  console.log('ready!')
}
</script>

<template>
  <main>
    <FilePicker
      :token="sessionJwt"
      :on-close="onClose"
      :on-ready="onReady"
      :on-select="onSelect"
      v-slot="filePickerProps"
    >
      <button @click="filePickerProps.open()">Open</button>
    </FilePicker>
  </main>
</template>
```

### Demo

The code block below shows a quick demo on how you could use the FilePicker component. Click the button to execute the code that's shown below. In the demo we use the `@apideck/file-picker-js` package, which can be used in any JavaScript application.

### Properties

| Property             | Type    | Required | Default             | Description                                                           |
| -------------------- | ------- | -------- | ------------------- | --------------------------------------------------------------------- |
| token                | string  | true     | -                   | The JSON Web Token returned from the Create Session call              |
| open                 | boolean | false    | false               | Opens the file picker if set to true                                  |
| on-close             | event   | false    | -                   | Function that gets called when the modal is closed                    |
| on-select            | event   | false    | -                   | The function that gets called when a file is selected                 |
| on-connection-select | event   | false    | -                   | The function that gets called when a connection is selected           |
| file-to-save         | file    | false    | -                   | Forces "Upload" mode to select the folder to upload the provided file |
| title                | string  | false    | Apideck File Picker | Title shown in the modal                                              |
| sub-title            | string  | false    | Select a file       | Subtitle shown in the modal                                           |
| show-attribution     | boolean | false    | true                | Show "Powered by Apideck" in the backdrop of the modal backdrop       |