Vue Friendly Iframe

0.20.0 · active · verified Sun Apr 19

Vue Friendly Iframe is a Vue.js component designed to simplify the creation and management of dynamic, asynchronous iframes, based on Aaron Peters' iframe loading techniques. The current stable version is 0.20.0, with releases occurring somewhat irregularly but indicating active maintenance, often driven by feature additions or bug fixes. Its primary differentiator is providing a controlled, event-driven mechanism for loading external content within an iframe, making it easier to interact with the iframe's lifecycle and attributes. It specifically supports Vue 2.x projects and integrates as a Vue plugin, offering props for `src`, `sandbox`, `allow`, `allowfullscreen`, and custom events for load states, aiming to provide a safer and more performant iframe experience compared to native iframe usage. It abstracts away some of the complexities of handling iframe content and security attributes.

Common errors

```
[Vue warn]: Unknown custom element: <vue-friendly-iframe> - did you register the component correctly?
```
cause The `vue-friendly-iframe` component was not registered globally as a Vue plugin, or it was not imported/used correctly in a local component.

fix Ensure you have `import VueFriendlyIframe from 'vue-friendly-iframe';` and `Vue.use(VueFriendlyIframe);` in your main Vue entry file (e.g., main.js) before your Vue instance is created.
```
Refused to display 'https://example.com' in a frame because it set 'X-Frame-Options' to 'deny'.
```
cause The server hosting the iframe's content explicitly denies embedding in iframes via the `X-Frame-Options` HTTP header or a Content Security Policy (CSP).

fix This is a server-side restriction. You must either use a different `src` that permits embedding or request the owner of the content to modify their server's `X-Frame-Options` or CSP. You cannot bypass this client-side.

Warnings

breaking Starting from version 0.17.0, `vue-friendly-iframe` must be installed as a Vue plugin using `Vue.use(VueFriendlyIframe)` instead of being directly imported and registered as a component.
Fix: Ensure your Vue application calls `Vue.use(VueFriendlyIframe)` once during initialization, typically in your main.js file.
deprecated The `scrolling` attribute for iframes was removed in v0.10.0 as it is obsolete. It should be controlled via CSS instead.
Fix: Remove the `scrolling` attribute from your `<vue-friendly-iframe>` component. Use CSS properties like `overflow: auto;` or `overflow: scroll;` on the iframe or its containing element if you need to control scrolling behavior.
gotcha This component is designed for Vue 2.x. It does not officially support Vue 3.x and may require significant adaptations or not function as expected in a Vue 3 environment.
Fix: Use this package exclusively with Vue 2.x projects. For Vue 3, consider looking for a Vue 3 compatible iframe component or building a custom solution.
gotcha When loading external content, be mindful of browser same-origin policies. Cross-Origin Resource Sharing (CORS) restrictions can prevent access to the iframe's content or events unless properly configured by the iframe's source server.
Fix: Ensure the content loaded in the iframe has appropriate CORS headers if you need to access its DOM or listen to events from it. For sandboxed iframes, explicitly include `allow-same-origin` in the `sandbox` attribute if necessary.

Install

npm install vue-friendly-iframe npm
yarn add vue-friendly-iframe yarn
pnpm add vue-friendly-iframe pnpm

Imports

VueFriendlyIframe

wrong:

import { VueFriendlyIframe } from 'vue-friendly-iframe'; // This is a default export, not named.

correct:

import VueFriendlyIframe from 'vue-friendly-iframe';

The component is exported as a default export.

Plugin Installation

wrong:

new Vue({
  components: { VueFriendlyIframe }
}); // Component must be installed as a plugin globally since v0.17.0.

correct:

import Vue from 'vue';
Vue.use(VueFriendlyIframe);

Since version 0.17.0, the component must be installed as a Vue plugin using `Vue.use()` before being used in templates.

Component Usage in Template
```
<vue-friendly-iframe :src="iframeSrc" @load="onIframeLoad" @message="onIframeMessage"></vue-friendly-iframe>
```
The component tag is `vue-friendly-iframe`. Use `:src` for dynamic source and `@load`, `@message` for events.

Quickstart

This quickstart demonstrates how to install `vue-friendly-iframe` as a Vue plugin, set its source, and handle `load` and `message` events, including essential `sandbox` and `allow` attributes for security and functionality.

import Vue from 'vue';
import VueFriendlyIframe from 'vue-friendly-iframe';

Vue.use(VueFriendlyIframe);

new Vue({
  el: '#app',
  data: {
    iframeSrc: 'https://example.com/some-content',
    iframeLoaded: false,
    iframeMessage: ''
  },
  methods: {
    onIframeLoad() {
      this.iframeLoaded = true;
      console.log('Iframe content loaded!');
    },
    onIframeMessage(event) {
      this.iframeMessage = event.data;
      console.log('Message from iframe:', event.data);
    }
  },
  template: `
    <div>
      <h1>My App with Friendly Iframe</h1>
      <p v-if="!iframeLoaded">Loading iframe...</p>
      <p v-else>Iframe loaded!</p>
      <p v-if="iframeMessage">Message received: {{ iframeMessage }}</p>
      <vue-friendly-iframe
        :src="iframeSrc"
        @load="onIframeLoad"
        @message="onIframeMessage"
        sandbox="allow-scripts allow-same-origin"
        allow="fullscreen"
        style="width: 100%; height: 500px; border: 1px solid #ccc;"
      ></vue-friendly-iframe>
    </div>
  `
});

view raw JSON →