Last updated Dec 20, 2024

Create a Confluence theme

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:

Theme module descriptor
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

Property	Type	Required	Description
`key`	string	Yes	A key for the module, which other modules can refer to. Must be unique within the manifest. Regex: `^[a-zA-Z0-9_-]+$`
`routeOverride`	boolean	Optional (default: `true`)	A configuration to enable or disable route override. The default is true.
`availableGlobally`	boolean	Optional (default: `false`)	A configuration to make the theme available to select in global administration. The default is false.
`description`	string	Optional	A description for the Theme. This will appear next to the icon in the Theme selector in the Confluence admininstration screen.
`icon`	Json Object `"icon": {"width":110,"height": 70,"url":"/icon.png"},`	Optional	An 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.
`routes`	string	Yes	Defines 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.
`name`	string	Optional	name of the module
`lookAndFeel`	Json Object	Optional	You 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.
      }
  }]
}