Embeddable Media Library widget

The Media Library widget provides an easy way to integrate ImageKit DAM into your CMS or any web application. Access all assets stored in your Media Library and Collections directly from your existing CMS or application.

Integration is straightforward, as you'll discover in this guide.

Live demo

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

This JavaScript-based plugin enables seamless access to your ImageKit Media Library and Collections within your CMS or web application. Search and manage assets stored in the Media Library directly from your application.

Key features include:

Access ImageKit Media Library within your CMS using ImageKit credentials
Search and insert images directly from your Media Library into your CMS
Configure UI view options: inline or modal-based Media Library panel
Apply custom container classes to match your application's theme
Open the Media Library in specific states (folders, assets, collections)
Control asset selection: single/multiple assets with configurable limits

Integration Overview

For quick and easy access to the DAM, use the ImageKit desktop app on Windows and macOS instead of building custom integrations. This app handles simple tasks such as uploading, browsing, searching files, and drag-and-drop into your application, streamlining your workflow efficiently.

Integrating the ImageKit Media Library plugin into your web application or CMS is straightforward. Follow these steps:

Include the plugin script and create a container element - Add the plugin script to your web page and create a container element for the widget
Initialize the Media Library widget - Configure the widget with options including the mandatory container and optional settings
Instantiate the Media Library widget and open it - Create the widget instance using the IKMediaLibraryWidget constructor
Insert assets from the Media Library - Select and insert images and other files into your CMS or application

Include the plugin script and create a container element

You can include the ImageKit Media Library Widget in your project using either the CDN or NPM installation method.

CDN Installation

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

Copy

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

NPM Installation

Install the imagekit-media-library-widget package:

Copy

# Using npm
npm install --save imagekit-media-library-widget

# Using yarn
yarn add imagekit-media-library-widget

Then include it in your JavaScript code:

Copy

// ES6 module
import IKMediaLibraryWidget from 'imagekit-media-library-widget';

// CommonJS syntax
const IKMediaLibraryWidget = require("imagekit-media-library-widget");

Internet Explorer does not natively support all Media Library Widget features. We recommend using a modern browser like Google Chrome, Mozilla Firefox, or Safari.

Create a container element

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

Copy

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

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

Copy

const mediaLibraryWidget = new IKMediaLibraryWidget(config, callback);

Constructor parameters

The IKMediaLibraryWidget constructor accepts two parameters:

Parameter	Type	Description
config	`object`	Configuration options for the Media Library widget instance. See plugin options for detailed configuration.
callback	`function`	Function called when users click "Insert" in the Media Library. Receives a JSON payload containing the selected assets.

Callback function signature

Copy

function callback(payload) {
  // Handle the selected assets
  console.log('Selected assets:', payload.data);
}

Callback payload schema

The callback receives a JSON object with the following structure:

Copy

{
  eventType: 'INSERT',
  data: [
    // Array of selected file/folder objects
    // Each object matches the schema from the 
    // List and Search Assets API response
  ]
}

Property	Type	Description
eventType	`'INSERT'`	Always set to `'INSERT'` when assets are selected and inserted.
data	`object[]`	Array of selected file objects. Each object follows the same schema as items returned by the List and Search Assets API. Contains properties like `fileId`, `name`, `filePath`, `url`, `fileType`, `tags`, etc.

Note: The default "Open Media Library" button is only displayed when renderOpenButton is set to true (default behavior).

Plugin options

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.

Option	Type	Description
container (required)	`string` \| `HTMLElement`	The container element where the Media Library will be rendered. Accepts CSS selectors (e.g., `#container`) or DOM element references.
className	`string`	Optional CSS class to apply to the container element for custom styling.
dimensions	`object`	Dimensions of the Media Library container element. Copy { height: '100%', width: '100%' }
view	`'modal'` \| `'inline'`	Display mode for the Media Library interface. Use `modal` for overlay display or `inline` for embedded display. Default: `'modal'`
renderOpenButton	`boolean`	Whether to display the default "Open Media Library" button. Set to `false` when using custom triggers or editor plugins. Default: `true`
mlSettings	`object`	Advanced configuration options for Media Library behavior. See mlSettings options below.

mlSettings options

The mlSettings object provides fine-grained control over Media Library behavior:

