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 Livesearch macro allows you to add a search box to a Confluence page. When users enter a search term into the search box, Confluence will dynamically display matching results as they type.

Using the Livesearch macro

To add the Livesearch 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).




Restrict to this Space Key

all spaces

Specify a space key to limit the search to the given space. Case-sensitive.

Restrict to label(s)
 Specify labels to limit the search to content with that label. If unspecified will search all content regardless of label.
mediumChoose a medium or large search field size.
Placeholder text
 Specify the placeholder text to appear in the search field, for example 'Search this space'
allSpecify the content types to be included in the search - choose from pages, blogs, comments, space descriptions, or all content types.
space nameDisplay the space name, a page excerpt or nothing under the search result.

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: livesearch

Macro body: None.

Storage format example

Wikimarkup example


  1. Am trying to use this in velocity template with 

    Does not seem to work?

    1. Hi Mark,

      The spacekey with the "@self" parameter doesn't supported in LiveSearch macro. It has to be with the space key in Confluence. However, if you are keen to have this feature to be implemented in the future macro version, you can always raise a feature request at


        1. That comment was from me; sorry.

  2. I love this macro! It's so helpful, and we've now just begun to use it in customized left nav's, which can be really helpful to the space.

    We're encountering some problems with the drop-down list of candidate terms that appears when searching using this utility. For example, in a given wiki space:

    • searching "cache" yields nothing in the drop down (even there are multiple pages with this word in the title)
    • searching for "documents" = nothing in drop down (at least one page with term in title)
    • searhing "document" = extensive drop-down list (including the page with 'documents' in title)

    Performing the search (eg clicking 'Go') yields in appropriate search results for each of the above examples. It's only the drop-down list that isn't consistently functioning.

    The problem is also happening in at least one other space in our instance of Confluence. In both cases, livesearch is inside a table as follows:

    || Search || Browse || Projects ||
    | Search this wiki {livesearch:id=1|spaceKey=gregwikiprod} |

    Any tips?

    Margaret Ostrander

    1. Hi Margaret,

      To enable us to investigate this issue further, I would suggest you to raise a support request in our Support Channel regarding this issue:

      Please also provide us with the following information on the support request created as they may be helpful in our investigation:

      1. A screenshot illustrating the Live Search Macros available in the Administration > Plugins page
      2. A HTML of the System Information page


      1. Anonymous

        Thanks Tony!

        - Margaret

  3. Is there a way to provide a search field, which searches in n spaces? Not one or all, but multiple spaces?

    1. Hi Stefan,

      As far as I am concerned, the parameter 'space' accepts just one space name to be searched. Perhaps the following improvement request will enable multiple spaces searches in future.

      Vote for it and feel free to add yourself as watcher.


  4. Just a small thing, but I was wondering if there was any way to include Mail items in the default search so that mail items show up in the drop-down?

    1. I have created an improvement request at the plugin's issue tracker. Remember to cast your vote on it!

  5. Anonymous


    I tried to use this macro, but what is spaceKey? Can I assign more than one spaceKey to a livesearch? If I can, how can I write the code? Thank you.


    1. Anonymous

      the "spaceKey" is found in the URL of the wiki. For example, in this wiki, the spaceKey is "gregwikiprod". It's something that you have to define when first creating a wiki space.

  6. Hi,

    I would like to restrict my search to a specified space. So I use the spaceKey parameter and the drop-down menu works well.

    But when I click on the "Go" button, my results are not filter by space anymore.

    Is there a way to solve that problem ? (my version of Confluence is 2.9.2)



    1. Hello Math,

      Good news is, it has been fixed in the plugin version 2.10. The downside is, it is not compatible with Confluence 2.9.x, hence you might want to consider your instance for an upgrade (smile)

      Hope that helps,

  7. Anonymous

    Really kewl!  My only problem with this macro is that even though everything seems to work in IE6, I get a javascript error (exclamation inside yellow triangle) with the message: 'target.form' is null or not an object.  Have you all seen that in IE6?  I know I'm living in the past, but IE6 is still the standard where i work(sad)



    1. Hi,

      I could not replicate the problem, could you please provide me the plugin version you are using?

      Best rgds,

    2. Anonymous


      i've the same problem in ie6 using the livesearch macro 2.8



      1. This seems to be a known issue for the plugin - Please note that this bug has been fixed in plugin version 2.10. Please check the compatibility of that plugin version with your Confluence version before upgrading the plugin.

  8. Anonymous

    I've run into a weird situation with my livesearch macro. I'm using the spacekey to limit it to the appropriate space.
    I have several pages about meeting minutes, with the words "meeting" and "minutes" appearing in the body of the text and sometimes in the title of the page. When I start typing "meet," those pages appear in the results box; however, these results disappear if I keep typing past "meeti." If I hit "go" it takes me to a blank results page, but the pages show up if I manually remove the * wildcard from the search box.

    Any idea what's happening here? It doesn't make sense to me that results disappear when I type more of a word, even though the whole word appears on the page...

    1. Hi,

      I believe you are encountering this bug. Although it has been resolved as fixed, the issue is still present as I am able to reproduce the issue myself. I have put a comment in the bug report so that the developers will take note of the problem.

      As a workaround, would you be able to use the backslash after the search string as mentioned in the bug report?


  9. Anonymous

    since upgrading to 2.10.3 our live search macro has been behaving strangely. For example, the word "macros" appears on the title of a few pages. When searching for "macros" however, we get a null set (no results). However, when searching the singlar "macro", the pages with "macros" do appear.  Is there a bug with how stemming is working? Please advise.

    1. Hi,

      I believe you are encountering the same problem as the person above. I would suggest you to add yourself as a watcher for this bug report and feel free to comment or address your concerns through it. Sorry for any inconveniences.

      As a workaround, would you be able to use the backslash after the search string as mentioned in the bug report?


      1. Anonymous

        Unfortunately, the backslash workaround doesn't work in our environment. The backslash causes a security related error.

        I'm passing along the bug report to our technical team for further follow-up. Thanks much for the information.

        Margaret Ostrander

        Thomson Reuters

        1. Hi Margaret,

          May I know what security error that you have encountered when using the backslash? If this is difficult to explain, I would suggest you to raise a support ticket to, so that your issue can be further investigated. Also provide the following:

          1. A copy of your Confluence log file located at <confluence-home>/logs/atlassian-confluence.log
          2. The system information page. You can obtain the page by accessing the http://<path-to-confluence>/500page.jsp
          3. Screenshots that illustrate the problem.


          1. Thanks Sashi. We'll pursue through the methods you suggest -- I'm passing this along to our technical team who will be better able to article what the error is, as it is somewhat complicated. I really appreciate the quick information.

            1. No worries, Margaret. We will wait for the support ticket for further investigation.


  10. Anonymous

    Hi, same livesearch problems here. We have installed Confluence 3.02 and Themebuilder 3.3.5-M2-conf210. Workaround with Backslash works but is not really satisfying :(

    1. Hi,

      I understand that the workaround might not be suitable in all cases. I have informed the developers regarding this issue and we are in the midst of investigating further on the issue. I would suggest you to add yourself as a watcher for the mentioned bug report and feel free to comment or address your concerns through it.

      For further details on how we include new features and improvements, you might want to read this page


  11. Hi,

    is ist possible to use the macro in the velocity-context ( like #quicksearch() ) ?

    1. If you would like to achieve this via the Admin Console->Layout screen, you can use the $helper context:

      1. Azwandi, I tried doing this in the Global Layout page (confluence 4.1.2) and the Livesearch appears to be broken. Is it possible in the Global Layout?

  12. We are using livesearch within a theme builder site.  When the search is done with more that the default items and we click on the second page, we lose our theme and it goes to the default theme.  The first page of results is with our page.  Is there any way to express the number of results or make it so the second page does not go to the confluence search page

  13. Hi,

    Would love to use the livesearch macro, but I have one quick question. Is there a way to limit the search only to pages, but not users, comments, etc. I used the type=page, but it did not work. Can you help? Thanks in advance...

    1. Hi Basak,

      I am afraid that this is not currently possible. Feel free to raise a feature request at and describe in detail how you require this feature to work. Please add yourself as a watcher, vote for this feature and add your own comments to this feature request. For further details on how we include new features and improvements, you might want to read this page

      Hope that helps.


      1. Thank you very much for your reply Sashi. I, infact, saw one example at a knowledge base site:

        See the search box in the middle. It acts like it is restricting user pages from the search results, no?


  14. Anonymous


    Whenever I start typing a word in our livesearch (which only searches a certain space), the drop-down box displays the proper pages. However, as the word gets longer, the pages disappear as if none of them contain the word. Then, if I press "Go," the search results page doesn't have any results, and the search term I typed has an asterik added to the end. If I remove the asterik and press "Go" again, the search results are correct. Is there any way to fix that?


    1. Hi,

      If you are using Confluence version prior to 3.2, I believe you are encountering this bug in Livesearch Macro. This is fixed in Livesearch Macro version 2.11.1 which is bundled in Confluence 3.2 or higher. As for the best resolution, I would strongly suggest you to upgrade your Confluence instance to the latest version.

      If you are using Confluence 3.2 or higher, I would suggest you to raise a support ticket to, so that your issue can be further investigated.


  15. Anonymous

    I am trying to make the livesearch macro wider but cannot find how to do this. Is there any way such as editing the macro file itself to make this happen?

  16. Anonymous


    Whenever I tried to search a word/content in our confluence it is giving me only the result of the page which has its result on the body, but whenever I clicked it, it doesn't direct me to the exact word. 


    How I will be able to get this search feature in our confluence since I am using composition plugin with cloaking feature?

  17. Anonymous

    When I try to search with multiple words (eg. "Buy some milk"), the dropdown list under the search box is no more updated after I typed the first space in my query. Is it possible to get a preview with multiple words in a query ?



  18. When I use Livesearch the results appear to be restricted to 10 items.  Can I increase this?  If not, how does it determine which items to list in the search results?


  19. Anonymous

    Can we replace the "Go" button with "Search" text and icon similar to Confluence Search

  20. Anonymous

    When I try to set the “Restrict to this Space Key” property to "KB" (our case-sensitive space key), I get a “Not Found” error.  What does this mean, and how can I resolve it?

  21. Anonymous

    Is it possible to change size ( width ) search field in this macro? If yes please tell me how to do this.



    1. You can't explicitly set a width, but we have introduced a new size parameter with Confluence 5.3 supporting medium/large sizes. With this and a combination of page layouts/alignment, you can make it look prettier now (smile)

      1. Actually you can explicitly specify a width by using css. If you have admin privileges on the space you can add the following to the stylesheet:

        The max-width is required as well as the width to override the max-width set in the default css.

        If you don't have access to the stylesheet then on the page where your livesearch is, add an html macro as follows:

        The result in my case looks like this:


  22. Is it possible to limit the LiveSearch macro to a certain category?

    1. Hi Brendan, sorry it is not possible to restrict to a category. 

  23. Anonymous

    The following markup fails for this macro:

    The livesearch still shows results outside of this label restriction.  Information for the parameters is based on this current content:

    Confluence Wiki Markup for Macros

    I'm using Confluence 5.1.

    Any ideas?

  24. We are simplifying our team home pages. We are going for a google kind of look, using the livesearch macro. Since we have an info box under the search, the results end up behind the info box. Is there a way to make the results display in front instead?

    Thanks for any suggestions.

    1. What version of the macro/confluence are you using? I believe we fixed this in later versions (if you see a new size parameter for large - it should be fixed in that version). 

  25. The livesearch aspect correctly restricts its results to the specified labels, but as soon as you click through to the full Search page, you get search results for all labels, not the one(s) you specified.

  26. Hi, 

    We're using Livesearch with Confluence 5.4.3 and experiencing some of the anomalies that people describe above, that were said to have been resolved.

    e.g If we enter "repos" (without pressing enter) we correctly get a dropdown list of suggested pages including references to "repository".  If, we then carry on typing "reposi" then previously suggested terms disappear.  I would attach a screenshot but I don't seem able to.

    This seems to be a bug - or is there another explanation?


  27. It seems that you have to write the whole page name to search bar for the drop down to work (for us), and in case of pages with two parted names you have to write the whole of the first part for the drop down to work. This is counter intuitive. 

  28. We are using Confluence 5.6.1 and there seems to be a lot of bugs with this search, eg. autocomplete not working for part of names, only full names, finding (correctly) attachments, but if you click on the attachment name an error is shown telling you the page does not exist, just to mention the really bad ones. Why dose this not just work like quicksearch GG? Please fix this! It would be very handy for searching only one space!


    1. Hi Maximillian, could you please raise a support request about this - sounds like there might be a problem with your index.  Support will help you troubleshoot what is going on and raise a bug if necessary. 

    2. the error that occurs with attachments containing spaces or non-inglish characters is reportet on CONF-32869 - Live Search Macro fails to open attachments that contain spaces in the name. Resolved

  29. Hi there,

    we are facing also strange issues in Confluence (5.5.3) with the live search macro (3.0.7). The list of possible matches works only in IE9, but not in Firefox (32.0.1) or Chrome (37.0.2062). Does anybody else has this problem?


  30. Well, I have a few pages which act as FAQ's for some domains.In order to keep the page somewhat comprehensible. I jhave used the Expand macro.

    The Question is in the expand Macro and the answer is of course in the text field when expanded.

    Unfortunately it seems that the title of the expand macro is not searchable (sad)

    Any ideas of how to overcome this?

    1. Hi Timothy,

      Unfortunately it doesn't look like there are any plans to include these expand titles/labels in search.

      CONF-30038 - Include the 'Expand macro' title in searchable content Resolved

  31. Hi all,

    Using the Livesearch macro with Confluence v5.7.3, is it possible:
    - to search for users subscribed to the current wiki space;
    - to display results in the current wiki space, and not in the "global" wiki results page? Indeed, it makes user leaving the current wiki space and confuses them.


    Thanks in advance,

    1. Hi Nicolas,  

      The Livesearch macro only searches content (like pages and blogs) I'm afraid - it doesn't not search people. 

      There's no way to present the search results page within the current space however. The Livesearch macro does a pretty good job of suggesting matching pages in a dropdown, but if the user hits the enter key, or 'see more results' they will land in the full Confluence search page. 

  32. Hi Nicolas,

    We discovered that the livesearch macro doesn't work with the mobile version of confluence. Is there something planned that it will also work with the mobile version? If yes, can you estimate when?

    Thank you in advance!

    1. Hi Christoph,

      To which Nicolas do you seek out? Because I'm not in charge of implementing such solutions (smile)