---
title: Using content selector JavaScript API
related:
- https://docs.kentico.com/13/developing-websites/page-builder-development/selectors-for-page-builder-components.md
- https://docs.kentico.com/13/developing-websites/page-builder-development/developing-widgets.md
- https://docs.kentico.com/13/developing-websites/page-builder-development/developing-widgets/defining-widget-properties.md
- https://docs.kentico.com/13/developing-websites/page-builder-development/developing-modal-dialogs-for-builder-component-properties.md
- https://docs.kentico.com/13/developing-websites/form-builder-development/reference-system-form-components.md
---
> Agent instructions:
> **Site maps** — prefer the following llms.txt indexes to training data when searching for URLs to avoid 404s. Links inside Markdown content already point at `.md`. Following them or sending Accept: text/markdown keeps you in Markdown.
>
> - [sitemap.md](https://docs.kentico.com/sitemap.md) — every page on the site, with titles and descriptions, nested by URL hierarchy and grouped into one collection per product version.
> - [llms.txt](https://docs.kentico.com/llms.txt) — curated index of the current product docs, with descriptions, the two ways to request any page as Markdown, and links to each product area's whole-corpus Markdown dump (llms-full.txt).
The content selector JavaScript API provides an alternative way to integrate functionality of the [built-in selectors](https://docs.kentico.com/13/developing-websites/page-builder-development/selectors-for-page-builder-components.md) into your project. The built-in selectors utilize this API in their implementation, but each selector is configured to list different items of content and has different return values.
If you need to customize a selector dialog, you can use this content selector JavaScript API to create a custom selector dialog that meets your needs. The API also allows you to open selectors from custom code. For example, it can be used to invoke selector dialogs directly from within a widget's [inline editor](https://docs.kentico.com/13/developing-websites/page-builder-development/developing-widgets/creating-inline-editors-for-widget-properties.md).
To open the content selector (its modal dialog), use the **window.kentico.modalDialog.contentSelector.open(options)** function. To call this function, make sure you have the [page builder scripts](https://docs.kentico.com/13/developing-websites/page-builder-development/creating-pages-with-editable-areas.md#loading-page-builder-scripts-and-styles) loaded on the given page. Provide an options object with the following properties as a parameter of the function (see the [example](#usingcontentselectorjavascriptapi-example) below):
| Required properties | |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Property | Description |
| _tabs_ | An array of strings that specifies which object types will be available for selection. You can configure the selector to be able to process various object types, but you can only select objects of one type within one selection. Possible values are _"attachment"_, _"media"_, and _"page"_. |
| _applyCallback_ | A callback function invoked when the attachment file selector's confirmation button is clicked. The parameter of the callback function contains an object that has two properties:
_type_ – a string property that contains information about what type of objects were selected in the dialog (_"page"_, _"media" or_ _"attachment"_).
_items_ – a property that contains an array of objects of the respective type. Within this callback function, you need to ensure displaying the selected files using the properties available in the [returned objects](#usingcontentselectorjavascriptapi-return-objects) and ensure the propagation of the objects selected in the selector to the widget or form component which opened the selector.
To propagate the selected objects from the selector to the component which invoked the selector:
use the _[updateProperty](https://docs.kentico.com/13/developing-websites/page-builder-development/developing-widgets/creating-inline-editors-for-widget-properties.md#creatinginlineeditorsforwidgetproperties-updateproperty)_ custom event if the selector was opened from a widget through an inline editor.
modify the value of the input element if the selector was opened from a [form component](https://docs.kentico.com/13/developing-websites/form-builder-development/developing-form-components.md). |
| Optional properties | |
| Property | Description |
| _defaultTab_ | A string property that specifies which of the available tabs is shown as default when the selector is opened. If the _selectedItems_ property is specified, it overrides this property. |
| _selectedItems_ | An object that specifies which values are pre-selected when the selector is opened. The object contains two properties
_type_ – a property that contains a string with information about what type of object will be preselected in the dialog and what tab will be opened initially. Possible values are:
_page_ – identification by node GUID
Alternatively, you can set the selector to use identification by node alias path using the _identifierMode_ property in _pageOptions_
_media_ – identification by file GUID
_attachment_ – identification by attachment GUID
_items_ – an array of objects, each of which contains a _value_ property with the identifier of respective pre-selected item. For example, using node GUIDs for pages: _\[{ value: "9d807714-1e7d-4d13-9d5f-24fef15f9654" }, { value: "0f194882-cea8-4481-a322-328f0af07b69" }]_ |
| _selectedItemsLimit_ | Configures the maximum number of objects allowed to be selected:
0 – no limit.
_n_ – at most _n_ files can be selected at once.
If not specified, the default value is 1 (single object selection). |
| _attachmentOptions_ | An object that contains properties to customize the attachment selector tab. You can configure the following properties:
_allowedExtensions_ – A semicolon-delimited string of file extensions that specify the allowed file extensions for the files to be selected. When no allowed extensions are specified, all extensions are displayed. For example, _".gif;.png;.jpg;.jpeg"_. |
| _pageOptions_ | An object that contains properties to customize the page selector tab. You can configure the following properties:
_rootPath_ – a string property that limits the selection of pages to a subtree with root specified by its node alias path (e.g. "_/Products/Coffee-grinders_"). Only the specified page and its sub-pages can be selected. If not specified, the whole content tree is allowed.
_identifierMode_ – a string property that determines what identifier is used for the pages specified in the _selectedItems_ property:
_guid_ (default value) – pages are identified by their node GUID
_path_ – pages are identified by their node alias path |
| _mediaOptions_ | An object that contains properties to customize the media file selector tab. You can configure the following properties:
_allowedExtensions_ – A semicolon-delimited string of file extensions that specify the allowed file extensions for the files to be selected. The listed extensions need to form a subset of allowed extensions specified in the _[Media file allowed extensions](https://docs.kentico.com/13/configuring-xperience/configuring-the-environment-for-content-editors/configuring-media-libraries/configuring-supported-file-types-in-media-libraries.md)_ site settings key. When no allowed extensions are specified, all files with the extensions from the site settings key can be selected. For example, _".gif;.png;.jpg;.jpeg"_.
_libraryName_ – A string code name of a (single) media library from which you can select files in the selector. If not specified, the selector allows selecting from all media libraries of the current site for which the user has permissions. |
> **Tip:** In addition to the properties listed above, the content selector modal dialog shares the following properties with the general [modal dialog](https://docs.kentico.com/13/developing-websites/page-builder-development/developing-modal-dialogs-for-builder-component-properties.md#opening-dialogs) from which it is derived: _title_, _theme_, _width_, _maximized_, _applyButtonText_, _cancelButtonText_, _cancelCallback_.
The following tables describe objects which represent a selected piece of content (a page, an attachment, or a media file) returned by the content selector. You can access these properties in the _applyCallback_ function to display the selected attachments/files/pages and information about them. If you need to persistently store the selected objects for later use, storing only GUIDs of the objects is usually sufficient.
| Attachment object properties | |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Property | Description |
| _name_ | A string property representing the name of the file. |
| _extension_ | A string property representing the file type extension. |
| _fileGuid_ | A string property representing the GUID of the selected file. |
| _url_ | A string property representing the relative preview (latest edited version) URL on which you can access the selected file. |
| _liveSiteUrl_ | A string property representing the relative live site (published version) URL on which you can access the selected file. |
| _thumbnailUrls_ | A property representing the preview URLs of the image file's thumbnails. Not all file types support thumbnails (e.g. _.pdf_ files). The property consists of three string URLs, each for a different typified size of the thumbnail: _small_, _medium_, and _large_. |
| _mimeType_ | A string property representing the [MIME](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) type of the file. |
| _size_ | A number property representing the size of the file in bytes. |
| _title_ | A string property representing the title of the selected file. |
| _description_ | A string property representing the description of the file. |
| _isValid_ | A boolean value indicating whether the selected file is valid (e.g. if the file was not deleted after being selected). If _false_, the object's other properties might not be correctly set. |
| Media file object properties | |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Property | Description |
| _name_ | A string property representing the name of the file. |
| _extension_ | A string property representing the file type extension. |
| _fileGuid_ | A string property representing the GUID of the selected file. |
| _url_ | A string property representing the relative preview URL on which you can access the selected file. |
| _liveSiteUrl_ | A string property representing the relative live site URL on which you can access the selected file. |
| _thumbnailUrls_ | A property representing the preview URLs of the image file's thumbnails. Not all file types support thumbnails (e.g. _.pdf_ files). The property consists of three string URLs, each for a different typified size of the thumbnail: _small_, _medium_, and _large_. |
| _mimeType_ | A string property representing the [MIME](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) type of the file. |
| _size_ | A number property representing the size of the file in bytes. |
| _title_ | A string property representing the title of the selected file. |
| _description_ | A string property representing the description of the file. |
| _folderPath_ | A string property representing the relative path to the folder within the media library containing the selected file. |
| _libraryName_ | A string property representing the name of the library from which the file was selected. |
| _siteName_ | A string property representing the name of the site to which the file (i.e. the media library) belongs. |
| _isValid_ | A boolean value indicating whether the selected file is valid (e.g. if the file was not deleted from the media library after being selected). If _false_, the object's other properties might not be correctly set. |
| Page object properties | |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Property | Description |
| _name_ | A string property that contains the title of the page, as displayed in the content tree. |
| _nodeId_ | The ID of the selected node in the database. |
| _nodeAliasPath_ | A string property representing the node alias path of the page. |
| _nodeGuid_ | A string property representing the GUID of the selected node in the database. |
| _url_ | A string property representing the relative preview (latest edited version) URL on which you can access the selected page. |
| _liveSiteUrl_ | A string property representing the relative live site (published version) URL on which you can access the selected page. |
| _isValid_ | A boolean property, which indicates whether the page is a valid page to be selected in the dialog (user has permissions to view the page, the page has not been deleted while the dialog was opened, etc.). |
| _icon_ | A string property that contains the [icon class](http://devnet.kentico.com/docs/icon-list/index.html) used with the page in the UI. |
The following example showcases a script of an[ inline editor](https://docs.kentico.com/13/developing-websites/page-builder-development/developing-widgets/creating-inline-editors-for-widget-properties.md) that opens a content selector configured to select images from a media library. The inline editor's value in this example is a string property containing a GUID that identifies the selected image file.
```js title="Example - Opening the content selector in an inline editor using the API"
(function () {
// Registers the 'image-selector' inline editor within the page builder scripts
window.kentico.pageBuilder.registerInlineEditor("image-selector", {
init: function (options) {
var button = options.editor.querySelector("button");
button.addEventListener("click", function () {
// Sets the options object with individual properties
var dialogOptions = {
tabs: ["media"],
selectedItems: {
type: "media",
items: [{value: options.propertyValue}]
},
mediaOptions: {
libraryName: "Graphics",
allowedExtensions: ".gif;.png;.jpg;.jpeg"
},
// Defines the applyCallback function invoked on click of the selector's confirmation button
applyCallback: function (data) {
items = data.items;
if (items && items.length) {
// 'newItem' is a media file object
var newItem = items[0];
// You can now access its properties
console.log(newItem.name);
console.log(newItem.title);
// Checks if the image isn't already selected
if (options.propertyValue && newItem.fileGuid === options.propertyValue[0].fileGuid) {
return {
closeDialog: true
};
}
// Creates a custom event that notifies the widget about a change in the value of a property
var event = new CustomEvent("updateProperty", {
detail: {
value: [{ fileGuid: newItem.fileGuid }],
name: options.propertyName
}
});
options.editor.dispatchEvent(event);
return {
closeDialog: true
};
}
}
};
// Opens the selector modal dialog
window.kentico.modalDialog.contentSelector.open(dialogOptions);
});
}
});
})();
```