Spaces List Macro

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 Autocomplete for links, files, macros and mentions.

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

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

42 Archived comments

  1. User avatar

    Garnet R. Chaney

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

    14 Dec 2006
  2. User avatar

    Aaron Wallis

    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

    03 Feb 2008
    1. User avatar

      David Peterson [CustomWare]

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

      03 Feb 2008
      1. User avatar

        Stefan Baader

        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.


        15 Dec 2008
  3. User avatar

    Tracy Adams

    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?

    08 Oct 2008
    1. User avatar

      Azwandi Aris [Atlassian]

      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.


      16 Oct 2008
      1. User avatar

        Tracy Adams

        Perfect - worked like a charm - Thanks

        31 Oct 2008
      1. User avatar



        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)?



        26 Aug 2009
  4. User avatar


    Having a tab option for Favorites would also be great.

    17 Oct 2008
    1. User avatar

      Azwandi Aris [Atlassian]


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


      22 Oct 2008
  5. User avatar



    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?



    16 Nov 2009
  6. User avatar



    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?



    05 Jan 2010
    1. User avatar

      Giles Gaskell

      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.

      06 Jan 2010
  7. User avatar

    Stacy Shenker

    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?

    16 Mar 2010
    1. User avatar

      Jack Low [Atlassian]

      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,

      17 Mar 2010
  8. User avatar


    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.

    17 Jun 2010
  9. User avatar

    Dhyana Scarano

    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.



    15 Sep 2010
  10. User avatar

    Dhyana Scarano

    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.

    21 Mar 2011
  11. User avatar


    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.

    24 Mar 2011
    1. User avatar


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

      24 Mar 2011
  12. User avatar

    John Brandt

    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? 

    10 Aug 2011
    1. User avatar

      Benjamin Mårtensson

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

      27 Feb 2015
      1. User avatar

        Giles Brunning [Atlassian Technical Writer]

        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

        01 Mar 2015
  13. User avatar


    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?

    09 Sep 2011
    1. User avatar


      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!

      09 Sep 2011
  14. User avatar

    Chris Johnson

    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.

    07 May 2012
  15. User avatar

    srinivas patruni

    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?

    30 Aug 2012
    1. User avatar

      Marten Vanderheiden


      You ever have the chance to get this to work?

      28 Mar 2013
  16. User avatar


    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?

    24 Feb 2013
    1. User avatar

      Sarah Maddox [Atlassian]

      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

      24 Feb 2013
      1. User avatar

        Jason Plumhoff

        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

        25 Feb 2013
        1. User avatar

          Sarah Maddox [Atlassian]

          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

          26 Feb 2013
          1. User avatar

            Jason Plumhoff

            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)

            26 Feb 2013
            1. User avatar

              Sarah Maddox [Atlassian]

              Oh wow, thanks. (smile)

              26 Feb 2013
  17. User avatar

    Matthias Born

    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?



    05 Dec 2013
    1. User avatar

      Holly Hayes

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

      28 Oct 2014
      1. User avatar

        Giles Brunning [Atlassian Technical Writer]

        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.

        28 Oct 2014
  18. User avatar

    Zoe Jong

    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?

    09 Jan 2014
    1. User avatar

      Confluence Administrators Stromasys


      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

      02 Oct 2014
      1. User avatar

        Zoe Jong

        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.

        02 Oct 2014
        1. User avatar

          Confluence Administrators Stromasys

          Hi Zoe,

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

          02 Oct 2014
      1. User avatar

        Rachel Robins [Atlassian Tech Writer]

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


        02 Oct 2014
Powered by Confluence and Scroll Viewport