Revision 437553 of Blob

  • Revision slug: Web/API/Blob
  • Revision title: Blob
  • Revision id: 437553
  • Created:
  • Creator: tschneidereit
  • Is current revision? No
  • Comment

Revision Content

A Blob object represents a file-like object of immutable, raw data. Blobs represent data that isn't necessarily in a JavaScript-native format. The {{ domxref("File") }} interface is based on Blob, inheriting blob functionality and expanding it to support files on the user's system.

An easy way to construct a Blob is by invoking the {{ domxref("Blob") }} constuctor. Another way is to use the slice() method to create a blob that contains a subset of another blob's data.

Note: Be aware that the slice() method has vendor prefixes on some browsers and versions: blob.mozSlice() for Firefox 12 and earlier and blob.webkitSlice() in Safari. An old version of the slice() method, without vendor prefixes, had different semantics, and is obsolete.
Note: Some browsers offer {{ domxref("BlobBuilder") }}, which lets you iteratively append data to a blob, then retrieve the completed blob when you're ready to use it for something. However, BlobBuilder is not available in every browsers and all BlobBuilder implementations have vendor prefixes. And it is deprecated in favor of the Blob constructor. You should use Blob constructor whenever possible.

Properties

Property Type Description
size unsigned long long The size, in bytes, of the data contained in the Blob object. Read only.
type {{ domxref("DOMString") }} An ASCII-encoded string, in all lower case, indicating the MIME type of the data contained in the Blob. If the type is unknown, this string is empty. Read only.

Constructor

Blob Blob(
  [optional] Array parts,
  [optional] BlobPropertyBag properties
);

Parameters

parts
An Array of data objects to put into the new Blob object. This can be any number of ArrayBuffer, ArrayBufferView (typed array), {{ domxref("Blob") }}, or {{ domxref("DOMString") }} objects, in any order.
properties
An object that provides the properties for the new Blob. See the BlobPropertyBag section.

Methods

slice()

Returns a new Blob object containing the data in the specified range of bytes of the source Blob.

Blob slice(
  optional long long start,
  optional long long end,
  optional DOMString contentType
};

Parameters

start {{ optional_inline() }}
An index into the Blob indicating the first byte to copy into the new Blob. If you specify a negative value, it's treated as an offset from the end of the string toward the beginning. For example, -10 would be the 10th from last byte in the Blob. The default value is 0.
end {{ optional_inline() }}
An index into the Blob indicating the last byte to copy into the new Blob. If you specify a negative value, it's treated as an offset from the end of the string toward the beginning. For example, -10 would be the 10th from last byte in the Blob. The default value is size.
contentType {{ optional_inline() }}
The content type to assign to the new Blob; this will be the value of its type property. The default value is an empty string.

Return value

A new Blob object containing the specified data from the source Blob.

Notes

If you specify a value for start that is larger than the size of the source Blob, the returned Blob has size 0 and contains no data.

BlobPropertyBag

An object which contains two members: type and endings.

type
Corresponds to the type property.
endings {{Non-standard_inline()}}
Corresponds to the endings parameter of the {{ domxref("BlobBuilder","BlobBuilder","append()") }}. This can be either "transparent" or "native".

Blob constructor example usage

The following code:

var aFileParts = ["<a id=\"a\"><b id=\"b\">hey!<\/b><\/a>"];
var oMyBlob = new Blob(aFileParts, { "type" : "text\/xml" }); // the blob

is equivalent to:

var oBuilder = new BlobBuilder();
var aFileParts = ['<a id="a"><b id="b">hey!</b></a>'];
oBuilder.append(aFileParts[0]);
var oMyBlob = oBuilder.getBlob("text/xml"); // the blob

The {{ domxref("BlobBuilder") }} interface offers another way to create Blobs, but is now deprecated and should no longer be used.

Example for creating a URL to a typed array using a blob

The following code:

