Documentation for Confluence 5.8 (Server).
Documentation for Confluence Cloud and earlier versions of Confluence is available too.

Skip to end of metadata
Go to start of metadata

The Spaces List macro displays a list of spaces, similar to the list of spaces seen on the dashboard.

Using the Spaces List macro

To add the Spaces List macro to a page:

  1. In the Confluence editor, choose Insert > Other Macros
  2. Find and select the required macro

Speeding up macro entry with autocomplete: Type { and the beginning of the macro name, to see a list of suggested macros. Details are in Using Autocomplete.

To edit an existing macro: Click the macro placeholder and choose Edit. A macro dialog window will open, where you can edit the parameters of the macro.


Parameters are options that you can set to control the content or format of the macro output. Where the parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro browser, it will be listed below in brackets (example).





Scope of spaces



The view from which spaces are listed. Available options are:

  • all – All spaces in the Confluence installation.
  • category – Spaces grouped according to space categories.
  • favourite – Spaces which you have added to your favourites list.
  • new – New spaces which have been created within the last 7 days.

This parameter is unnamed in wikimarkup and storage format.

Width of List



The width of the spaces list, specified as a percentage (%) of the window width.

Code examples

The following examples are provided for advanced users who want to inspect or edit the underlying markup for a Confluence page. 

Macro name: spaces

Macro body: None.

Storage format example

Wiki markup example

  • No labels


  1. Need to add a type of "personal" to see a list of the personal spaces.

  2. Is there any way to render the spaces list without the tabs and extra interface?
    We've only got about 5 spaces in our wiki and i'd love to have a "quick list" in a side panel

    1. The Reporting Plugin will let you do that (and more). Something like:

      1. David, a good proposal. It seems that the original spaces macro is quite slow to render when 150 or more space are listed. With the space-reporter it renders much quicker.


  3. I'd like to change the dashboard page so that the descriptions aren't rendered with the space names.  Is there a way to not display space descriptions?

    1. Hi Tracy,

      The space list on the dashboard is built using the {spaces} macro of Confluence Dashboard Macros. As far as I am concerned, you can try to modify spacelist-drawspacerows.vm to exclude the space description. The file is located at:

      • In 2.8.*: <confluence-install>/confluence/template/includes/spacelist-drawspacerows.vm
      • In 2.9.*: <confluence-install>/confluence/WEB-INF/classes/com/atlassian/confluence/setup/

      Please note this may require some knowledge in HTML and Apache Velocity. Hope that helps.


      1. Perfect - worked like a charm - Thanks

      2. Hi,

        I am trying to customize the space list that shows up on the dashboard so that a space with a particular spacekey will NOT show up in the list.  I was thinking of using an IF statement somewhere in the Velocity file that creates the list of spaces, and thought that file might be spacelist-drawspacerows.vm.  But, I'm not finding a file with that name.  What file stores the list of spaces in Confluence 2.10.3 (on Tomcat)?



  4. Anonymous

    Having a tab option for Favorites would also be great.

    1. Hi,

      If you are keen on this feature, I would suggest you to raise an improvement request at it's issue tracker


  5. Anonymous


    I have my template designed in such a way that there is a drop down menu which lists all the spaces there. But what I essentially want is to see only spaces related to specific teams? Is there a way to do that?



  6. Anonymous


    I'm trying to use {spaces:myteamlabel} (or {spaces-list:myteamlabel} but this would show 4 different tabs: my, new, all, and team.  Isn't it possible to show just the team label?



    1. Hi Susana,

      As described in the 'Parameters' section on this page, you can restrict this macro to show only the 'team' tab by using the wiki markup syntax:
      (i.e. you just need to add the 'team' value to the macro's wiki markup syntax)

      Alternatively, if you want to avoid wiki markup syntax, you can insert this macro (with this parameter value) using the macro browser. (In the macro browser, this macro is called, unsurprisingly, "Spaces List".)

      When viewing this macro in the macro browser's 'preview mode', select 'team' in the 'Scope of spaces' parameter before inserting it on the page.

      I hope this information helps.

      Kind regards,
      Giles Gaskell.

  7. there used to be a listspaces macro that would list all the space admins but it does not seem to be working in 3.1.2.  Is there a replacement?

    1. Hi Stacy,
      Do you have any documentation reference for listpaces macro? I can't seem to find it from any of our documentation, nor google. Currently, this feature is not support in Confleunce UI, however, the space admin can be retrieved from database via sql query:

      Group level

      select PERMGROUPNAME from spacepermissions where PERMTYPE = 'SETSPACEPERMISSIONS';


      individual level

      select PERMUSERNAME from spacepermissions where PERMTYPE = 'SETSPACEPERMISSIONS';

      Hope it helps. Please feel free to ask again if you need further assistance.

      Thanks & regards,

  8. Anonymous

    Oops! Tags are going mad!

    Full text here:

    Say please, what file in Confluence 3.2 may I modify to change an appearance of spaces macros? And where can I find this file?

    In instance, I want to remove "favorite-space" stars and make my own tabs for spaces of group 1 and group 2 (not just all / favorites).

    Thank you.

  9. Favorites stars disappear when displaying spaces by label:

    When I use the macro {spaces} or {spaces-list} 3 little action icons appear next to each space (Browse Space, Add Page, Favourite).

    But when I limit the macro to a particular label, like this: {spaces:labels=blog}, the 3 icons don't appear next to the spaces in the list.

    Can you please help? Or can you please suggest another way to easily favourite a space other than using the {spaces} macro and showing a list of all spaces.



  10. Is it possible to limit the "scope of spaces" using more than one tab?

    i.e. I want to show the "My", "New", and "All" tabs, but not the "Team" tab.

  11. Anonymous

    After upgrading to Confluence 3.5 I have problems with the spaces macro.

    First, there seems to be no German text for "spaces.groups.word", because that Tag is shown.

    The more serious problem is, that I get a JavaScript error when clicking on the tabs. It says that the method "gotoUrl" is not defined. I get this error whis IE7 and Firefox 3.6.

    1. Anonymous

      Problem solved! I deactivated the subspace-plugin. Now everything is fine

  12. Would be very nice to have the icon next to the space names be the space-logo if it is enabled.   Any idea if this is possible? 

    1. This is definitely something we are also looking for. If someone knows how to do this it would be great!

      1. Hi Benjamin,

        There's an open improvement request for this. Feel free to comment on it to add your voice, and watch it to get any updates.

        CONF-24787 - Spaces Macro should display space logos Open

  13. Anonymous

    Accidentally I tried sth. like this on Confluence 3.5.x

    A hidden parameter to filter according to space labels (not category)? The result is a list of all spaces with this space label and the scope parameter "category" is ignored. What happens exactly?

    1. Anonymous

      In addition, what is the most simple (build in) way to list all spaces for a specific category (formerly know as team labels and used in that way). Thx!

  14. Warning. In Confluence 4.1, if you use the Spaces List macro with "Scope of spaces" set to "favourite" and you have users who have NO favorite spaces yet, they will all get this error message:

    You currently do not have any spaces on your favourites list. To add one, click the All tab and then on  next to the spaces you want to add as favourites.

    However, there is NO All tab on which to click, and moreover, the Javascript driving the drop-down menus on the page (if you are using a standard theme which has them) get messed up.

  15. I want to expose a page with the list of all available spaces and the respective space admins. This is just for the users reference to contact their respective space admins.  Is there any easy way to achieve this?


      You ever have the chance to get this to work?

  16. Anonymous

    The space list macro has been broken since version 4.1.  Maybe you should put a note on this page that this feature isn't actually available?

    1. Hallo there

      I've tested the macro in Confluence 5.0, and it's working. I've also looked in our issue tracker for a related issue but couldn't find one. Please could you let us know how it's broken, or point to the relevant issue so that I can add it to the page?

      Many thanks, Sarah

      1. Hi Sarah,

        If that's true, that's great news!  The bug we're talking about can be found here:

          CONF-26597 - Changing category in Space List macro generates wrong URL Resolved

        1. Hallo Jason

          Ah thanks, I hadn't spotted that one. Indeed, it's not nice. I've added the results of my testing to the issue, and added a note to this page too.

          Cheers, Sarah

          1. Thanks, Sarah!  I appreciate you taking the time to look into it.  We have dozens of spaces, and this macro is really the key to making it all user-friendly.  I really hope your dev team has the time to look into it soon.


            PS: "Confluence, Tech Comm, and Chocolate " = great book! It really helped shorten the learning curve for me.  (smile)

  17. Perhaps I am blind and this is a stupid question: 
    Is there a way to list spaces according to a SPECIFIC space category?

    I know the macro "space-list" and it's category-option that generates a form where I can choose a category.

    What I need is a space list for a given category. Something like the old space labels feature:


    Which is still working for very old spaces, but not for new ones.

    Any suggestions apart from commercial plugins?



    1. Did you ever get an answer? I have this exact question.

      1. Hi Holly and Matthias,

        There's unfortunately no way to set the default category for the spaces list macro. The only option is to have the category menu at the top of the macro, which allows you to choose the category when you're viewing it.

        There's an open improvement request you can watch though, to see if there's any changes:

        CONF-25148 - Enforce a category in the spaces list macro Open

        If you're looking for a list of spaces by category, not in a macro, it's available in Spaces > Space directory, then choose any category on the left. This page has more info on that topic.

  18. I can't seem to remove archived spaces from the space list, even though they aren't showing on the space directory page. Anyone running into similar issues?

    1. Hi,

      I have the same issue: the default dashboard does not show archived spaces whereas when I use this macro, archived spaces are displayed and there's no way to remove them. Could there be an update to select if archived spaces need to be displayed or not ? Thanks

      1. I ended up contacting support about it. Apparently, because I was an admin, I still saw the archived spaces, but none of the regular end users did.  Since I was the only one effected, I just left it.

        1. Hi Zoe,

          Well, my test user, non admin, is seeing archived spaces (sad)

      2. This is a known issue I'm afraid - see  CONF-33836 - Spaces List Macro should not list archived spaces Open .