Option	Type	Description
initialView	`object`	Configures the initial state when the Media Library opens. See initialView options below.
multiple	`boolean`	Whether users can select multiple assets during insertion. When `false`, only single asset selection is allowed. Default: `true`
maxFiles	`number`	Maximum number of assets that can be selected in a single operation. Only applies when `multiple: true`.
toolbar	`object`	Controls the visibility of toolbar buttons in the Media Library interface. Copy toolbar: { showCloseButton: false, // Default: true showInsertButton: false // Default: true }
queryParams	`object`	Custom query parameters to append to the Media Library widget URL. Useful for passing additional context or tracking parameters. Copy queryParams: { customParam1: "value1", customParam2: 123, customParam3: true }

initialView options

The initialView object determines the initial state when the Media Library opens. You can specify only one of the following options:

Important: You cannot pass more than one property in initialView. For complex filtering, use the searchQuery option.

Option	Type	Description
searchQuery	`string`	Lucene-like query string to filter assets, same as the `searchQuery` parameter in the list and search assets API. Opens the widget in search view with filtered results. Copy searchQuery: 'name: "pexel"'
folderPath	`string`	Path to the folder that should be opened initially. Must start with `/`. Copy folderPath: '/marketing/banners'
fileId	`string`	File ID to open in detail view initially. Opens the file detail page for the specified asset. Copy fileId: '5fd874c040308546019f0500'
collection	`object`	Collection configuration. Pass an empty object `{}` to show all collections, or specify an ID to open a specific collection. Example: Copy // All collections collection: {} // Specific collection collection: { id: '5fd874c040308546019f0500' }
fileType	`'images'` \| `'videos'` \| `'cssJs'` \| `'others'`	Filter assets by type. Opens search view with results filtered to the specified asset type: `'images'`: only image files `'videos'`: only video files `'cssJs'`: only CSS, JS, or TS files `'others'`: files other than images or videos Copy fileType: 'videos'

Refer to the configuration examples below to learn how to use these options:

Callback function and payload

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.

Copy

function callback(payload) {
  // Handle the selected assets
  console.log('Selected assets:', payload.data);
  
  // Example: Insert image URLs into a form
  payload.data.forEach(asset => {
    console.log(`Asset URL: ${asset.url}`);
    console.log(`Asset name: ${asset.name}`);
  });
}

Sample payload

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

Copy

{
  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/rally_s_tK613HYyf.jpg?updatedAt=1608029584570&tr=n-media_library_thumbnail",
    type: "file",
    url: "https://ik.imagekit.io/o00s3beva/rally_s_tK613HYyf.jpg?updatedAt=1608029584570"
  }]
}

Run the application

Navigate to your application webpage in the browser. You should see the "Open Media Library" button:

Click the button to open the Media Library. If you're already logged in to ImageKit in this browser, the Media Library will open directly. Otherwise, you'll see the login screen.

Enter your ImageKit email and password to log in.

After successful login, you'll be automatically directed to the Media Library view.

Insert assets from the Media Library

The Media Library Widget interface is similar to the ImageKit dashboard, providing a familiar experience.

Look for the "Insert" button in the upper right area of the screen. Click this button to trigger your callback function with the selected assets.

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

Sample application

Copy

<!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>

Copy

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%;
}

Configuration examples

Open Media Library home

Basic configuration that opens the Media Library in the default home view:

Copy

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)
};

Open at a specific folder path

Opens the Media Library widget directly in the specified folder:

Copy

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'
    },
  }
};

Open specific file detail view

Opens the Media Library widget directly in the file detail view for a specific asset:

Copy

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"
    },
  }
};

Filter by file type

Opens the Media Library widget with results filtered to show only specific file types:

Copy

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'
    },
  }
};

Search with custom query

Opens the Media Library widget in search view with a predefined query filter:

Copy

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"'
    },
  }
};

View all collections

Opens the Media Library widget showing all available collections:

Copy

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: {
      collection: {}
    }
  }
};

Open specific collection

Opens the Media Library widget directly in a specific collection:

Copy

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: {
      collection: {
        id: "5fd874c040308546019f0500"
      }
    }
  }
};

Single file selection

Configures the Media Library widget to allow selection of only one asset at a time:

Copy

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
  }
};

Limit maximum file selection

Sets a maximum limit on the number of assets that can be selected:

Copy

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
  }
};

Google Chrome Incognito mode

When using this plugin in Google Chrome's Incognito mode, you need to enable third-party cookies:

Embeddable Media Library widget

Live demo

Media Library widget features

Integration Overview

Include the plugin script and create a container element

CDN Installation

NPM Installation

Create a container element

Initialize the Media Library widget

Constructor parameters

Callback function signature

Callback payload schema

Plugin options

mlSettings options

initialView options

Callback function and payload

Sample payload

Run the application

Insert assets from the Media Library

Sample application

Configuration examples

Open Media Library home

Open at a specific folder path

Open specific file detail view

Filter by file type

Search with custom query

View all collections

Open specific collection

Single file selection

Limit maximum file selection

Google Chrome Incognito mode