@googleworkspace/drive-picker-element

!Release

Description

The [Google Drive Picker] web component offers a seamless way to integrate the Google Picker API into your web applications. This component is framework-agnostic, meaning it works effortlessly with React, Svelte, Vue, Angular, and more.

The Google Picker API is a JavaScript API that allows users to select or upload Google Drive files. This component acts as a "File Open" dialog, providing access to and interaction with files stored on Google Drive.

Explore the storybook demo to see the component in action.

See the framework specific components:

- React

Index

- Install
- Usage
- Import the Component
- Add the Component to Your HTML
- Use the oauth-token attribute
- Listening to Events
- Event Details
- Controlling Visibility
- React
- Content Security Policy (CSP)
- Support
- Reference
-
-

Install

Install using NPM or similar.

``sh
npm i @googleworkspace/drive-picker-element
`

A CDN version is also available. See the unpkg.

`html

`

Usage

To use the drive-picker component in your project, follow these steps:

$3

First, import the drive-picker component in your JavaScript file:

`js
import "@googleworkspace/drive-picker-element";
`

This isn't necessary if you're using the CDN version.

$3

Next, add the drive-picker component to your HTML file. Replace YOUR_CLIENT_ID and YOUR_APP_ID with your actual client ID and app ID.

> Note: You can find these values in the Google Cloud Console under "APIs & Services" > "Credentials". You can also follow this guide to create a new OAuth 2.0 client ID.

`html



`

> Note: If you wish to register the component with a different name, you can import the components individually and call customElements.define() manually:

`js
import {
DrivePickerElement,
DrivePickerDocsViewElement,
} from "@googleworkspace/drive-picker-element/drive-picker";
customElements.define("custom-drive-picker", DrivePickerElement);
customElements.define(
"custom-drive-picker-docs-view",
DrivePickerDocsViewElement,
);
`

$3

If you already have an OAuth token, you can pass it to the drive-picker component using the oauth-token attribute. This will authenticate the user without requiring them to sign in again.

`html

`

If you don't have an OAuth token, you can listen for the "picker-oauth-response" event to get the token after the user has authenticated. This library wraps the Google Identity Services library to make it easier to authenticate users.

$3

The drive-picker component emits several events that you can listen to. Here is an example of how to listen to these events:

`html





`

$3

Most of these events return the Picker ResponseObject as the event detail. For example, the "picker-picked" CustomEvent contains details about the selected files:

`js
{
"type": "picker-picked",
"detail": {
"action": "picked",
"docs": [
{
"id": "OMITTED",
"mimeType": "application/pdf",
"name": "OMITTED",
"url": "https://drive.google.com/file/d/OMITTED/view?usp=drive_web",
"sizeBytes": 12345
// ... other properties omitted
}
]
}
}
`

The "picker-oauth-response" event returns the OAuth token response as the event detail:

`js
{
"type": "picker-oauth-response",
"detail": {
"access_token": "OMITTED",
"expires_in": 3599,
"scope": "https://www.googleapis.com/auth/drive.file",
"token_type": "Bearer"
}
}
`

$3

To make the picker visible, set the visible property of the drive-picker element to true:

`html



`

After the picker dialog has been closed, the visible property will be reset to false.

$3

For React applications, we recommend using the official React wrapper package: @googleworkspace/drive-picker-react.

Please refer to the package documentation for usage instructions.

$3

This library dynamically loads the Google API scripts (https://apis.google.com/js/api.js and https://accounts.google.com/gsi/client) if they are not already present. This may violate strict CSP settings that disallow dynamic script injection or restrict script sources.

To use this library in a strict CSP environment:

1. Pre-load the scripts: Manually include the Google API scripts in your HTML using

`

2. Ensure global objects are available: The library checks for window.gapi and window.google.accounts.oauth2. If these are present, it skips the dynamic injection.

3. Allow Google domains in CSP: You must allow the picker's origin and other Google domains in your Content-Security-Policy. Here is a complete example:

`http
Content-Security-Policy:
default-src 'self';
script-src 'self' https://apis.google.com https://accounts.google.com;
frame-src 'self' https://docs.google.com https://drive.google.com https://accounts.google.com;
style-src 'self' 'unsafe-inline';
img-src 'self' https://*.googleusercontent.com;
connect-src 'self' https://*.googleapis.com;
font-src 'self' https://fonts.gstatic.com;
`

Notes:
- The frame-src domains are required for the Picker iframe and authentication. The exact domains may vary, but these are the most common.
- style-src: 'unsafe-inline' may be required for some styles injected by the Picker. For a stricter policy, you can use nonces.

Note for Chrome Extensions (Manifest V3):
The underlying Google Picker API relies on gapi, which is not supported in Manifest V3 extensions. Therefore, this library may not function in that environment regardless of CSP settings.

Support

To report issues or feature requests for the underlying Drive Picker, please use the Google Picker issue tracker. For all other issues, please use the GitHub issue tracker.

Reference

$3

