YouTube Upload Widget


  1. Overview
  2. Requirements
  3. Getting started
  4. Loading an upload widget
  5. Operations
    1. Methods
    2. Events
  6. Known issues
  7. Revision history


The YouTube Upload Widget lets your website's visitors perform webcam uploads to YouTube. The support for webcam uploads sets the upload widget apart from other uploading options that YouTube APIs support. The widget uses HTML5's postMessage support to send messages back to your website regarding videos uploaded via the widget.

When the widget loads, it displays a button that you can click to record a webcam video. If the user elects to record a video, the widget displays a popup prompting the user to sign in.

This guide explains how to embed and customize the widget on your website so that users can upload videos. It also defines supported commands for setting video metadata. Finally, it explains the different types of callback notifications that the embedded widget sends and explains how to handle those notifications. For example, the widget sends callback notifications to inform your application when the user's webcam application changes state or when a video upload that was initiated through the widget has completed.

Note: The Upload Widget loads the same JavaScript file as the IFrame Player API. As such, an application that loads the JavaScript file to display an upload widget could also instantiate and control a YouTube player using the same code. The IFrame Player API Reference explains how to load and control a YouTube player.


The end user must be using a browser that supports the HTML5 postMessage feature to be able to handle the widget's callback notifications. Most modern browsers support postMessage, though Internet Explorer 7 does not support it. The widget still functions on some older browsers, but since the widget is not able to send messages to the hosting website, those browsers do not receive callbacks in response to events.

Any web page that uses the YouTube Upload Widget must also implement the following JavaScript function:

  • onYouTubeIframeAPIReady – The Upload Widget calls this function when the page has finished downloading the widget's JavaScript, which enables you to call commands and handle callbacks on your page. Thus, this function might create the upload widget that you want to display when the page loads.

Getting started

The sample HTML page below creates an embedded <iframe> that lets a user record a webcam video and subsequently upload it to YouTube.

<!DOCTYPE html>
    // 1. The 'widget' div element contains the upload widget.
    //    The 'player' div element contains the player IFrame.
    <div id="widget"></div>
    <div id="player"></div>

      // 2. Asynchronously load the Upload Widget and Player API code.
      var tag = document.createElement('script');
      tag.src = "https://www.youtube.com/iframe_api";
      var firstScriptTag = document.getElementsByTagName('script')[0];
      firstScriptTag.parentNode.insertBefore(tag, firstScriptTag);

      // 3. Define global variables for the widget and the player.
// The function loads the widget after the JavaScript code has
// downloaded and defines event handlers for callback notifications
// related to the widget. var widget; var player; function onYouTubeIframeAPIReady() { widget = new YT.UploadWidget('widget', { width: 500, events: { 'onUploadSuccess': onUploadSuccess, 'onProcessingComplete': onProcessingComplete } }); } // 4. This function is called when a video has been successfully uploaded. function onUploadSuccess(event) { alert('Video ID ' + event.data.videoId + ' was uploaded and is currently being processed.'); } // 5. This function is called when a video has been successfully processed. function onProcessingComplete(event) { player = new YT.Player('player', { height: 390, width: 640, videoId: event.data.videoId, events: {} }); } </script> </body> </html>

The numbered items in the list below provide more details about the comments in the sample above:

  1. The <div> tags in this section identify the location on the page where the JavaScript places the upload widget and the video player. The constructor for the widget, which is described below, identifies the <div> tag by its id to ensure that the JavaScript places the <iframe> in the proper location. As an alternative, you could also put the <iframe> element directly on the page. This option is explained later in the document.

  2. The code in this section loads the Upload Widget's JavaScript code. The example uses DOM modification to download the JavaScript file, thereby ensuring that the file is retrieved asynchronously. (The <script> tag's async attribute, which also enables asynchronous downloads, is not yet supported in all modern browsers as discussed in this article.)

  3. The onYouTubeIframeAPIReady function executes as soon as the widget's JavaScript code downloads. This portion of the code defines global variables for the widget and the player that you are embedding. The function loads the widget and specifies the functions to call if an onUploadSuccess or onProcessingComplete event fires.

  4. The onUploadSuccess function executes when a user successfully uploads a video to YouTube via the widget. The event.data.videoId field specifies the YouTube video ID of the newly uploaded video.

  5. The widget calls the onProcessingComplete function when an uploaded video is processed and viewable. Again, the event.data.videoId field specifies the video's YouTube video ID. In the sample event handler shown above, the function creates a player object so that the user can watch the new video.

Loading an upload widget

After the Upload Widget's JavaScript file loads, it calls the onYouTubeIframeAPIReady function, at which point you can construct a YT.UploadWidget object to insert an embedded uploader on your page. The HTML excerpt below shows the onYouTubeIframeAPIReady function from the example above:

