Basic Styling Tutorial

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

This page contains instructions on how to get started with custom CSS styling in Confluence.

CSS Editing Quick-Start

To edit a space's CSS style sheets:
  1. Go to the space and choose Space tools > Look and Feel from the bottom of the sidebar
  2. Choose Stylesheet then Edit.
  3. Paste your custom CSS into the text field.
  4. Save your changes. The new CSS will be visible on all content pages in the space.

On this page:

Related pages:

Tutorial: Changing the Header Background

The header is the menu area at the top of a default Confluence page where the Breadcrumb Links, Browse menu, User menu and the Quick Search box reside. In this example, we are going to change the background of the header to include a custom graphic.

  1. Create a custom graphic. For this example, we created a custom header graphic of 1046 x 61 pixels.
  2. Upload the custom graphic to a page in the space that you are customizing.
  3. Note the page ID of the page where you uploaded the new graphic. (in this example, the page ID was '658833839'.
  4. Compose your custom CSS for the header. The example below loads the new graphic (called 'header.png') from a specific page (denoted by page ID '658833839') in the same space.

     #header .aui-header  {
           background-repeat: no-repeat;
  5. Log in as the Space Administrator.
  6. Open the Space Admin page.
  7. Click Stylesheet.
  8. Click Edit to change the code in the text field.
  9. Paste your custom CSS into the text field.
  10. Click Save and then reload the page (you may have to shift-reload). The background of the header will change.
  11. The custom header will be visible on all content pages in the space. To revert your change, simple delete the custom code from the 'Stylesheet' page and click Save.

CSS Editing Tips

Begin With a Space Stylesheet

A space stylesheet is a good starting point for CSS customization, as it already includes all of the elements that can be changed. When you work on the space stylesheet it styles all content pages in the space. Build and test it at space-level, before considering applying the new stylesheet to your entire site. Once you are satisfied with your space design, test it thoroughly until you are confident that it has no problems. Then, you can look into advanced customization of the Confluence CSS such as adjusting the Search page, the Dashboard and other integral pages.

Use the Right Tools

As the Confluence CSS is reasonably sophisticated, web development applications will help you to understand how the page styles have been created. In particular, you will need to view the existing source for the pages you're starting to work on. If you don't already have some, tools such as the following free applications will allow you to do this.

1. Firebug
Firebug, a plugin for the Firefox web browser, allows you to take a look at the style of each element on your page. This is very useful to see what styles are currently applied, for example styles applied to the header only.

2. Web Developer
The Web Developer plugin for Firefox allows you to edit CSS inline and create new page designs.

3. CSS Edit
CSS Edit is a stand-alone CSS editor for Macintosh that extracts all existing styles from a given page and allows you to overwrite these.

Edit Simple Elements First

Begin by editing simple elements and checking that they work. By making changes, then checking that each one worked, you can easily isolate any CSS code that is causing problems. Be aware that some page elements are more suited to customization than others. For example, adding a gradient to the toolbar is less likely to 'break' the page than changing the page width. Editing reasonably static elements such as background graphics will render more predictably than designs which attempt to completely change the user interface or the Javascript-powered drop-down menus (which we don't recommend editing).


Note: By default, only system administrators can edit the CSS for a space or for the site. To allow any user with Space Admin permissions to edit the CSS for a space, go to Administration  > General Configuration > Security Configuration and select Custom Stylesheets for Spaces.

Last modified on Mar 31, 2023

Was this helpful?

Provide feedback about this article
Powered by Confluence and Scroll Viewport.