Customize The Asset Library

In this example, we will show you how to customize the asset library in CreativeEditor SDK.

Explore a full code sample on Stackblitz or view the code on Github.

The asset library is used to find assets to insert them into a scene or replace a currently selected asset. By default, we have already added a configuration of entries shown in the dock panel for images, text, stickers, shapes, and more. You can add and remove every entry or change the appearance of any entry.

Every entry has a couple of configuration options to determine what and how assets will be displayed. See the documentation on the Asset Library Entry for more information.

Adding, changing, or removing entries is done using the Asset Library Entries API. You can for example use cesdk.ui.updateAssetLibraryEntry to change the number of grid columns in the images library.

The basics of customizing the entries for replacement are the same as for insertion. The main difference is that these entries might vary depending on what block is currently selected and that the returned entries will determine if a replace action is shown on a selected block.

Most of the time it makes sense to provide a custom function to return different entries based on the type or fill of a block. If no replacement should be available for the current block, an empty array has to be returned. The UI will not show a replace button in that case.

As an argument to the callback, you will get the current context in the editor, mainly what blocks are selected, their block type as well as fills. This makes it more convenient to quickly decide what to return, but of course, you can also use the API for further checks as well.

If you do not use a custom title function for an entry, you need a translation provided with the following keys in the i18n configuration:

libraries.<entry-id>.label The label used in the dock panel
libraries.<entry-id><group-id>.label The label for groups for a given entry.
libraries.<entry-id>.<source-id>.label The label for a source in the source overview of a given entry
libraries.<entry-id>.<source-id>.<group-id>.label The label for a given group in the group overview for a given entry.
libraries.<source-id>.label The label used for a source in all entries
libraries.<source-id><group-id>.label The label for groups for source in all entries.


import CreativeEditorSDK from 'https://cdn.img.ly/packages/imgly/cesdk-js/1.39.0/index.js';

const config = {
  license: 'mtLT-_GJwMhE7LDnO8KKEma7qSuzWuDxiKuQcxHKmz3fjaXWY2lT3o3Z2VdL5twm',
  userId: 'guides-user',
  baseURL: 'https://cdn.img.ly/packages/imgly/cesdk-js/1.39.0/assets',
  i18n: {
    en: {
      'libraries.empty-custom-asset-source.label': 'Empty'
    }
  },
  callbacks: { onUpload: 'local' } // Enable local uploads in Asset Library.
};

CreativeEditorSDK.create('#cesdk_container', config).then(async (instance) => {
  // Do something with the instance of CreativeEditor SDK, for example:
  // Populate the asset library with default / demo asset sources.
  instance.addDefaultAssetSources();
  instance.addDemoAssetSources({ sceneMode: 'Design' });

  instance.engine.asset.addSource({
    id: 'emptySource',
    findAssets: () => {
      return Promise.resolve({
        assets: [],
        total: 0,
        currentPage: 1,
        nextPage: undefined
      });
    }
  });

  instance.ui.addAssetLibraryEntry({
    id: 'empty-custom-asset-source',
    sourceIds: ['emptySource'],
    previewLength: 3,
    gridColumns: 3,
    gridItemHeight: 'square',
    previewBackgroundType: 'contain',
    gridBackgroundType: 'contain',
    icon: ({ theme, iconSize }) => {
      if (theme === 'dark') {
        if (iconSize === 'normal') {
          return 'https://img.ly/static/cesdk/guides/icon-normal-dark.svg';
        } else {
          return 'https://img.ly/static/cesdk/guides/icon-large-dark.svg';
        }
      }

      if (iconSize === 'normal') {
        return 'https://img.ly/static/cesdk/guides/icon-normal-light.svg';
      } else {
        return 'https://img.ly/static/cesdk/guides/icon-large-light.svg';
      }
    }
  });

  instance.ui.addAssetLibraryEntry({
    id: 'empty-custom-asset-source-for-replace',
    sourceIds: ['emptySource'],
    previewLength: 3,
    gridColumns: 3,
    gridItemHeight: 'square'
  });

  instance.ui.addAssetLibraryEntry({
    id: 'custom-images',
    sourceIds: ['ly.img.image'],
    previewLength: 5,
    gridColumns: 5,
    icon: 'https://img.ly/static/cesdk/guides/icon-normal-dark.svg'
  });

  instance.ui.updateAssetLibraryEntry('ly.img.image', {
    ...instance.ui.getAssetLibraryEntry('ly.img.image'),
    gridColumns: 4
  });

  instance.ui.setReplaceAssetLibraryEntries(
    ({ defaultEntryIds, selectedBlocks }) => {
      if (selectedBlocks.length !== 1) {
        return [];
      }
      const [selectedBlock] = selectedBlocks;
      if (selectedBlock.blockType === '//ly.img.ubq/graphic') {
        return [...defaultEntryIds, 'empty-custom-asset-source-for-replace'];
      }
      return [];
    }
  );

  instance.ui.setDockOrder([
    ...instance.ui.getDockOrder(),
    {
      id: 'ly.img.assetLibrary.dock',
      key: 'empty-custom-asset-source',
      icon: '@imgly/CustomLibrary',
      label: 'libraries.empty-custom-asset-source.label',
      entries: ['empty-custom-asset-source']
    },
    {
      id: 'ly.img.assetLibrary.dock',
      key: 'custom-images',
      icon: '@imgly/CustomLibrary',
      label: 'libraries.custom-images.label',
      entries: ['custom-images']
    }
  ]);

  await instance.createDesignScene();
});