<p><a href="https://www.npmjs.com/package/wholescreen.js"><img src="https://img.shields.io/npm/v/wholescreen.js.svg" alt=""></a>
<a href="https://travis-ci.org/friday/wholescreen/branches"><img src="https://img.shields.io/travis/friday/wholescreen.svg" alt=""></a>
<a href="https://cdn.jsdelivr.net/npm/wholescreen.js/dist/"><img src="https://img.shields.io/bundlephobia/minzip/wholescreen.js.svg" alt=""></a>
<a href="https://github.com/friday/wholescreen/blob/master/LICENCE"><img src="https://img.shields.io/github/license/friday/wholescreen.svg" alt=""></a>
<a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/npm/types/wholescreen.js.svg" alt=""></a>
<a href="https://greenkeeper.io/"><img src="https://badges.greenkeeper.io/friday/wholescreen.svg" alt="Greenkeeper badge"></a></p>
<h1 id="id-wholescreenjs">wholescreen.js</h1>
<p>Tiny wrapper (~40 lines of code) for the <a href="https://developer.mozilla.org/en/DOM/Using_full-screen_mode">Fullscreen API</a>. </p>
<ul>
<li>Handles all vendor prefixes for you</li>
<li>Has a simple <a href="#api">API</a> that resembles the standard API</li>
<li>Supports <a href="https://github.com/umdjs/umd">UMD</a>, standalone ES6 modules, require.js and AMD as separate files so you can import it anwhere.</li>
<li>Comes with TypeScript definitions (since it's written in TypeScript)</li>
<li>Detects each of the browser properties individually, meaning wider support, and safer for browser changes. All while using less code.</li>
<li>Probably the smallest Fullscreen API wrapper (but they're all pretty small)</li>
</ul>
<h2 id="id-installation">Installation</h2>
<pre><code class="hljs language-bash">npm install --save wholescreen.js
</code></pre>
<p>Or</p>
<pre><code class="hljs language-bash">yarn add wholescreen.js
</code></pre>
<p>Or you can use the <a href="https://www.jsdelivr.com/package/npm/wholescreen.js">jsdelivr CDN</a></p>
<pre><code class="hljs language-html"><span class="hljs-tag"><<span class="hljs-name">script</span> <span class="hljs-attr">src</span>=<span class="hljs-string">"https://cdn.jsdelivr.net/npm/wholescreen.js"</span>></span><span class="hljs-tag"></<span class="hljs-name">script</span>></span>
</code></pre>
<h2 id="id-usage-example">Usage example</h2>
<pre><code class="hljs language-js"><span class="hljs-keyword">import</span> wholescreen <span class="hljs-keyword">from</span> <span class="hljs-string">'wholescreen.js'</span>;
<span class="hljs-keyword">const</span> element = <span class="hljs-variable language_">document</span>.<span class="hljs-title function_">querySelector</span>(<span class="hljs-string">'.some-element'</span>);
<span class="hljs-comment">// Check for support</span>
<span class="hljs-keyword">if</span> (wholescreen.<span class="hljs-property">supported</span>) {
<span class="hljs-comment">// listen to changes</span>
wholescreen.<span class="hljs-title function_">on</span>(<span class="hljs-string">'change'</span>, <span class="hljs-function">() =></span> {
<span class="hljs-comment">// Log change based on `wholescreen.active`</span>
<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">`Fullscreen <span class="hljs-subst">${wholescreen.active ? <span class="hljs-string">'enabled'</span> : <span class="hljs-string">'disabled'</span>}</span>`</span>)
});
<span class="hljs-comment">// Activate fullscreen mode on button click</span>
<span class="hljs-comment">// You should only request fullscreen from events like this, or browsers will deny the request.</span>
<span class="hljs-variable language_">document</span>.<span class="hljs-title function_">querySelector</span>(<span class="hljs-string">'.button'</span>).<span class="hljs-title function_">addEventListener</span>(<span class="hljs-string">'click'</span>, <span class="hljs-function">() =></span> {
<span class="hljs-comment">// If you pass an element as the second argument the element will fullscreen instead of the window</span>
wholescreen.<span class="hljs-title function_">request</span>();
});
}
</code></pre>
<h2 id="id-api">API</h2>
<p>The API was designed to generally use the same names as the standard API (without the word <code>fullscreen</code> in everything since it's implied). There is one exception: <code>fullscreenEnabled</code> was renamed to <code>supported</code>, to avoid the misleading standard name. It also has a couple of useful additions over the standard API.</p>
<h3 id="id-getters">Getters</h3>
<div class="table-responsive"><table class="table table-striped"><tr>
<th>Property</th>
<th>type</th>
<th>Description</th>
</tr>
<tr>
<td><code>supported</code></td>
<td><code>boolean</code></td>
<td>Check <a href="https://caniuse.com/#feat=fullscreen">device / browser support</a> and if the window has permission to use fullscreen (requires special parameter for iframes)</td>
</tr>
<tr>
<td><code>active</code></td>
<td><code>boolean</code></td>
<td>Check if an element is currently fullscreened</td>
</tr>
<tr>
<td><code>element</code></td>
<td><code>Node</code></td>
<td>The dom node (element) currently fullscreened (or <code>null</code> if none)</td>
</tr>
</table></div><h3 id="id-methods">Methods</h3>
<div class="table-responsive"><table class="table table-striped"><tr>
<th>Method</th>
<th>arguments</th>
<th>Description</th>
</tr>
<tr>
<td><code>request()</code></td>
<td><code>element</code></td>
<td>Activate fullscreen for the element, or the window if the <code>element</code> argument is missing</td>
</tr>
<tr>
<td><code>toggle()</code></td>
<td><code>element</code>, <code>enable</code></td>
<td>Toggle fullscreen for the element. Will toggle based on the optional <code>enable</code> argument if present, otherwise it will reverse <code>active</code>. If another element is fullscreened, it will restore it first</td>
</tr>
<tr>
<td><code>exit()</code></td>
<td>-</td>
<td>Exit fullscreen</td>
</tr>
<tr>
<td><code>on()</code></td>
<td><code>type</code>, <code>listener</code>, <code>options</code></td>
<td>Listen for wholescreen events. Works exactly like <a href="https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener">addEventListener</a>, except it (only) supports custom wholescreen event types <code>change</code> and <code>error</code></td>
</tr>
<tr>
<td><code>off()</code></td>
<td><code>type</code>, <code>listener</code>, <code>options</code></td>
<td>Remove wholescreen event listener. Works exactly like <a href="https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/removeEventListener">removeEventListener</a>, except it (only) supports custom wholescreen event types <code>change</code> and <code>error</code></td>
</tr>
</table></div><h3 id="id-browser-api">Browser API</h3>
<p>If you need to get the original method and property names for the current browser, these are available as <code>wholescreen.events</code> and <code>wholescreen.props</code></p>
<h2 id="id-support">Support</h2>
<p><a href="https://caniuse.com/#feat=fullscreen">Browsers support</a></p>
<h2 id="id-alternatives">Alternatives</h2>
<ul>
<li><a href="https://github.com/sindresorhus/screenfull.js">screenfull.js</a> - The first and most well used Fullscreen API wrapper. Uses commonjs module declaration. The wholescreen.js API is very similar to screenfull.js (not by intention). screenfull also support the legacy syntax with an additional optional argument for allowing keyboard input.</li>
<li><a href="https://github.com/rafrex/fscreen">fscreen</a> - Small alternative. Handles all the common prefixes, but not the older Safari ones (you can most likely do without them). Uses es6-module declaration. The API is more verbose than screenfull.js and wholescreen.js</li>
</ul>