Skip navigation

Custom elements JS API

The Custom elements API is a JavaScript API that contains methods needed for implementing custom elements in Kentico Kontent. The API serves as a tool for communication between a custom element and the Kentico Kontent app.

Table of contents

    Inclusion in your app

    When implementing your custom elements, you need to reference the Custom Elements JS API in your HTML5 app.

    • JavaScript
    <script src="https://app.kontent.ai/js-api/custom-element/v1/custom-element.min.js"></script>
    <script src="https://app.kontent.ai/js-api/custom-element/v1/custom-element.min.js"></script>

    For more details, see our tutorial on Integrating your own content editing features.

    init method

    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 Kentico Kontent.

    • JavaScript
    CustomElement.init(callback);
    CustomElement.init(callback);
    ParameterTypeDescription
    callbackfunctionA callback function that receives the Element and Context objects which provide information from Kentico Kontent 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);
    }

    Context object

    PropertyTypeDescription
    projectIdstringThe project's ID.
    item.idstringThe ID of the content item that contains the custom element.
    item.codenamestringThe codename of the content item that contains the custom element.
    variant.idstringThe language's ID.
    variant.codenamestringThe language's codename, for example, en-us.

    Element object

    PropertyTypeDescription
    valuestring, nullThe custom element's initial value.
    disabledbooleanIndicates whether an element is disabled for editing.
    configobject, nullParameters of the custom element specified as a JSON object in the UI (in a content type or a content type snippet)

    setValue method

    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, Kentico Kontent checks its 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, Kentico Kontent will display an error.

    • JavaScript
    CustomElement.setValue(value: string | null | ValueObject);
    CustomElement.setValue(value: string | null | ValueObject);
    ParameterTypeDescription
    valuestring, null, objectCustom element value to be set.

    ValueObject object

    ParameterTypeDescription
    valueObject.valuestring, nullCustom element value to be set.
    valueObject.searchableValuestring, nullPlain text searchable value used for searching in the content items list. Do not use any markup or JSON here to allow a correct search.

    onDisabledChanged method

    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.
    • JavaScript
    CustomElement.onDisabledChanged(callback);
    CustomElement.onDisabledChanged(callback);
    ParameterTypeDescription
    callbackfunctionA 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);
    }

    setHeight method

    Use the setHeight method to set a custom height of a custom element. The value will be set in pixels. See specifying height of custom elements to learn more.

    • JavaScript
    CustomElement.setHeight(height);
    CustomElement.setHeight(height);
    ParameterTypeDescription
    heightnumberCustom element height to be set in the Kentico Kontent UI. Height must be a positive integer.

    getElementValue method

    Use the getElementValue method to retrieve the value of a different element. The specified element must be present in the list of elements allowed for reading by the custom element in its configuration in the Kentico Kontent UI.

    You can retrieve an element's value even if the custom element is disabled. 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.

    • JavaScript
    CustomElement.getElementValue(elementCodename, callback);
    CustomElement.getElementValue(elementCodename, callback);
    ParameterTypeDescription
    elementCodenamestringCodename of the content element from which the value should be read.
    callbackfunctionA 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
    }

    Data type of content elements

    • Custom element – string
    • Date & Time – ISO-8601Opens in a new window formatted string
    • 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.

    observeElementChanges method

    Use the observeElementChanges method to receive notifications about changes in other elements.

    The oberveElementChanges 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 a particular element value.

    The oberveElementChanges method can listen to any element changes and does not depend on the list of elements allowed for reading.

    • JavaScript
    CustomElement.observeElementChanges(elementCodenames, callback);
    CustomElement.observeElementChanges(elementCodenames, callback);
    ParameterTypeDescription
    elementCodenamesarray of stringsArray of codenames of the content elements to observe.
    When an empty arra
    y is provided, all elements are observed.
    callbackfunctionA callback function that receives codenames of changed elements as an array of strings.
    (changedElementCodenames: string[]) => {
      // React to changes in particular element
    }

    selectAssets method

    Use the selectAssets method to enable the custom element to select assets from Kentico Kontent.

    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.

    • JavaScript
    CustomElement.selectAssets(config: Config): Promise<AssetReference[] | null>
    CustomElement.selectAssets(config: Config): Promise<AssetReference[] | null>

    Config object

    PropertyTypeDescription
    allowMultiplebooleanSpecifies whether multiple assets can be selected.
    fileTypestringSpecifies what type of images can be selected; allowed values are all and images.

    AssetReference object

    The object containing an ID reference to the selected asset.

    PropertyTypeDescription
    idGUIDThe asset's internal ID.

    getAssetDetails method

    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.

    • JavaScript
    getAssetDetails(assetIds): Promise<Asset[] | null>
    getAssetDetails(assetIds): Promise<Asset[] | null>
    ParameterTypeDescription
    assetIdsarray of GUIDsThe internal IDs of the assets to be returned.

    Asset object

    PropertyTypeDescription
    idGUIDThe asset's internal ID.
    descriptionsarray of asset description objectsThe descriptions of the asset in all available languages. 
    fileNamestringThe name of the file.
    imageHeightintegerThe asset's height in pixels.
    imageWidthintegerThe asset's width in pixels.
    namestringThe asset's display name.
    sizeintegerThe size of the asset in bytes.
    thumbnailUrlstringThe URL for the thumbnail of the asset.
    titlestringThe asset's title.
    typestringThe type of the file.
    urlstringThe URL of the asset.

    Asset description object

    PropertyTypeDescription
    language.idGUID The description's language ID.
    language.codenamestringThe description's language codename.
    descriptionstringThe asset's description for a specific language.

    selectItems method

    Use the selectItems method to enable the custom element to select content items from Kentico Kontent.

    The method takes a config object and, if a user selects assets 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.

    • JavaScript
    CustomElement.selectItems(config: Config): Promise<ContentItemReference[] | null>
    CustomElement.selectItems(config: Config): Promise<ContentItemReference[] | null>

    Config object

    PropertyTypeDescription
    allowMultiplebooleanSpecifies whether multiple items can be selected.

    ContentItemReference object

    PropertyTypeDescription
    idGUIDThe content item's internal ID.

    getItemDetails method

    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.

    • JavaScript
    CustomElement.getItemDetails(itemIds): Promise<ContentItem[] | null>
    CustomElement.getItemDetails(itemIds): Promise<ContentItem[] | null>
    ParameterTypeDescription
    itemIdsarray of GUIDsThe internal IDs of the items to be returned.

    ContentItem object

    PropertyTypeDescription
    idGUIDThe item's internal ID.
    codenamestringThe item's codename.
    namestringThe item's display name.
    typereference objectThe item's type.