The drive-picker web component provides a convenient way to declaratively
build
google.picker.Picker
by using the component attributes mapped to the corresponding methods of
google.picker.PickerBuilder.

#### Attributes

| Name | Type | Description |
| ------------------------ | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| app-id | string | The Google Drive app ID. See PickerBuilder.setAppId. |
| client-id | string | The OAuth 2.0 client ID. See Using OAuth 2.0 to Access Google APIs. |
| debounce-delay | number | The debounce delay in milliseconds before building the picker after an attribute change. |
| developer-key | string | The API key for accessing Google Picker API. See PickerBuilder.setDeveloperKey. |
| hide-title-bar | "default"\|"true"\|"false" | Hides the title bar of the picker if set to true. See PickerBuilder.hideTitleBar. |
| locale | string | The locale to use for the picker. See PickerBuilder.setLocale. |
| max-items | number | The maximum number of items that can be selected. See PickerBuilder.setMaxItems. |
| mine-only | boolean | If set to true, only shows files owned by the user. See PickerBuilder.enableFeature. |
| multiselect | boolean | Enables multiple file selection if set to true. See PickerBuilder.enableFeature. |
| nav-hidden | boolean | Hides the navigation pane if set to true. See PickerBuilder.enableFeature. |
| oauth-token | string | The OAuth 2.0 token for authentication. See PickerBuilder.setOAuthToken. |
| origin | string | The origin parameter for the picker. See PickerBuilder.setOrigin. |
| relay-url | string | The relay URL for the picker. See PickerBuilder.setRelayUrl. |
| scope | string | The OAuth 2.0 scope for the picker. The default is https://www.googleapis.com/auth/drive.file. See Drive API scopes. |
| title | string | The title of the picker. See PickerBuilder.setTitle. |
| hd | string | The hosted domain to restrict sign-in to. (Optional) See the hd field in the OpenID Connect docs. |
| include-granted-scopes | boolean | Enables applications to use incremental authorization. See TokenClientConfig.include_granted_scopes. |
| login-hint | string | An email address or an ID token 'sub' value. Google will use the value as a hint of which user to sign in. See the login_hint field in the OpenID Connect docs. |
| prompt | ""\|"none"\|"consent"\|"select_account" | A space-delimited, case-sensitive list of prompts to present the user. See TokenClientConfig.prompt |

#### Events

| Name | Type | Description |
| ----------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| picker-oauth-error | OAuthErrorEvent | Triggered when an error occurs in the OAuth flow. See the error guide. Note that the TokenResponse object can have error fields. |
| picker-oauth-response | OAuthResponseEvent | Triggered when an OAuth flow completes. See the token model guide. |
| picker-canceled | PickerCanceledEvent | Triggered when the user cancels the picker dialog. See ResponseObject. |
| picker-picked | PickerPickedEvent | Triggered when the user picks one or more items. See ResponseObject. |
| picker-error | PickerErrorEvent | Triggered when an error occurs. See ResponseObject. |

#### Slots

| Name | Description |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| default | The default slot contains View elements to display in the picker. Each View element should implement a property view of type google.picker.View. |

#### Properties

| Name | Type | Description |
| ------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| visible | boolean | Controls the visibility of the picker after the picker dialog has been closed. If any of the attributes change, the picker will be rebuilt and the visibility will be reset. |
| tokenClientConfig | \Omit< | |

``
google.accounts.oauth2.TokenClientConfig,
"callback" \| "error_callback" > | |
``

$3

The drive-picker-docs-view element is used to define a google.picker.DocsView.

#### Attributes

| Name | Type | Description |
| ----------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| enable-drives | "default"\|"true"\|"false" | Whether to allow the user to select files from shared drives. See DocsView.enableDrives. |
| file-ids | string | A comma-separated list of file IDs to filter the view. See View.setFileIds. |
| include-folders | "default"\|"true"\|"false" | Whether to include folders in the view. See DocsView.includeFolders. |
| mime-types | string | A comma-separated list of MIME types to filter the view. See View.setMimeTypes. |
| mode | string | The mode of the view. See DocsViewMode. |
| owned-by-me | "default"\|"true"\|"false" | Whether to show files owned by the user. See DocsView.ownedByMe. |
| parent | string | The ID of the folder to view. See DocsView.setParent. |
| query | string | The query string to filter the view. See View.setQuery. |
| select-folder-enabled | "default"\|"true"\|"false" | Whether to allow the user to select folders. See DocsView.selectFolderEnabled. |
| starred | "default"\|"true"\|"false" | Whether to show starred files. See DocsView.starred. |
| view-id | string | The keyof typeof google.picker.ViewId. For example, "DOCS", which is equivalent to google.picker.ViewId.DOCS. See ViewId. |

#### Properties

| Name | Type | Description |
| ------ | ------------------------ | ------------------------------------------------------------------------ |
| view | google.picker.DocsView` | Gets the Google Drive Picker view based on the current attribute values. |

[Google Drive Picker]: https://developers.google.com/drive/picker/guides/overview
[Google Drive Picker Reference]: https://developers.google.com/drive/picker/reference/picker