Was this page helpful?

File structure

The basic file structure of UI Extensions comprises of two files:

  • index.html
  • extension.json


The index.html file is the building block for an extension and it is embedded into the Contentful entry editor as an <iframe>.

The index.html includes the following:

  • the markup code and the logic.

  • reference to the UI Extensions SDK which,

    • enables the extension to communicate with the Contentful Web App.

    • exposes the contentfulExtension.init() method. This is the main entry point for all the extension-related code.

      Following is an example of the contentfulExtension.init() method:

      window.contentfulExtension.init(function (extension) {
      var value = extension.field.getValue()
      extension.field.setValue("Hello world!")
    • cf-extension.css library, in order to use any of the Contentful’s styles.

      <!doctype html>
      <html lang="en">
        <meta charset="UTF-8"/>
        <title>Sample Editor Extension</title>
        <link rel="stylesheet" href="https://contentful.github.io/ui-extensions-sdk/cf-extension.css">
        <script src="https://unpkg.com/contentful-ui-extensions-sdk@3"></script>
        <div id="content"></div>
        <script type="text/javascript">
          window.contentfulExtension.init(function (extension) {
            var value = extension.field.getValue()
            extension.field.setValue("Hello world!")


The extension.json file, also known as the Descriptor file, is used to describe the properties of an extension. Although this file is optional, it is recommended to create it.

The following table describes the properties that can be set on an extension.

Property Required Type Description
id yes String Extension id
name yes String Extension name
fieldTypes yes Array<String>* The field types of a content type where an extension can be used
src ** String URL where the root HTML document of the extension can be found
srcdoc ** String Path to the local extension HTML document
sidebar no Boolean Controls the location of the extension. If true it will be rendered on the sidebar

* Valid field types are: Symbol, Symbols, Text, Integer, Number, Date, Boolean, Object, Entry, Entries, Asset, Assets.

** One of src or srcdoc is required.

Following is an example of a extension.json file:

  "id": "extension",
  "name": "My first extension",
  "srcdoc": "./app.html",
  "fieldTypes": ["Text"]

Next steps

Not what you’re looking for? Try our FAQ.