The Custom elements API is a JavaScript API that gives you the methods you need for implementing custom elements in Kontent.ai. The Custom elements API serves as a means of communication between your custom element and the Kontent.ai UI.
When implementing your custom elements, you need to reference the Custom Elements JS API in your HTML5 app.
For more details, see our tutorial on Integrating your own content editing features.Use the init method to initialize your custom element.The init method expects a callback function which takes element and context as parameters. This callback function is called once your custom element is registered within Kontent.ai.
Parameter
Type
Description
callback
function
A callback function that receives the Element and Context objects which provide information from Kontent.ai about the custom element and about where it is displayed in the UI. (element: Element, context: Context) => {
   // Initializes the custom element
   initMyCustomElement(element.value, element.disabled, element.config);
}
When using the custom element in a content component, the Context object refers to the parent content item of the content component, not the component itself. It's currently not possible to retrieve information about the component or access its other elements.
Property
Type
Description
projectId
string
The environment’s ID.
item.id
string
The ID of the content item that contains the custom element.
item.codename
string
The codename of the content item that contains the custom element.
item.collection
reference object
Property
Type
Description
value
string, null
The custom element's initial value.
disabled
boolean
Indicates whether an element is disabled for editing.
config
object, null
Parameters of the custom element specified as a JSON object in the UI (in a content type or a
Use the setValue method to set a custom element value. When the value is set to null, the element is considered empty.
If you want the custom element content to be searchable in the content items list, specify the keywords or the plain text using value object.
If a custom element is set as required in the UI, Kontent.ai checks the element's value. Any value other than null is considered a valid value and won't generate a validation error message.
Custom elements can contain up to 100,000 characters. If an element exceeds this number, Kontent.ai will display an error.
Parameter
Type
Description
value
string, null, object
Custom element value to be set.
Parameter
Type
Description
valueObject.value
string, null
Custom element value to be set.
valueObject.searchableValue
string, null
Plain text searchable value used for searching in the content items list. Do not use any markup or JSON here to allow a correct search.
Use the onDisabledChanged method to define what should happen with a custom element when it's disabled for editing. The method takes a callback function.
When disabled, the element is in read-only mode. This means that the element is shown in a content item but cannot be changed.
For example, custom elements can be disabled in these cases:
The content item is published.
User is viewing an older version of a content item.
User doesn't have editing permissions.
Parameter
Type
Description
callback
function
A callback function that receives a boolean indicating whether the element is disabled for editing. (disabled: boolean) => {
   // Sets your custom element to read-only mode
   myCustomElement.updateDisabledState(disabled);
}
Use the setHeight method to set a custom height of a custom element. The value will be set in pixels.
Parameter
Type
Description
height
number
Custom element height to be set in the Kontent.ai UI. Height must be a positive integer.
Use the getElementValue method to retrieve the value of a different element. You can retrieve another element's value even if the custom element is disabled.
The getElementValue method works on elements that are:
Used in the same content group as the custom element itself.
Specified in the custom element's configuration, specifically, in the Allow the custom element to read values of specific elements field.
If you need to get values of multiple elements, call the getElementValue method for each such element. If you need to get the value multiple times, call the method multiple times.
Parameter
Type
Description
elementCodename
string
Codename of the content element from which the value should be read.
callback
function
A callback function that receives the value of the specified element. The data type of the value varies based on the type of the content element. (value: <mixed>) => {
 // Use the returned element value here
}
Multiple choice – array of selected options. Each option is returned as an object based on the following schema: { id: <uuid>, name: <string>, codename: <string> }.
Text – string
URL slug – string
Other content elements are currently not supported.
Use the observeElementChanges method to receive notifications about changes in other elements.
The observeElementChanges method can listen to any element changes and does not depend on the list of elements allowed for reading.
The observeElementChanges method does not return a specific element value but only notifies that the change occurred. The method takes a callback function as a second parameter. Use this method together with the getElementValue method to keep updated information about an element value.
Parameter
Type
Description
elementCodenames
array of strings
Array of codenames of the content elements to observe. When an empty array is provided, all elements are observed.
callback
function
A callback function that receives codenames of changed elements as an array of strings. (changedElementCodenames: string[]) => {
  // React to changes in particular element
}
Use the observeItemChanges method to receive notifications about changes in the item.
The observeItemChanges method can listen to changes of the item's attributes – its name, codename, or collection.
The method only notifies about the change, it doesn't return the new value of the changed attributes. It takes a callback function that is called whenever any of the attributes is changed. The callback function is called with a parameter that contains the item's new details.
Parameter
Type
Description
callback
function
A callback function that receives object with current item data. (newItemDetails: ItemChangedDetails) => { Â Â // React to changes in a particular element }
Property
Type
Description
item.codename
string
The codename of the content item that contains the custom element.
item.collection
reference object
The object represents an identifier of the item's collection, for example {"id": "00000000-0000-0000-0000-000000000000"}
item.name
string
The display name of the content item that contains the custom element
Use the selectAssets method to enable the custom element to select assets from Kontent.ai.
The method takes a config object and, if a user selects assets from the dialog, returns a promise with an array of asset references containing the selected asset's ID. If the selection dialog is closed, the method returns null.
Property
Type
Description
allowMultiple
boolean
Specifies whether multiple assets can be selected.
fileType
string
Specifies what type of images can be selected; allowed values are all and images.
The object containing an ID reference to the selected asset.
Property
Type
Description
id
GUID
The asset's internal ID.
Use the getAssetDetails method to get metadata about a specific asset. After getting IDs with the selectAssets method, you can then get more information about each of the assets returned.
The getAssetDetails method takes an array of asset IDs as strings and returns a promise with an array of asset objects. The method returns a null if the specified items don't exist.
The descriptions of the asset in all available languages.Â
fileName
string
The name of the file.
imageHeight
Property
Type
Description
language.id
GUIDÂ
The description's language ID.
language.codename
string
The description's language codename.
description
string
The asset's description for a specific language.
Use the selectItems method to enable the custom element to select content items from Kontent.ai.
The method takes a config object and, if a user selects content items from the dialog, returns a promise with an array of content item references containing the selected item's ID. If the selection dialog is cancelled, the method returns null.
Property
Type
Description
allowMultiple
boolean
Specifies whether multiple items can be selected.
Property
Type
Description
id
GUID
The content item's internal ID.
Use the getItemDetails method to get details about a specific content item. After getting IDs with the selectItem method, you can then get details about each of the items returned.
The getItemDetails method takes an array of content item IDs as strings and returns a promise with an array of content item objects. The method returns a null if the specified items don't exist.
Parameter
Type
Description
itemIds
array of GUIDs
The internal IDs of the items to be returned.
Property
Type
Description
id
GUID
The item's internal ID.
codename
string
The item's codename.
name
string
The item's display name.
collection
reference object
The item's collection
The object represents an identifier of the item's collection, for example {"id": "00000000-0000-0000-0000-000000000000"}
item.name
string
The display name of the content item that contains the custom element
Jan Cerman
8 minutes
API
formatted string