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.

Premium feature

Custom elements require a Professional plan or higher.

Table of contents

    When implementing your Custom elements, you need to reference the Custom Elements API in your HTML app. For more details, see our Integrating your own content editing features tutorial.

    init method

    Use the init method to initialize your custom element. The init method expects a function which takes element and context as parameters. The element and context objects provide information from Kentico Kontent about the custom element and about where it is displayed in the UI.

    • JavaScript
    CustomElement.init((element, context) => { // Initializes the custom element setupColorPicker(element.value, element.disabled, element.config) })
    CustomElement.init((element, context) => { // Initializes the custom element setupColorPicker(element.value, element.disabled, element.config) })
    Object propertyTypeDescription
    element.valuestring, nullThe custom element's initial value.
    element.disabledbooleanIndicates whether an element is disabled for editing.
    element.configobject, nullParameters of the custom element specified as a JSON object in the UI (in a content type or a content type snippet)
    context.projectIdstringThe project's ID.
    context.item.idstringThe ID of the content item that contains the custom element.
    context.item.codenamestringThe codename of the content item that contains the custom element.
    context.variant.idstringThe language's ID.
    context.variant.codenamestringThe language's codename, for example, en-us.

    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 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);
    CustomElement.setValue(value);
    ParameterTypeDescription
    valuestring, nullCustom element value to be set

    onDisabledChanged method

    Use the onDisabledChanged method to define what should happen with a custom element when it's disabled for editing. 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((disabled) => { // Sets your custom element to read-only mode myElement.updateDisabledState(disabled); })
    CustomElement.onDisabledChanged((disabled) => { // Sets your custom element to read-only mode myElement.updateDisabledState(disabled); })
    ParameterTypeDescription
    disabledbooleanIndicates whether element is disabled for editing

    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, (value) => { // Use the returned element value here })
    CustomElement.getElementValue(elementCodename, (value) => { // Use the returned element value here })
    ParameterTypeDescription
    elementCodenamestringCodename of the content element from which the value should be read
    valuevariesReturned value of the specified content element. Data type is based on the type of the content element.

    Data type of content elements

    • Custom element – string
    • Date & Time – ISO-8601 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. This method can listen to any element changes and does not depend on the list of elements allowed for reading.

    Use this method together with the getElementValue method to keep updated information about a particular element value.

    • JavaScript
    CustomElement.observeElementChanges(elementCodenames, (changedElementCodenames) => { // React to change in particular element })
    CustomElement.observeElementChanges(elementCodenames, (changedElementCodenames) => { // React to change in particular element })
    ParameterTypeDescription
    elementCodenamesarray of stringsArray of codenames of the content elements to observe.
    When an empty array is provided, all elements are observed.
    changedElementCodenamesarray of stringsArray of codenames of the elements which value has changed.