Skip navigation

Extend the content editing features with custom elements

6 min read
Download PDF

You can extend Kontent.ai by implementing extra features you need for your project, such as a 3rd-party video service. These extensions are called custom elements. Custom elements help you expand the built-in functionality of Kontent.ai and take the authoring experience to next level.

Table of contents

    Key points

    • A custom element is a small HTML app that acts as an extension of Kontent.ai's native capabilities.
    • To use your extension in a Kontent.ai project, add a custom element into a content type and specify the URL of your extension.
    • You need to securely host your custom elements yourself.

    What is a custom element?

    Custom elements are small HTML apps that exist in a sandboxed <iframe> in Kontent.ai and interact with Kontent.ai through the Custom Elements API. They enable you to extend the default content type elements to include the functionality you need.

    Have a look at a few examples of extending Kontent.ai capabilities using custom elements:

    • Enable selecting assets from a 3rd-party digital asset management system (DAM), such as Bynder.
    • Add an AI-powered content personalization system like Recombee.
    • Let your content creators write the way they're used to by implementing a custom Markdown WYSIWYG text editor.

    Available custom elements

    Check out the available custom elements created and maintained by our community. Choose a custom element that suits your needs, host the element securely, and add the element to Kontent.ai.

    Tip: Create your own custom elements

    Can't find an existing custom element that does the trick? Get started with our custom element template to quickly create your own custom elements.

    Host your custom element securely

    Custom elements are HTML applications loaded in an <iframe>. They need to be hosted so the browser can fetch the file.

    You need to host your custom element yourself or use a service like Netlify.

    • If you decide to host your custom element on your own servers, you need to:
      • Set up the appropriate domain certificate for the server.
      • Make sure the server sends the X-frame-options (or Content-Security-Policy) header to specify an allowed origin, in this case, https://app.kontent.ai. For more details, see the MDN Web Docs.
    • If you'd like to test your custom element locally, use a secure tunnel to your localhost. You can use a service like ngrok that connects to your local application and provides a secure public URL for access from Kontent.ai.

    Your custom element is separated from the rest of Kontent.ai through the sandbox attribute on the <iframe>. The following sandbox flags are enabled:

    • allow-forms – allows form submission
    • allow-scripts – allows JavaScript to run inside the <iframe>
    • allow-popups – allows popups
    • allow-same-origin – allows the document to maintain its origin
    • allow-modals – allows modal dialogs
    • allow-storage-access-by-user-activation – allows storage access (e.g. cookies or local storage)

    Add the custom element to your project

    To have your custom element appear in content items, you need to add it to the content type of the items.

    1. In Content model, open a content type for editing.
    2. Click Custom element on the right to add a new custom element.
    3. Name the element.
    4. In Hosted code URL (HTTPS), paste the URL where you host your custom element.
    5. (Optional) In Parameters {JSON}, enter JSON configuration parameters if your custom element needs any.
    6. Click Save changes.

    If you set the custom element as required, Kontent.ai checks if the element contains any value. Any other value than null is considered valid and won't prevent an item from getting published.

    How to use JSON parameters

    The JSON parameters enable you to configure your element and reuse it in various contexts. In some cases, you may want different settings for different projects, content types, or even elements. 

    For example, a custom element that provides a WYSIWYG editor might be configured to accept JSON parameters for activating and deactivating spellcheck and tools like inserting images. This way, you would enable spellcheck or images only in places where it makes sense.

    You might also change the custom editor's HTML so that all its features can be activated and deactivated via JSON parameters. That way, each custom element can have a different feature set.

    Never store your API keys or any other sensitive data in the JSON parameters field. It's not secure! Use server-side proxy to store sensitive data.

    Default values for custom elements

    You can use the JSON parameters to set a default value for your custom element.

    For example, you can add {"default_value": "Enter your text here"} to the JSON parameters. When you initialize your element, check whether there's already some value in the element. If there isn't, use the value from the JSON parameters.

    When you create a content item via Management API, you need to insert the default value yourself. Without that, the custom element would remain empty since its code doesn't execute after you create the item via API.

    Authoring experience with custom elements

    Once you've added your custom element to a content type, you can use the custom element in content items. For example, if you add a custom Markdown editor, it looks like this:

    When you get the content item via Delivery API, you get markdown content in the custom element's value.

    • JSON
    "markdown_editor": { "type": "custom", "name": "Markdown editor", "value": "## Hello world\nThis is a sentence with **bold** and *italics* in it.\n> And blockquotes!" }
    "markdown_editor": { "type": "custom", "name": "Markdown editor", "value": "## Hello world\nThis is a sentence with **bold** and *italics* in it.\n> And blockquotes!" }

    What's next?