Embeddable Media Library widget

The Media Library widget provides a way to easily integrate ImageKit DAM into your CMS or any other web application. You can access all the assets stored in your Media Library and Collections from your existing CMS or application.

Integrating the Media Library widget is straightforward, as you will discover in this document.

You can also see the live hosted demo on codesandbox.io. Tweak the parameters to understand the different options.

The JavaScript-based plugin allows seamless access to your ImageKit Media Library and Media Collections within your CMS or web application. You can search assets stored in the Media Library and consume them in your application.

The plugin allows you to:

• Open the ImageKit Media Library within your CMS and log in to it using ImageKit credentials
• Search and insert images directly into your CMS from your ImageKit Media Library.
• Configure UI view options like inline or modal-based Media Library panel.
• Supply a custom container class to customize the styling to match your application theme.
• Open the Media Library directly to a specified state, such as opening a specific folder or asset.
• Allowing single/multiple asset(s) insertion or limiting the maximum number of assets inserted via the plugin.

Integrating the ImageKit Media Library plugin into a page in your web application or CMS interface is straightforward. We will go through the following steps in detail one by one:

1. Include the plugin script and create a container element - Include the plugin script file in the web page to embed the Media Library. Create a container element where the widget will be rendered.
2. Initialize the Media Library widget - Provide the configuration options and callback to initialize the widget. These options include the mandatory container within which the Media Library Widget UI will be rendered and other optional settings described later in the page.
3. Instantiate the Media Library widget and open it - Using the configuration options and callback method, the plugin can now be instantiated through the IKMediaLibraryWidget constructor and used by navigating to the webpage where it has been embedded.
4. Insert images from the Media Library via the plugin - Choose images and other files from within the Media Library interface and insert them in your CMS or web application.

Insert the following script on the web page where you want to access the Media Library plugin:

<script src="https://unpkg.com/imagekit-media-library-widget/dist/imagekit-media-library-widget.min.js"></script>

Create an HTML container element where the widget will be rendered:

<div id="container"></div>

Using the configuration options and callback function, let’s instantiate the plugin:

const mediaLibraryWidget = new IKMediaLibraryWidget(config, callback);

• config - Configuration options applied to the Media Library widget instance.
• callback - This function is called after the user clicks the "Insert" button in the Media Library. The callback receives a JSON payload of the selected images.

The plugin accepts the following configuration options, including the mandatory container. It also accepts some optional settings that control the plugin's behavior and styling.

mlSettings can have the following properties:

initialView can only have one of the following properties:

Refer to example configuration to learn how to use these options.

• Open Media library(ML) home
• Open ML at a specific path
• Open specific file
• Open specific types of files
• Custom search query
• Open all collections
• Open specific collection
• Allow single file selection
• Specify the maximum number of files to be selected

This callback function is called after the user clicks the "Insert" button in the Media Library. The callback receives a JSON payload of the selected images. You can consume this data in your application in any way you choose.

function callback (payload) {
  // this is the callback handler
  // … consume json payload …
}

The following shows an example of the JSON payload returned after selecting and inserting an image from the Media Library Widget UI.

{
  eventType: 'INSERT',
  data: [{
    createdAt: "2020-12-15T08:33:04.570Z",
    customCoordinates: null,
    fileId: "5fd874c040308546019f0500",
    filePath: "/rally_s_tK613HYyf.jpg",
    fileType: "image",
    isPrivateFile: false,
    name: "rally_s_tK613HYyf.jpg",
    tags: null,
    thumbnail: "https://ik.imagekit.io/o00s3beva/tr:n-media_library_thumbnail/rally_s_tK613HYyf.jpg",
    type: "file",
    url: "https://ik.imagekit.io/o00s3beva/rally_s_tK613HYyf.jpg"
 }]
}

Navigate to your application webpage in the browser. You should see the following button:

Upon clicking it, the Media Library view should open up directly if you are already logged in to ImageKit on this browser. Otherwise, the login screen will be displayed.

Login to ImageKit with your email and password.

After logging in successfully, you should automatically be routed to the Media Library view.

The Media Library Widget looks and works similarly to the ImageKit dashboard.

An "Insert" button should be present in the screen's upper right area. Click on this to trigger your web app page's image selection handling callback.

The modal view should close automatically. Open the browser console and verify that the image payload data has been logged successfully:

<!DOCTYPE html>
<html>

<head>
  <title>ImageKit Media Library Widget</title>
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <link rel="stylesheet" href="styles.css">
</head>

<body>
  <!-- Media Library -->
  <div class="wrapper">
    <div id="container"></div>
  </div>
