Add support for options (#182)

Co-authored-by: Sindre Sorhus <sindresorhus@gmail.com>
sindresorhus · Dec 24, 2020 · 0092521 · 0092521
1 parent 759746d
commit 0092521
Show file tree

Hide file tree

Showing 6 changed files with 58 additions and 18 deletions.
diff --git a/dist/screenfull.d.ts b/dist/screenfull.d.ts
@@ -48,6 +48,7 @@ declare namespace screenfull {
 		Keep in mind that the browser will only enter fullscreen when initiated by user events like click, touch, key.
 
 		@param element - Default is `<html>`. If called with another element than the currently active, it will switch to that if it's a decendant.
+		@param options - [`FullscreenOptions`](https://developer.mozilla.org/en-US/docs/Web/API/FullscreenOptions).
 		@returns A promise that resolves after the element enters fullscreen.
 
 		@example
@@ -70,6 +71,15 @@ declare namespace screenfull {
 			}
 		});
 
+		// Fullscreen an element with options
+		const element = document.getElementById('target');
+
+		document.getElementById('button').addEventListener('click', () => {
+			if (screenfull.isEnabled) {
+				screenfull.request(element, {navigationUI: 'hide'});
+			}
+		});
+
 		// Fullscreen an element with jQuery
 		const element = $('#target')[0]; // Get DOM element from jQuery collection
 
@@ -80,7 +90,7 @@ declare namespace screenfull {
 		});
 		```
 		*/
-		request(element?: Element): Promise<void>;
+		request(element?: Element, options?: FullscreenOptions): Promise<void>;
 
 		/**
 		Brings you out of fullscreen.
@@ -92,6 +102,8 @@ declare namespace screenfull {
 		/**
 		Requests fullscreen if not active, otherwise exits.
 
+		@param element - Default is `<html>`. If called with another element than the currently active, it will switch to that if it's a decendant.
+		@param options - [`FullscreenOptions`](https://developer.mozilla.org/en-US/docs/Web/API/FullscreenOptions).
 		@returns A promise that resolves after the element enters/exits fullscreen.
 
 		@example
@@ -105,7 +117,7 @@ declare namespace screenfull {
 		});
 		```
 		*/