var typedArray = GetTheTypedArraySomehow();
var blob = new Blob([typedArray], {type: "application/octet-binary"}); // pass a useful mime type here
var url = URL.createObjectURL(blob);
// url will be something like: blob:d3958f5c-0777-0845-9dcf-2cb28783acaf
// now you can use the url in any context that regular URLs can be used in, for example img.src, etc.

Example for extracting data from a Blob

The only way to read content from a Blob is to use a FileReader. The following code reads the content of a Blob as a typed array.

var reader = new FileReader();
reader.addEventListener("loadend", function() {
   // reader.result contains the contents of blob as a typed array
});
reader.readAsArrayBuffer(blob);

By using other methods of FileReader, it is possible to read the contents of a Blob as a string or a data URL.

Browser compatibility

{{ CompatibilityTable() }}

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
Basic support 5 4 10 11.10 5.1
slice()

21
10 {{ property_prefix("webkit") }}‡

13
5 {{ property_prefix("moz") }}‡
10 12 5.1 (534.29) {{ property_prefix("webkit") }}
Blob() constructor 20 {{ CompatGeckoDesktop("13.0") }} 10 12.10 6 (536.10)
Feature Android Firefox Mobile (Gecko) IE Phone Opera Mobile Safari Mobile
Basic support {{ CompatUnknown() }} {{ CompatGeckoMobile("13.0") }} {{ CompatUnknown() }} {{ CompatUnknown() }} {{ CompatUnknown() }}

Notes on the slice() implementations

The slice() method had initially taken length as the second argument to indicate the number of bytes to copy into the new Blob. If you specified values such that start + length exceeded the size of the source Blob, the returned Blob contained data from the start index to the end of the source Blob.

That version of the slice() was implemented in Firefox 4, WebKit, and Opera 11.10. However, since that syntax is differed from Array.slice() and String.slice(), Gecko and WebKit removed support and added support for the new syntax as {{ manch("mozSlice") }}/Blob.webkitSlice.

Starting in Gecko 13.0 {{ geckoRelease("13.0") }} and Chrome 21, {{ manch("slice") }} is no longer prefixed.‡

Gecko notes

Prior to Gecko 12.0 {{ geckoRelease("12.0") }}, there was a bug that affected the behavior of {{ manch("slice") }}; it did not work for start and end positions outside the range of signed 64-bit values; it has now been fixed to support unsigned 64-bit values.

See also

  • {{ spec("http://www.w3.org/TR/FileAPI/#dfn-Blob", "File API Specification: Blob", "WD") }}
  • {{ spec("http://dev.w3.org/2006/webapi/FileAPI/#dfn-Blob", "File API Specification: Blob", "ED") }}
  • {{ domxref("BlobBuilder") }}
  • {{ domxref("File") }}
  • {{ domxref("XMLHttpRequest/FormData", "FormData") }}

{{ languages( { "en": "en/DOM/Blob", "ja": "ja/DOM/Blob" } ) }}

Revision Source

<p>A <code>Blob</code> object represents a file-like object of immutable, raw data. Blobs represent data that isn't necessarily in a JavaScript-native format. The {{ domxref("File") }} interface is based on <code>Blob</code>, inheriting blob functionality and expanding it to support files on the user's system.</p>
<p>An easy way to construct a <code>Blob</code> is by invoking the {{ domxref("Blob") }} constuctor. Another way is to use the <code>slice()</code> method to create a blob that contains a subset of another blob's data.</p>
<div class="note">
  <strong>Note:</strong> Be aware that the <code>slice()</code> method has vendor prefixes on some browsers and versions: <code>blob.mozSlice()</code> for Firefox 12 and earlier and <code>blob.webkitSlice()</code> in Safari. An old version of the <code>slice()</code> method, without vendor prefixes, had different semantics, and is obsolete.</div>
