Styling Confluence with CSS

This page explains the facility for changing the look and feel of Confluence with CSS.


Cascading Style Sheets (CSS) are an industry-standard way of styling a web page. The content of a page is rendered with HTML, and its look and feel is determined by CSS files. You can upload a CSS text file, or simply type in a stylesheet, and apply it to a space or even a whole Confluence site.

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  > General Configuration > Security Configuration and select Custom Stylesheets for Spaces.

Creating CSS styles that work seamlessly across different browsers is a delicate task for basic web sites, and reasonably challenging when customising web applications like Confluence. It is important to test each change that you make and ensure it works as expected in all areas of Confluence – for example, on the Confluence dashboard as well as on regular pages.

In order to get you started, we have compiled this introduction, a basic styling tutorial.

Considerations for Using Custom CSS

CSS Knowledge is Required

If you are not familiar with CSS, see the links in the CSS Resources section below. You should spend some time to become confident with Cascading Style Sheets before you start editing your Confluence style sheets.


Custom CSS can be used to inject scripts into a page, opening the risk of cross-site scripting (XSS) attacks. With this feature enabled, space administrators could upload styles that steal other users' login credentials, trick their browsers into performing actions on the wiki without their knowledge, or even obtain global administration privileges. As such, this feature is disabled by default. Confluence administrators should only enable custom CSS if they are comfortable with the risks listed in this paragraph.


Each page needs to scale. Depending on the resolution of the user's screen, the content should render intelligently. Your designs needs to degrade gracefully. Try resizing each page that exists in Confluence. There are quite a few pages in the browse-space-section, like drafts, labels, page hierarchy, and so on. Your style has to work everywhere, not just in the first page you happen to be looking at.

Features Cannot Be Disabled

It is easy to turn off certain links, headers, or even menu items by simply setting their style to 'hidden'. This can help you to roll out Confluence to users that may not be very Wiki-savvy yet. The simpler the UI, the easier it may be for them to use. However, please remember that removing the link to a part of the application does not mean that the functionality is not available. Every user can still change their style from within their browsers, or access the URL directly. Don't rely on CSS to disable parts of Confluence.

Features Should Not Be Disabled

Users familiar with Confluence will expect to find the same controls that they are accustomed to. Removing buttons or controls from the interface is not advised as it may frustrate your users and cause them to circumvent your design by using direct URL access, as mentioned above.

Custom CSS does not apply to Admin screens

Any CSS styling applied to your site will not be applied to the Administration console. This is to ensure changes to CSS do not prevent administrators from accessing Admin functions in future.  

Confluence Version Compatibility

Be aware of any plans to upgrade your Confluence instance. Future versions of Confluence may not be compatible with your custom CSS — this may cause your CSS to break, requiring maintenance when Confluence is upgraded. Ask your Confluence administrator for more information.

Test on Different Web Browsers

As a rule you should test your modifications on different web browsers. Internet Explorer, Firefox, Opera and Safari (on Mac OS X) are some of the more popular browsers.

Note about supported web browsers: Please ensure that you are using one of the web browsers supported by Confluence. If you are using an unsupported browser or browser version, some features may not work correctly. Check the Supported Platforms page to find the list of supported web browsers and browser versions on this page.

CSS Customisation is Not Supported

As creating custom CSS has potentially limitless possibilities, Atlassian will not support issues that are caused by or related to CSS customisation.

Getting Started

Editing the CSS

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.

If your space uses the Documentation theme:

  1. Choose Browse > Space Admin from the header

    Note: The Space Admin option appears only if you have space admin permissions, or if you're part of the 'confluence-administrators' group.

  2. Click Stylesheet in the left-hand panel under the heading 'Look and Feel'.
  3. Choose  Edit.
  4. Paste your custom CSS into the text field.
  5. Save your changes. The new CSS will be visible on all content pages in the space.

