Iframe embed
Koval UI provides a utility Iframe
component which improves on top of default HTMLIFrameElement
.
Features
- Responsive.
Iframe
respects parent element's size and collapses if needed. Developers have to providewidth
andheight
props required to renderHTMLIFrameElement
; - Flexible permissions config. Developers can use
sandboxConfig
andpermissionsConfig
props, which allow better modification thansandbox
andallow
html attributes. See below.
Demo
import {Iframe} from 'koval-ui'; /* Don't forget to memoize (useMemo) if you are declare this inside component */ const permissionsConfig = { accelerometer: true, autoplay: true, 'clipboard-write': true, 'encrypted-media': true, gyroscope: true, 'picture-in-picture': true, 'web-share': true, } const sandboxConfig = { 'allow-downloads': true, 'allow-downloads-without-user-activation': true, 'allow-forms': true, 'allow-modals': true, 'allow-orientation-lock': true, 'allow-pointer-lock': true, 'allow-popups': true, 'allow-popups-to-escape-sandbox': true, 'allow-presentation': true, 'allow-same-origin': true, 'allow-scripts': true, 'allow-storage-access-by-user-activation': true, 'allow-top-navigation': true, 'allow-top-navigation-by-user-activation': true, 'allow-top-navigation-to-custom-protocols': true, } export default () => { return ( <Iframe src="https://www.youtube.com/embed/dQw4w9WgXcQ?si=dFPV1emazW5GQntR" width={560} height={315} referrerPolicy="strict-origin-when-cross-origin" allowFullScreen={true} name="rickroll" title="YouTube video player" sandboxConfig={sandboxConfig} permissionsConfig={permissionsConfig} /> ); };
See Iframe
playground and full props description at the Storybook
page (opens in a new tab).
sandbox
permissions
sandboxConfig
property is responsible for managing the sandbox permissions (opens in a new tab). But instead of using flat string, Koval uses the config object.
type SandboxConfig = {
/**
* Allows downloading files through an <a> or <area> element with the download attribute,
* as well as through the navigation that leads to a download of a file.
* This works regardless of whether the user clicked on the link,
* or JS code initiated it without user interaction.
*/
'allow-downloads'?: boolean;
/**
* Allows for downloads to occur without a gesture from the user.
*/
'allow-downloads-without-user-activation'?: boolean;
/**
* Allows the page to submit forms.
* If this keyword is not used, the form will be displayed as normal,
* but submitting it will not trigger input validation,
* sending data to a web server or closing a dialog.
*/
'allow-forms'?: boolean;
/**
* Allows the page to open modal windows by Window.alert(),
* Window.confirm(), Window.print() and Window.prompt(),
* while opening a <dialog> is allowed regardless of this keyword.
* It also allows the page to receive BeforeUnloadEvent event.
*/
'allow-modals'?: boolean;
/**
* Lets the resource lock the screen orientation.
*/
'allow-orientation-lock'?: boolean;
/**
* Allows the page to use the Pointer Lock API.
*/
'allow-pointer-lock'?: boolean;
/**
* Allows popups (like from Window.open(), target="_blank", Window.showModalDialog()).
* If this keyword is not used, that functionality will silently fail.
*/
'allow-popups'?: boolean;
/**
* Allows a sandboxed document
* to open a new browsing context without forcing the sandboxing flags upon it.
* This will allow, for example, a third-party advertisement
* to be safely sandboxed without forcing the same restrictions upon the page the ad links to.
* If this flag is not included, a redirected page, popup window,
* or new tab will be subject to the same sandbox restrictions as the originating <iframe>.
*/
'allow-popups-to-escape-sandbox'?: boolean;
/**
* Allows embedders to have control over whether an iframe can start a presentation session.
*/
'allow-presentation'?: boolean;
/**
* If this token is not used,
* the resource is treated as being from a special origin that always fails the same-origin policy
* (potentially preventing access to data storage/cookies and some JavaScript APIs).
*/
'allow-same-origin'?: boolean;
/**
* Allows the page to run scripts (but not create pop-up windows).
* If this keyword is not used, this operation is not allowed.
*/
'allow-scripts'?: boolean;
/**
* Allows a document loaded in the <iframe>
* to use the Storage Access API to request access to unpartitioned cookies.
*/
'allow-storage-access-by-user-activation'?: boolean;
/**
* Lets the resource navigate the top-level browsing context (the one named _top).
*/
'allow-top-navigation'?: boolean;
/**
* Lets the resource navigate the top-level browsing context, but only if initiated by a user gesture.
*/
'allow-top-navigation-by-user-activation'?: boolean;
/**
* Allows navigations to non-http protocols built into a browser or registered by a website.
* This feature is also activated by allow-popups or allow-top-navigation keyword.
*/
'allow-top-navigation-to-custom-protocols'?: boolean;
};
allow
permissions
permissionsConfig
property is responsible for managing the permissions policy of the iframe (opens in a new tab). We also provide a config object for this.
We're extending on top of default allow
attribute which expects configuration as a flat string. There are some keywords surrounded by quotes, though urls aren't. Semicolon used as delimiter
HTML attribute
<iframe
allow="geolocation 'self' https://a.example.com https://b.example.com; accelerometer *"
></iframe>
Koval config
Koval UI makes this config more jsx friendly and easier to read.
Each permission (opens in a new tab) is a config property with its own name. Developers can provide one or many values to each property.
See Iframe
playground with all supported permissions
here (opens in a new tab).
type Permission = `https://${string}` | 'self' | '*' | 'src' | 'none' | boolean;
export type PermissionsConfig = {
/**
* Controls whether the iframe is allowed
* to gather information about the acceleration of the device through the Accelerometer interface.
* @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Permissions-Policy/accelerometer
*/
accelerometer?: Permission | Permission[];
//...
};
Also, it is possible to set permissions as a boolean variable. It is an equivalent for <iframe allow="accelerometer" />
.
<Iframe permissionsConfig={{accelerometer: true}} />