<div class="note">
  <strong>Note:</strong> Some browsers offer {{ domxref("BlobBuilder") }}, which lets you iteratively append data to a blob, then retrieve the completed blob when you're ready to use it for something. However, <code>BlobBuilder</code> is not available in every browsers and all <code>BlobBuilder</code> implementations have vendor prefixes. And it is deprecated in favor of the <code>Blob</code> constructor. You should use <code>Blob</code> constructor whenever possible.</div>
<h2 id="Properties">Properties</h2>
<table class="standard-table">
  <tbody>
    <tr>
      <td class="header">Property</td>
      <td class="header">Type</td>
      <td class="header">Description</td>
    </tr>
    <tr>
      <td><code>size</code></td>
      <td><code>unsigned long long</code></td>
      <td>The size, in bytes, of the data contained in the <code>Blob</code> object. <strong>Read only.</strong></td>
    </tr>
    <tr>
      <td><code>type</code></td>
      <td>{{ domxref("DOMString") }}</td>
      <td>An ASCII-encoded string, in all lower case, indicating the MIME&nbsp;type of the data contained in the <code>Blob</code>. If the type is unknown, this string is empty. <strong>Read only.</strong></td>
    </tr>
  </tbody>
</table>
<h2 id="Constructor">Constructor</h2>
<pre class="syntaxbox">
Blob Blob(
&nbsp;&nbsp;[optional] Array parts,
&nbsp;&nbsp;[optional] BlobPropertyBag properties
);
</pre>
<h3 id="Parameters">Parameters</h3>
<dl>
  <dt>
    <code>parts</code></dt>
  <dd>
    An <a href="/en/JavaScript/Reference/Global_Objects/Array" title="Array"><code>Array</code></a> of data objects to put into the new <code>Blob</code> object. This can be any number of <code><a href="/en/JavaScript_typed_arrays/ArrayBuffer#ArrayBuffer()" title="en/JavaScript_typed_arrays/ArrayBuffer#ArrayBuffer()">ArrayBuffer</a>, <a href="/en-US/docs/JavaScript_typed_arrays/ArrayBufferView" title="/en-US/docs/JavaScript_typed_arrays/ArrayBufferView">ArrayBufferView</a></code> (typed array), {{ domxref("Blob") }}, or {{ domxref("DOMString") }} objects, in any order.</dd>
  <dt>
    <code>properties</code></dt>
  <dd>
    An object that provides the properties for the new <code>Blob</code>. See the <a href="/en/DOM/Blob#BlobPropertyBag" title="Blob"><code>BlobPropertyBag</code></a> section.</dd>
</dl>
<h2 id="Methods">Methods</h2>
<h3 id="slice()">slice()</h3>
<p>Returns a new <code>Blob</code> object containing the data in the specified range of bytes of the source <code>Blob</code>.</p>
<pre>
Blob slice(
  optional long long start,
  optional long long end,
  optional DOMString contentType
};
</pre>
<h4 id="Parameters">Parameters</h4>
<dl>
  <dt>
    <code>start</code> {{ optional_inline() }}</dt>
  <dd>
    An index into the <code>Blob</code> indicating the first byte to copy into the new <code>Blob</code>. If you specify a negative value, it's treated as an offset from the end of the string toward the beginning. For example, -10 would be the 10th from last byte in the <code>Blob</code>. The default value is 0.</dd>
  <dt>
    <code>end</code> {{ optional_inline() }}</dt>
  <dd>
    An index into the <code>Blob</code> indicating the last byte to copy into the new <code>Blob</code>. If you specify a negative value, it's treated as an offset from the end of the string toward the beginning. For example, -10 would be the 10th from last byte in the <code>Blob</code>. The default value is <code>size</code>.</dd>
  <dt>
    <code>contentType</code> {{ optional_inline() }}</dt>
  <dd>
    The content type to assign to the new <code>Blob</code>; this will be the value of its <code>type</code> property. The default value is an empty string.</dd>