-		toggle(element?: Element): Promise<void>;
+		toggle(element?: Element, options?: FullscreenOptions): Promise<void>;
 
 		/**
 		Add a listener for when the browser switches in and out of fullscreen or when there is an error.

diff --git a/dist/screenfull.js b/dist/screenfull.js
@@ -1,6 +1,6 @@
 /*!
 * screenfull
-* v5.0.2 - 2020-02-13
+* v5.0.2 - 2020-10-27
 * (c) Sindre Sorhus; MIT License
 */
 (function () {
@@ -82,7 +82,7 @@
 	};
 
 	var screenfull = {
-		request: function (element) {
+		request: function (element, options) {
 			return new Promise(function (resolve, reject) {
 				var onFullScreenEntered = function () {
 					this.off('change', onFullScreenEntered);
@@ -93,7 +93,7 @@
 
 				element = element || document.documentElement;
 
-				var returnPromise = element[fn.requestFullscreen]();
+				var returnPromise = element[fn.requestFullscreen](options);
 
 				if (returnPromise instanceof Promise) {
 					returnPromise.then(onFullScreenEntered).catch(reject);
@@ -121,8 +121,8 @@
 				}
 			}.bind(this));
 		},
-		toggle: function (element) {
-			return this.isFullscreen ? this.exit() : this.request(element);
+		toggle: function (element, options) {
+			return this.isFullscreen ? this.exit() : this.request(element, options);
 		},
 		onchange: function (callback) {
 			this.on('change', callback);

diff --git a/dist/screenfull.min.js b/dist/screenfull.min.js
diff --git a/readme.md b/readme.md
@@ -92,6 +92,18 @@ document.getElementById('button').addEventListener('click', () => {
 });
 ```
 
+#### Hide navigation user-interface on mobile devices
+
+```js
+const element = document.getElementById('target');
+
+document.getElementById('button').addEventListener('click', () => {
+	if (screenfull.isEnabled) {
+		screenfull.request(element, {navigationUI: 'hide'});
+	}
+});
+```
+
 #### Fullscreen an element with jQuery
 
 ```js
@@ -177,11 +189,13 @@ export class ToggleFullscreenDirective {
 
 ### API
 
-#### .request()
+#### .request(element, options?)
 
 Make an element fullscreen.
 
-Accepts a DOM element. Default is `<html>`. If called with another element than the currently active, it will switch to that if it's a decendant.
+Accepts a DOM element and [`FullscreenOptions`](https://developer.mozilla.org/en-US/docs/Web/API/FullscreenOptions).
+
+The default element is `<html>`. If called with another element than the currently active, it will switch to that if it's a decendant.
 
 If your page is inside an `<iframe>` you will need to add a `allowfullscreen` attribute (+ `webkitallowfullscreen` and `mozallowfullscreen`).
 
@@ -195,10 +209,12 @@ Brings you out of fullscreen.
 
 Returns a promise that resolves after the element exits fullscreen.
 
-#### .toggle()
+#### .toggle(element, options?)
 
 Requests fullscreen if not active, otherwise exits.
 
+Accepts a DOM element and [`FullscreenOptions`](https://developer.mozilla.org/en-US/docs/Web/API/FullscreenOptions).
+
 Returns a promise that resolves after the element enters/exits fullscreen.
 
 #### .on(event, function)

diff --git a/src/screenfull.d.ts b/src/screenfull.d.ts
@@ -48,6 +48,7 @@ declare namespace screenfull {
 		Keep in mind that the browser will only enter fullscreen when initiated by user events like click, touch, key.
 
 		@param element - Default is `<html>`. If called with another element than the currently active, it will switch to that if it's a decendant.
+		@param options - [`FullscreenOptions`](https://developer.mozilla.org/en-US/docs/Web/API/FullscreenOptions).
 		@returns A promise that resolves after the element enters fullscreen.
 
 		@example
@@ -70,6 +71,15 @@ declare namespace screenfull {
 			}
 		});
 
+		// Fullscreen an element with options
+		const element = document.getElementById('target');
+
+		document.getElementById('button').addEventListener('click', () => {
+			if (screenfull.isEnabled) {
+				screenfull.request(element, {navigationUI: 'hide'});
+			}
+		});
+
 		// Fullscreen an element with jQuery
 		const element = $('#target')[0]; // Get DOM element from jQuery collection
 
@@ -80,7 +90,7 @@ declare namespace screenfull {
 		});
 		```
 		*/
-		request(element?: Element): Promise<void>;
+		request(element?: Element, options?: FullscreenOptions): Promise<void>;
 
 		/**
 		Brings you out of fullscreen.
@@ -92,6 +102,8 @@ declare namespace screenfull {
 		/**
 		Requests fullscreen if not active, otherwise exits.
 
+		@param element - Default is `<html>`. If called with another element than the currently active, it will switch to that if it's a decendant.
+		@param options - [`FullscreenOptions`](https://developer.mozilla.org/en-US/docs/Web/API/FullscreenOptions).
 		@returns A promise that resolves after the element enters/exits fullscreen.
 
 		@example
@@ -105,7 +117,7 @@ declare namespace screenfull {
 		});
 		```
 		*/
-		toggle(element?: Element): Promise<void>;
+		toggle(element?: Element, options?: FullscreenOptions): Promise<void>;
 
 		/**
 		Add a listener for when the browser switches in and out of fullscreen or when there is an error.

diff --git a/src/screenfull.js b/src/screenfull.js
@@ -77,7 +77,7 @@
 	};
 
 	var screenfull = {
-		request: function (element) {
+		request: function (element, options) {
 			return new Promise(function (resolve, reject) {
 				var onFullScreenEntered = function () {
 					this.off('change', onFullScreenEntered);
@@ -88,7 +88,7 @@
 
 				element = element || document.documentElement;
 
-				var returnPromise = element[fn.requestFullscreen]();
+				var returnPromise = element[fn.requestFullscreen](options);
 
 				if (returnPromise instanceof Promise) {
 					returnPromise.then(onFullScreenEntered).catch(reject);
@@ -116,8 +116,8 @@
 				}
 			}.bind(this));
 		},
-		toggle: function (element) {
-			return this.isFullscreen ? this.exit() : this.request(element);
+		toggle: function (element, options) {
+			return this.isFullscreen ? this.exit() : this.request(element, options);
 		},
 		onchange: function (callback) {
 			this.on('change', callback);