Last updated Mar 2, 2022

Rate this page:

Create a Confluence theme

The Theme API was built for a UI that Confluence has recently moved away from, and doesn't support the new UI. Based on Theme API usage to date, we are evaluating whether Theme API will support the new UI.

This page will give the basics of creating and managing a theme. Please go through this page and create a sample connect app.

confluenceThemes

To create a theme for Confluence you need to create:

  1. Theme module descriptor
  2. HTML/CSS/Javascript for the theme

You can make use of the Confluence Web Components Library if you like, which will be served to the user via an iframe.

Create theme module descriptor

A theme module descriptor contains a set of routes to override. The URL belonging to the route definition property will be rendered as a full-page iframe similar to a general page module without the Confluence header.

The URL supplied by the route property will be given a set of context parameters. These context parameters will contain information about the specific route, and can be used by your add-on to render appropriate content. For example, the spaceview route will have the context parameter space.key, which is the key of the space being rendered. The theme routes documentation details each context parameter and its meaning for each route.

The theme is expected to create an appropriate UI for the particular route being overridden. The spaceview route is expected to show the home page of a specific space. The JavaScript API is also available inside a theme iframe so that the theme can perform client-side requests to Confluence or display dialogs.

The theme can optionally provide custom space experiences, which can be applied to a particular space or globally (to all spaces). The look and feel settings in the descriptor will be saved into the colour scheme settings under a Theme setting.

Create HTML/CSS/Javascript for the theme

Please go through AUI guide to get more details about each UI component.

UI kit component: Theme properties

PropertyTypeRequiredDescription
keystringYesA key for the module, which other modules can refer to. Must be unique within the manifest. Regex: ^[a-zA-Z0-9_-]+$
routeOverridebooleanOptional (default: true)A configuration to enable or disable route override. The default is true.
availableGloballybooleanOptional (default: false)A configuration to make the theme available to select in global administration. The default is false.
descriptionstringOptionalA description for the Theme. This will appear next to the icon in the Theme selector in the Confluence admininstration screen.
iconJson Object "icon": {"width":110,"height": 70,"url":"/icon.png"},OptionalAn icon to display in the Theme selector in the Confluence administration screen. The icon will be resized to 110px wide and 70px high to fit inside the Theme selector.
routesstringYesDefines each of the routes that the Theme module should override. For example, the spaceview route can have as a URL /my-spaceview/{space.key}, and the context parameter space.key is going to be replaced with the actual space key of the content being viewed.
namestringOptionalname of the module
lookAndFeelJson ObjectOptionalYou can change the look and feel of pages, blog posts, and the Confluence header by applying lookAndFeel properties to your Confluence theme. More details are here.

Example of confluenceThemes module

As described here, in your app root directory open atlassian-connect.json and add confluenceThemes module in the modules section.

1
2
"modules": {
  "confluenceThemes": [{
      "key": "my-first-theme",
      "routeOverride": false,
      "availableGlobally": true,
      "icon": {
          "width":110,
          "height": 70,
          "url":"/icon.png"
      },
      "name": {
          "value": "Hello World Theme"
      },
      "description": {
          "value": "My first Connect theme."
      },
      "routes": {
          "spaceview": {
              "url": "/space/{space.key}"
          }
      },
      "lookAndFeel": {
        // Your look and feel settings go here.
      }
  }]
}

Rate this page: