Custom elements

Is this page helpful?
calendar icon
user iconDavid Klement
clock icon7 minutes
bullseye iconCustom elements
arrow-down-line iconDownload 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.

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 Bynderarrow-right-top-square icon.
  • Add an AI-powered content personalization system like Recombeearrow-right-top-square icon.
  • Let your content creators write the way they're used to by implementing a custom Markdown WYSIWYG text editorarrow-right-top-square icon.

Available custom elements

Check out the available custom elementsarrow-right-top-square icon 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.

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 Netlifyarrow-right-top-square icon.
  • 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 Docsarrow-right-top-square icon.
  • If you'd like to test your custom element locally, use a secure tunnel to your localhost. You can use a service like ngrokarrow-right-top-square icon 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 attributearrow-right-top-square icon 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)
    • Keep in mind that this is a 3rd party context. You need to set cookies attributes SameSite=None; Secure to use cookies.

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 binder icon Content model, open a content type for editing.
  2. Click custom-element icon 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.

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.

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 editorarrow-right-top-square icon, it looks like this:
When you get the content item via Delivery API, you get markdown content in the custom element's value.
  • Docs
  • AI accelerators
  • Collections
  • Custom elements
  • Environments
  • Keyboard shortcuts
  • Mission Control
  • Projects
  • Spaces
  • Task management
  • Terminology
Custom element configuration
Markdown editor custom element in content item
  • JSON
  • desktop-alt icon
  • Cheat sheets
  • Documentation
  • API reference
  • Product updates
Kontent.ai Learn
  • Plan
  • Set up
  • Model
  • Develop
  • Create
Copyright © 2024 Kontent.aiarrow-right-top-square icon. All rights reserved.
  • Webarrow-right-top-square icon
  • Privacy policyarrow-right-top-square icon
  • Cookies policy
  • Consent settingsarrow-right-top-square icon
  • Securityarrow-right-top-square icon
  • GDPRarrow-right-top-square icon
"markdown_editor": {
  "type": "custom",
  "name": "Markdown editor",
  "value": "## Hello world\nThis is a sentence with **bold** and *italics* in it.\n> And blockquotes!"
}
key icon
light-bulb icon
exclamation-triangle icon
i-circle icon
Configuring a custom element in a content type.
Markdown editor custom element in a content item.
  • Sign in
  • What is a custom element?
  • Available custom elements
  • Host your custom element securely
  • Add the custom element to your project
  • How to use JSON parameters
  • Authoring experience with custom elements
    • 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.
    Tip: Create your own custom elementsCan't find an existing custom element that does the trick? Get started with our custom element templatearrow-right-top-square icon to quickly create your own custom elements.
    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.
    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.