var player;
function onYouTubeIframeAPIReady() {
  widget = new YT.UploadWidget('widget', {
    width: 500,
    events: {
      'onUploadSuccess': onUploadSuccess,
      'onProcessingComplete': onProcessingComplete

The constructor for the upload widget specifies the following parameters:

  1. The first parameter specifies either the DOM element or the id of the HTML element where the JavaScript inserts the <iframe> tag containing the widget.

    Specifically, the JavaScript replaces the specified element with the <iframe> element containing the widget. This could affect the layout of your page if the element being replaced has a different display style than the inserted <iframe> element. By default, an <iframe> displays as an inline-block element.

  2. The second parameter is an object that specifies widget options. The object contains the following properties:
    • width (number) – The width of the upload widget. The default value is 640.
    • height (number) – The height of the upload widget. If a parameter value is not specified, the height is set based on a constant fraction of the width.
    • events (object) – The object's properties identify the events that the widget fires and the functions (event listeners) that the widget calls when those events occur. In the example, the constructor indicates that the onUploadSuccess function executes when the onUploadSuccess event fires and that the onProcessingComplete function executes when the onProcessingComplete event fires.

As mentioned above, instead of writing an empty <div> element on your page, which the widget's JavaScript code then replaces with an <iframe> element, you could create the <iframe> tag yourself.

<iframe id="widget" type="text/html" width="640" height="390"
  src="https://www.youtube.com/upload_embed" frameborder="0"></iframe>

If you do write the <iframe> tag, then when you construct the YT.UploadWidget object, you do not need to specify values for the width and height, which are specified as attributes of the <iframe> tag.



The widget supports the following methods:

Returns the DOM node for the <iframe> that contains the upload widget.
widget.setSize(width:Number, height:Number):Object
Sets the size in pixels of the <iframe> that contains the widget.
widget.addEventListener(event:string, listener:Function|string):Object
Adds a listener function for the specified event. The listener can either be a reference to the function or specify the name of the function that executes when the specified event fires.

The Events section below identifies the different events that the widget might fire.
Removes the <iframe> containing the upload widget.


The widget fires events to notify your application of changes that are relevant to the widget. You can subscribe to events by adding event listeners when constructing the YT.UploadWidget object, and you can also use the addEventListener function.

The widget passes an event object as the sole argument to each of those functions. The event object has the following properties:

  • The event's target identifies the video player that corresponds to the event.

  • The event's data object specifies values relevant to the event. The object can specify the following values:

    • A videoId is a value that uniquely identifies a YouTube video.
    • A correlationId is a value that can be used to associate events. For example, an onUploadSuccess event might specify a correlationId without specifying a videoId since the latter might not have been assigned when the event fired. However, a subsequent event that specifies a videoId and a correlationId could be used to associate the two events.
    • The state field identifies the webcam application's status.

    Note that the onApiReady event does not specify a data property.

The following list defines the events that the widget fires:

This event fires when the internal command API, which enables you to set metadata for a newly uploaded video, is ready. The event handler for this event can call the following functions to set metadata for an uploaded video:
  • widget.setVideoTitle(title) – The title parameter is a string that specifies the video title.
  • widget.setVideoDescription(description); – The description parameter is a string that specifies the video description.
  • widget.setVideoKeywords(keyword1, keyword2, ..., keywordn); – The function takes a list of string parameters, each of which specifies a keyword for the video.
  • widget.setVideoPrivacy(privacy) – The privacy parameter is a string that specifies the initial privacy setting for the newly uploaded video. Valid values are public, unlisted, and private. The default setting is public.
This webcam-specific event fires whenever the webcam application's state changes. The event.data.state field of the object that the widget sends to your event listener function specifies an integer that corresponds to the webcam application's new state. Possible values are:
  • YT.UploadWidgetState.IDLE
  • YT.UploadWidgetState.PENDING
  • YT.UploadWidgetState.ERROR
  • YT.UploadWidgetState.PLAYBACK
  • YT.UploadWidgetState.RECORDING
  • YT.UploadWidgetState.STOPPED
This event fires when a video uploaded via the widget has been successfully processed and is ready to be viewed. The event's data object contains a videoId field and a correlationId field.

This event fires when a video has been successfully uploaded via the widget. The event's data object contains a correlationId and may contain a videoId.

This event fires when the YouTube video ID is available for a video that was uploaded via the widget. The event's data object contains a correlationId and a videoId.

This webcam-specific event fires when the user clicks the Cancel button on the webcam app.

Known issues

  • Users who have two or more open browser windows that both use the upload widget may experience problems with the widget freezing or becoming unresponsive in those windows.

  • The onApiReady event listener function's description defines a number of functions that can be used to set metadata for an uploaded video. Those functions really must be called from that event listener as there is a potential race condition if your application calls the metadata functions from any other function.

Revision history

This section lists YouTube Upload Widget changes and documentation updates. Subscribe to this changelog. Subscribe

May 7, 2014

This update contains the following changes:

  • As noted in the August 22, 2012, release notes, the widget does not currently support an option to upload existing video files to YouTube. With that in mind, the document has been updated to remove mentions of that functionality.

May 10, 2013

This update contains the following changes:

August 22, 2012

This update contains the following changes:

  • The webcamOnly property has been removed from the list of widget options that you can specify in the constructor for the upload widget. Previously, this property was documented as having a default value of false, which would mean that the widget would also display a button for uploading an existing video file. However, the option to upload an existing file is not currently supported, so the widget always only displays an option to record and upload a webcam video.

August 2, 2012

This update contains the following changes:

  • The definition of the onApiReady event has been updated to reflect support for the setVideoPrivacy function, which can be used to define the initial privacy setting for a newly uploaded video.

June 27, 2012

This update contains the following changes:

  • The YouTube Upload Widget launches as an experimental feature.

Back to top