</dl>
<h4 id="Return_value">Return value</h4>
<p>A new <code>Blob</code> object containing the specified data from the source <code>Blob</code>.</p>
<h4 id="Notes">Notes</h4>
<p>If you specify a value for <code>start</code> that is larger than the size of the source <code>Blob</code>, the returned <code>Blob</code> has size 0 and contains no data.</p>
<h2 id="BlobPropertyBag">BlobPropertyBag</h2>
<p>An object which contains two members: <code>type</code> and <code>endings</code>.</p>
<dl>
  <dt>
    <code>type</code></dt>
  <dd>
    Corresponds to the <code>type</code> property.</dd>
  <dt>
    <code>endings</code> {{Non-standard_inline()}}</dt>
  <dd>
    Corresponds to the <code>endings</code> parameter of the {{ domxref("BlobBuilder","BlobBuilder","append()") }}. This can be either "transparent" or "native".</dd>
</dl>
<h2 id="Blob_constructor_example_usage">Blob constructor example usage</h2>
<p>The following code:</p>
<pre class="brush: js">
var aFileParts = ["&lt;a id=\"a\"&gt;&lt;b id=\"b\"&gt;hey!&lt;\/b&gt;&lt;\/a&gt;"];
var oMyBlob = new Blob(aFileParts, { "type" : "text\/xml" }); // the blob
</pre>
<p>is equivalent to:</p>
<pre class="brush: js">
var oBuilder = new BlobBuilder();
var aFileParts = ['&lt;a id="a"&gt;&lt;b id="b"&gt;hey!&lt;/b&gt;&lt;/a&gt;'];
oBuilder.append(aFileParts[0]);
var oMyBlob = oBuilder.getBlob("text/xml"); // the blob
</pre>
<p>The {{ domxref("BlobBuilder") }} interface offers another way to create <code>Blob</code>s, but is now deprecated and should no longer be used.</p>
<h2 id="Example_for_creating_a_URL_to_a_typed_array_using_a_blob">Example for creating a URL to a typed array using a blob</h2>
<p>The following code:</p>
<pre class="brush: js">
var typedArray = GetTheTypedArraySomehow();
var blob = new Blob([typedArray], {type: "application/octet-binary"}); // pass a useful mime type here
var url = URL.createObjectURL(blob);
// url will be something like: blob:d3958f5c-0777-0845-9dcf-2cb28783acaf
// now you can use the url in any context that regular URLs can be used in, for example img.src, etc.
</pre>
<h2 id="Example_for_extracting_data_from_a_Blob">Example for extracting data from a Blob</h2>
<p>The only way to read content from a Blob is to use a <a href="/en-US/docs/Web/API/FileReader" title="/en-US/docs/Web/API/FileReader">FileReader</a>. The following code reads the content of a Blob as a typed array.</p>
<pre class="brush: js">
var reader = new FileReader();
reader.addEventListener("loadend", function() {
   // reader.result contains the contents of blob as a typed array
});
reader.readAsArrayBuffer(blob);</pre>
<p>By using other methods of <a href="/en-US/docs/Web/API/FileReader" title="/en-US/docs/Web/API/FileReader">FileReader</a>, it is possible to read the contents of a Blob as a string or a data URL.</p>
<h2 id="Browser_compatibility">Browser compatibility</h2>
<p>{{ CompatibilityTable() }}</p>
<div id="compat-desktop">
  <table class="compat-table">
    <tbody>
      <tr>
        <th>Feature</th>
        <th>Chrome</th>
        <th>Firefox (Gecko)</th>
        <th>Internet Explorer</th>
        <th>Opera</th>
        <th>Safari (WebKit)</th>
      </tr>
      <tr>
        <td>Basic support</td>
        <td>5</td>
        <td>4</td>
        <td>10</td>
        <td>11.10</td>
        <td>5.1</td>
      </tr>
      <tr>
        <td><code>slice()</code></td>
        <td>
          <p>21<br />
            10 {{ property_prefix("webkit") }}‡</p>
        </td>
        <td>13<br />
          5 {{ property_prefix("moz") }}‡</td>
        <td>10</td>
        <td>12</td>
        <td>5.1 (<a class="external" href="http://trac.webkit.org/changeset/83873">534.29</a>) {{ property_prefix("webkit") }}</td>
      </tr>
      <tr>
        <td><code>Blob()</code> constructor</td>
        <td>20</td>
        <td>{{ CompatGeckoDesktop("13.0") }}</td>
        <td>10</td>
        <td>12.10</td>
        <td>6 (<a class="external" href="http://trac.webkit.org/changeset/115582">536.10</a>)</td>
      </tr>
    </tbody>
  </table>
