@googleworkspace/drive-picker-element v0.5.0

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 demos:

• React
• Svelte

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 and JSX
• Support
• Reference
  • <drive-picker/>
  • <drive-picker-docs-view/>

Install

Install using NPM or similar.

npm i @googleworkspace/drive-picker-element

A CDN version is also available. See the unpkg.

<script src="https://unpkg.com/@googleworkspace/drive-picker-element@0/dist/index.iife.min.js"></script>

Usage

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

Import the Component

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

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

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

Add the Component to Your HTML

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.

<drive-picker client-id="YOUR_CLIENT_ID" app-id="YOUR_APP_ID">
  <drive-picker-docs-view starred="true"></drive-picker-docs-view>
</drive-picker>

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

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

Use the oauth-token attribute

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.

<drive-picker app-id="YOUR_APP_ID" oauth-token="OAUTH_TOKEN"></drive-picker>

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

Listening to Events

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

<drive-picker client-id="YOUR_CLIENT_ID" app-id="YOUR_APP_ID">
  <drive-picker-docs-view starred="true"></drive-picker-docs-view>
</drive-picker>

<script>
  const element = document.querySelector("drive-picker");
  element.addEventListener("picker:authenticated", console.log);
  element.addEventListener("picker:picked", console.log);
  element.addEventListener("picker:canceled", console.log);
</script>

Event Details

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

{
  "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:authenticated" event returns the token as the event detail:

{
  "type": "picker:authenticated",
  "detail": {
    "token": "OMITTED"
  }
}

Controlling Visibility

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

<drive-picker client-id="YOUR_CLIENT_ID" app-id="YOUR_APP_ID"></drive-picker>

<script>
  const element = document.querySelector("drive-picker");
  element.visible = true;
</script>

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

React and JSX

To use the component in a React application, you can extend the global JSX namespace as follows:

import type {
  DrivePickerElement,
  DrivePickerDocsViewElement,
  DrivePickerElementProps,
  DrivePickerDocsViewElementProps,
} from "@googleworkspace/drive-picker-element";

declare global {
  namespace JSX {
    interface IntrinsicElements {
      "drive-picker": React.DetailedHTMLProps<
        React.HTMLAttributes<DrivePickerElement> & DrivePickerElementProps,
        DrivePickerElement
      >;
      "drive-picker-docs-view": React.DetailedHTMLProps<
        React.HTMLAttributes<DrivePickerDocsViewElement> &
          DrivePickerDocsViewElementProps,
        DrivePickerDocsViewElement
      >;
    }
  }
}

The above snippet can be added to a declaration file (e.g. app.d.ts) in your React project.

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

<drive-picker/>

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

Events

Slots

Properties

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

<drive-picker-docs-view/>

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

Attributes

Properties