To edit your global CSS stylesheet:

  1. Choose the cog icon , then choose General Configuration under Confluence Administration
  2. Choose Stylesheet.
  3. Choose Edit.
  4. Paste your custom CSS into the text field.
  5. Choose Save


  • The new CSS will be visible across all spaces, provided they do not define their own custom stylesheet and are not using a theme. This CSS will also overwrite all styles defined in custom global themes.
  • You may be able to add CSS to your site by choosing Custom HTML in the administration section, and adding your CSS definitions to the HEAD or BODY of the page. You should only use this option if you cannot achieve the desired results via the global stylesheet.

Follow the Tutorial

Follow the examples in the Basic Styling Tutorial to get started.

CSS Resources 

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

31 Archived comments

  1. User avatar


    I have created a CSS class that highlights text and designates it as an instructor note. Now how do I apply that to the text? In HTML I would use a <div class="inst_note"> or <span class="inst_note"> tag. I can't find documentation here that explains how to do the equivalent of using a <div> or <span> tag to apply a CSS class.

    22 Apr 2009
    1. User avatar

      Arie Murdianto

      Hi Will,

      You may want to try my way to get your stylesheet applied:

      1. Create the stylesheet on <space> -> Space Admin -> Stylesheet. Put the following:
        div.kampredo {color: blue}
      2. Create a page contains the following. Please note that in order to use html macro, you need to enable it in plugin manager.
        <DIV class="kampredo"> this is kampredo </DIV>


      07 May 2009
      1. User avatar


        Hi Arie Murdianto

        its is suitable for confluence 3.5.13 ?

        Thank you


        26 Sep 2012
  2. User avatar

    Jay Mackey

    I've tried overriding paragraph margin in the space admin style sheet. I can make it bigger than default, but not smaller. How can I make it smaller, such as 1em instead of what appears to be 2em on either the top or bottom margin.

    Alternatively, is there a way to make a custom paragraph style available from the pull-down, so that a paragraph would have a 1X line spacing between paragraphs like the 'preformatted' style, but with the same font, etc. as the current paragraph style?


    03 Apr 2012
    1. User avatar

      Matt Ryall [Atlassian]

      I'm not sure exactly what the cause of your problem is without some sample styles, but it sounds like it's a problem with collapsing margins, where a larger margin on one element causes a large gap even though the other element has a smaller margin. Vertical margins in CSS "collapse", which means that the vertical margins of adjacent elements overlap with each other in most circumstances.

      If you want to reduce the paragraph spacing on a section of text in a page, I'd recommend writing a user macro that wraps the content in a div with an additional class – <div class="single-spaced">...</div>. You can then apply custom styles to reduce the margin on paragraphs and headings within those macros: .single-spaced p { margin: 0; }. You'll need similar styles for the headings.

      23 Apr 2012
  3. User avatar


    I'm using Confluence 3.5. I cannot overwrite the default style of h1, h2, h3, ..., h7 via Space Admin >> Stylesheet.

    Any customized class (for instance #header1) works.

    23 Apr 2012
    1. User avatar

      Matt Ryall [Atlassian]

      You need to understand how CSS specificity works to make styles that override Confluence's ones.

      In our stylesheet, we use ".wiki-content h1" as our selector. So your selector needs to be at least as specific in order to work correctly.

      23 Apr 2012
      1. User avatar


        Adding ".wiki-content" in front of the default class does work!! Thanks a lot!

        25 Apr 2012
  4. User avatar


    My users want to add comments to pages and have the comment text to be single line spaced, but then they press enter it's always <p> and double spaced

    how can I change the default settings to be <br> instead of <p>

    I just want to make their comments single line spaced.

    The double line spacing is adding too much padding to the pages

    PS they also want to do it with out having to press sift-return for new single spaced new lines

    30 Apr 2012
    1. User avatar

      Matt Ryall [Atlassian]

      There isn't really an easy way, unfortunately. We looked at making this the default for Confluence, but it introduced a lot of problems in the editing experience – way more problems than there are now.

      You could create a user macro and some custom CSS, as I described to Jay above, but that's probably not as easy as just encouraging your users to use shift-return if they want to insert a line break rather than a paragraph break.

      30 Apr 2012
  5. User avatar

    Stephen Gilson

    We applied a lot of styles to a page, but now when we edit the page, the edit area of the page is about one inch tall. Can styles applied to a page affect the way the page appears when you edit it? Is there a way to turn off styles when you edit a page? I can post an image if that helps.



    02 May 2012
  6. User avatar

    Mike Reaves

    The double-spacing of lines is giving my users problems as well.  There is too much wasted space in a document.  Is it possible to get back to the old "wiki markup" editing UI, instead of the WYSIWYG editor so that lines can easily be single-spaced? 

    Thank you.

    10 Jul 2012
  7. User avatar

    Melaina Rauen

    Hello all,

    I was having a hard time getting the custom css within the Space Admin to overwrite the global CSS (a problem I found a lot of other people had, but no solutions to). I found a very simple fix to this and thought I might share, hopefully save someone else the headache!

    Normally, to define a custom style for a particular space, you would go to Space Admin > Stylesheet and then enter your CSS, cross your fingers, hold your breath, and hope that it actually works. Well, if it doesn't, take that fancy custom CSS, and go to Space Admin > Edit Space Layout. In the Header section, paste in your CSS and add {style} open and close tags.


    .myCoolThing {display: block;}


    Works like a charm! Good luck!


    25 Jul 2012
    1. User avatar

      Melaina Rauen

      side note: This trick is best used when you are trying to avoid using !important. The first step, before going into the Edit Space Layout sections, would be to add !important to your CSS within the Stylesheet. This should overwrite the global CSS with no problems. Because of custom jQuery I was using, the !important tag was not an option. In the Space Stylesheet, your CSS would look like this:

      .myCoolThing { display: block !important; }

      Hope this helps!

      25 Jul 2012
  8. User avatar


    I like the things that can be created with CSS3, for example nice buttons without using image file; so, the page loads faster is a few buttons:
    Only with css /css3.

    13 Oct 2012
  9. User avatar

    Normann P. Nielsen

    Hi All,


    I am working on a GUI styling guide, please fell free to visit

    30 Dec 2012
    1. User avatar

      Matt Ryall [Atlassian]

      Thanks for the link, Normann. Please note that we are planning some significant changes to the web interface for Confluence 5.0, due to be released in a couple of months. More details here:

      I notice you're already referring to Confluence "4.x" in your page titles. This is a good approach – clear indicating which version your documentation refers to, so there is no confusion.

      02 Jan 2013
  10. User avatar

    Chris Maloney

    The text says I need system admin permissions "to edit the CSS for a space or for the site".  We have a large confluence installation and I am not one of the admins, but I have created several spaces and would like to be able to use css to fix some deficiencies in Confluence rendering.  Do I really need to ask the admins for system admin permissions to be able to add css to my own spaces?  If so, why is it designed this way?  Why can't anyone add css to their own spaces?  At least, that relaxed permissions mode should be an option.

    08 Jan 2013
  11. User avatar


    I'm trying to control table cell padding in confluence 5.  Anybody know how to use CSS to control this?

    03 Jul 2013
  12. User avatar

    Dmitriy Lazarev

    Please correct link "CSS Resources section" in page. This link go on same page, not "Resources section".

    19 Jul 2013
    1. User avatar

      Denise Unterwurzacher [Atlassian]

      Oops! Good pickup (smile) I've fixed that up now, thanks for letting us know.

      21 Jul 2013
  13. User avatar


    I've created a css for the site and change a lot of properties & values (so have i a large css). So far so good, it works great, but ...

    How can i change for some spaces only few (3-4) of the values without paste the whole css into space-stylesheet? I mean a reason like this:

    <head> ...
    <link type="text/css" rel="stylesheet" ... my_for_site.css>
    <style> ... -color: red; ...</style>

    but not - like in html - for single dokuments. I'm looking for a reason for single spaces!

    11 Aug 2013
  14. User avatar


    I'm again. No answer is an answer too. i understand it as 'search by yourself' (smile)
    CONF-27929 - Allow Space Stylesheet to work alongside Global Stylesheets Resolved

    13 Aug 2013
  15. User avatar

    Vamsi K Nori

    I created a css for my space. While the background color is getting applied and so is the font-size, the font color is not getting applied in my pages. Can anyone respond to this asap?

    18 Sep 2013
    1. User avatar

      Rachel Robins [Atlassian Tech Writer]

      Hi Vamsi, You might want to ask your question over at Atlassian Answers - you will get a faster response than here in the docs. 

      19 Sep 2013
  16. User avatar

    Eddy Hernandez

    Does the css for this page come as a default theme? If not, I copied it over to a gist and added it to one of my pages. Thanks!

    21 Apr 2014
  17. User avatar

    Hans-Peter Geier

    last weekend we have upgraded our Confluence 4.3 instance to 5.4.

    As part of the upgrade, I had to modify the style sheets (global and space-specific), because some of the CSS had to be removed and others to be added, so they work correctly in 5.4.

    While it was obvious to me that I have to handle all existing space-specific stylesheets to apply these changes, I planned to take this opportunity and remove all space-specific style sheet, and move all relevant CSS content into the global stylesheet, so it would be at least easier for future upgrades (and other reasons for changing CSS globally).

    As it turned out, when I cleared the space's stylesheet, the global style sheet was NOT applied to the sapce. Which is even more surprising because it works perfectly in this way for PDF stylesheet and PDF layout. So, why not for the regular stylesheet?

      (we are using the Documentation Theme in most spaces. Is my observation related to this theme only? Or is this the same behavior in the default theme as well?)

    I ended up copying the new global stylesheet into all spaces which is something I really wanted to avoid. It's a huge amount of manual work for a site having many spaces. This needs to be urgently improved.  (CONF-27929 already exists which describes some aspects of my request already)

    27 May 2014
  18. User avatar

    Frédéric Bonneau

    Is there a way of using labels to customize page rendering through CSS rules ?

    I would like to specify which layout must be used to export pages in PDF depending its labels : meeting notes have not the same presentation as specification documents or table report.

    02 Apr 2015
    1. User avatar

      Giles Brunning [Atlassian Technical Writer]

      Hi Frédéric,

      I think that's more of a CSS question than a Confluence one, but you might try asking over at answers.

      Personally, I've never known CSS to be able to perform that type of if/then operation; it sounds like you'd need a combination of javascript and CSS to get that result.

      07 Apr 2015
      1. User avatar

        Frédéric Bonneau

        Hi Giles,

        Thanks for your feedback. You're right : CSS selectors can't be applied from child to parent so if the labels informations are in a DOM entity lower than the content (which is the case I think), I can't use it to specify different layout. One way could be to get the labels higher in the DOM structure (ie : at a main-content level) to perform such selectors "main-content[labels~=mylabel] myElement{ ... }". But it's not available at the moment.

        I need to try the javascript solution to get this done.

        07 Apr 2015
  19. User avatar

    Hans-Peter Geier

    Confluence up to 3.5 did visualize links which the user did not have access permissions.

    Since Confluence 4, this feature does not exist anymore.

    In Confluence 4 and 5 (currently we are on 5.4.4) , I brought back this lacking feature by an Custom CSS entry like this:

    which I found in Answers.


    In Confluence 5.8, these links do not have 'class="unresolved" ' anymore, so this CSS doesn't work anymore.

    Is there another way to achieve the same in 5.8 ?

    22 Jul 2015
Powered by Confluence and Scroll Viewport