</div>
<div id="compat-mobile">
  <table class="compat-table">
    <tbody>
      <tr>
        <th>Feature</th>
        <th>Android</th>
        <th>Firefox Mobile (Gecko)</th>
        <th>IE&nbsp;Phone</th>
        <th>Opera Mobile</th>
        <th>Safari Mobile</th>
      </tr>
      <tr>
        <td>Basic support</td>
        <td>{{ CompatUnknown() }}</td>
        <td>{{ CompatGeckoMobile("13.0") }}</td>
        <td>{{ CompatUnknown() }}</td>
        <td>{{ CompatUnknown() }}</td>
        <td>{{ CompatUnknown() }}</td>
      </tr>
    </tbody>
  </table>
</div>
<h3 id="Notes_on_the_slice()_implementations">Notes on the slice() implementations</h3>
<p>The <code>slice()</code> method had initially taken <code>length</code> as the second argument to indicate the number of bytes to copy into the new <code>Blob</code>. If you specified values such that <code>start + length</code> exceeded the size of the source <code>Blob</code>, the returned <code>Blob</code> contained data from the start index to the end of the source <code>Blob</code>.</p>
<p>That version of the <code>slice()</code> was implemented in <a class="link-https" href="https://hg.mozilla.org/mozilla-central/rev/1b3947ed93c6">Firefox 4</a>, <a class="external" href="http://trac.webkit.org/changeset/55670">WebKit</a>, and <a class="external" href="http://www.opera.com/docs/specs/presto28/file/#blob">Opera 11.10</a>. However, since that syntax is differed from <a href="/en/JavaScript/Reference/Global_Objects/Array/slice" title="en/JavaScript/Reference/Global Objects/Array/slice"><code>Array.slice()</code></a> and <a href="/en/JavaScript/Reference/Global_Objects/String/slice" title="en/JavaScript/Reference/Global Objects/String/slice"><code>String.slice()</code></a>, Gecko and WebKit removed support and added support for the new syntax as {{ manch("mozSlice") }}/<a class="external" href="http://trac.webkit.org/changeset/83873"><code>Blob.webkitSlice</code></a>.</p>
<p>Starting in Gecko 13.0 {{ geckoRelease("13.0") }} and Chrome 21, {{ manch("slice") }} is no longer prefixed.‡</p>
<h3 id="Gecko_notes">Gecko notes</h3>
<p>Prior to Gecko 12.0 {{ geckoRelease("12.0") }}, there was a bug that affected the behavior of {{ manch("slice") }}; it did not work for <code>start</code> and end positions outside the range of signed 64-bit values; it has now been fixed to support unsigned 64-bit values.</p>
<h2 id="See_also">See also</h2>
<ul>
  <li>{{ spec("http://www.w3.org/TR/FileAPI/#dfn-Blob", "File API&nbsp;Specification:&nbsp;Blob", "WD") }}</li>
  <li>{{ spec("http://dev.w3.org/2006/webapi/FileAPI/#dfn-Blob", "File API Specification: Blob", "ED") }}</li>
  <li>{{ domxref("BlobBuilder") }}</li>
  <li>{{ domxref("File") }}</li>
  <li>{{ domxref("XMLHttpRequest/FormData", "FormData") }}</li>
</ul>
<p>{{ languages( { "en": "en/DOM/Blob", "ja": "ja/DOM/Blob" } ) }}</p>
Revert to this revision