</body>

<script src="https://unpkg.com/imagekit-media-library-widget/dist/imagekit-media-library-widget.min.js"></script>

<script>
// configuration options
const config = {
  container: '#container',   // the element in which the widget will be rendered
  className: 'media-library-widget',
  dimensions: {
    height: '100%',
    width: '100%',
 },
  view: 'modal',  // modal | inline
  renderOpenButton: true  // false | true (default)
};

// define callback handler  
function callback (payload) {
  // this is the callback handler
  // … consume json payload …
  console.log('Image data:', payload.data);
}

// instantiate the plugin
const mediaLibraryWidget = new IKMediaLibraryWidget(config, callback);
</script>

</html>

html {
  width: 100%;
  height: 100%;
  margin: 0;
  padding: 0;
}

body {
  margin: 0;
  font-family: Arial, Helvetica, sans-serif;
}

#container {
  position: relative;
  height: 100%;
  width: 100%;
}

.wrapper {
  width: 100%;
  height: 100%;
}

const config = {
  container: '#container',   // the element in which the widget will be rendered
  className: 'media-library-widget',
  dimensions: {
    height: '100%',
    width: '100%',
 },
  view: 'modal',  // modal (default) | inline
  renderOpenButton: true  // false | true (default)
};

The following config will open the ML widget at path: /marketing/banner.

const config = {
  container: '#container',   // the element in which the widget will be rendered
  className: 'media-library-widget',
  dimensions: {
    height: '100%',
    width: '100%',
 },
  view: 'modal',  // modal (default) | inline
  renderOpenButton: true,  // false | true (default)
  mlSettings: {
    initialView: {
      folderPath: '/marketing/banner'
 },
 }
};

The following config will open the specific file detail page.

const config = {
  container: '#container',   // the element in which the widget will be rendered
  className: 'media-library-widget',
  dimensions: {
    height: '100%',
    width: '100%',
 },
  view: 'modal',  // modal (default) | inline
  renderOpenButton: true,  // false | true (default)
  mlSettings: {
    initialView: {
      fileId: "5fd874c040308546019f0500"
 },
 }
};

Only open videos type files.

const config = {
  container: '#container',   // the element in which the widget will be rendered
  className: 'media-library-widget',
  dimensions: {
    height: '100%',
    width: '100%',
 },
  view: 'modal',  // modal (default) | inline
  renderOpenButton: true,  // false | true (default)
  mlSettings: {
    initialView: {
      fileType: 'videos'
 },
 }
};

It opens in a search view with all the assets with names starting with pexel.

const config = {
  container: '#container',   // the element in which the widget will be rendered
  className: 'media-library-widget',
  dimensions: {
    height: '100%',
    width: '100%',
 },
  view: 'modal',  // modal (default) | inline
  renderOpenButton: true,  // false | true (default)
  mlSettings: {
    initialView: {
      searchQuery: '(name : "pexel")'
 },
 }
};

The following configuration will show a view of all collections.

const config = {
  container: '#container',   // the element in which the widget will be rendered
  className: 'media-library-widget',
  dimensions: {
    height: '100%',
    width: '100%',
 },
  view: 'modal',  // modal (default) | inline
  renderOpenButton: true,  // false | true (default)
  mlSettings: {
      collection: {}
 }
};

The following config will open a collection with the specified ID.

const config = {
  container: '#container',   // the element in which the widget will be rendered
  className: 'media-library-widget',
  dimensions: {
    height: '100%',
    width: '100%',
 },
  view: 'modal',  // modal (default) | inline
  renderOpenButton: true,  // false | true (default)
  mlSettings: {
      collection: {
        id: "5fd874c040308546019f0500"
 }
 }
};

The following config will allow the user to select only a single asset.

const config = {
  container: '#container',   // the element in which the widget will be rendered
  className: 'media-library-widget',
  dimensions: {
    height: '100%',
    width: '100%',
 },
  view: 'modal',  // modal (default) | inline
  renderOpenButton: true,  // false | true (default)
  mlSettings: {
    multiple: false
 }
};

The following config will allow the user to select only a single asset.

const config = {
  container: '#container',   // the element in which the widget will be rendered
  className: 'media-library-widget',
  dimensions: {
    height: '100%',
    width: '100%',
 },
  view: 'modal',  // modal (default) | inline
  renderOpenButton: true,  // false | true (default)
  mlSettings: {
    multiple: true,
    maxFiles: 3
 }
};

To use this plugin on Google Chrome in Incognito mode, you need to enable third-party cookies: