Instant Search for Confluence
Instant Search adds a search box to any Confluence page. Results appear while you type: there is no need to press Enter or to leave the page. The search is not case sensitive, accepts several words, and can be narrowed with filters, so a page can offer a search of exactly the content its readers need: one space, one label, one content type.
Typical uses are documentation spaces, knowledge bases, help desks, and QA or document libraries where readers need to find a page quickly.
Versions
Instant Search is available for Confluence Cloud and Confluence Data Center.
| Confluence Cloud | Confluence Data Center | |
|---|---|---|
| App version | 4.x | 3.x (2.9 for Confluence 7 and 8) |
| Compatibility | Confluence Cloud | 3.1: Confluence 10.0 to 10.2. 3.0: Confluence 9.0 to 9.5. 2.9: Confluence 7.15 to 8.9 |
| Type-ahead search box | Yes | Yes |
| Filters (space, label, content type, contributor and others) | Yes | Yes |
| Extra details in results (space, labels, dates, likes) | Yes | Yes |
| Popular searches and searches with no results | Yes | Yes, with the Instant Search Log Table macro |
| Styling with your own CSS classes | No | Yes |
| Wiki markup form of the macro | No | Yes |
The options described on this page have the same names and meaning in both versions unless a section says otherwise.
Install the app
Confluence Cloud
- As a site administrator, open Apps and go to the Atlassian Marketplace (Explore more apps).
- Search for Instant Search for Confluence.
- Select Try it free or Buy now and confirm.
Confluence Data Center
- Open Administration > Manage apps > Find new apps.
- Search for Instant Search for Confluence.
- Select Free trial or Buy now and follow the steps to get a license.
No further setup is needed. The app uses Confluence's own search index, so there is nothing else to install or configure, and results respect each reader's permissions: a reader only sees content they are allowed to view.
Add a search box to a page
- Edit the page where the search box should appear.
- Type
/instant search(Cloud) or{instant(Data Center), or open the macro browser and choose Instant Search. - Set the options you need. The preview shows the search box as readers will see it.
- Insert the macro and publish the page.
With no options set, the box searches all content the reader can view and shows up to 5 results with a short excerpt.
To use it, start typing in the box. Results are listed under the box and update with every keystroke. Select a result to open it.
Options: search box
These options change how the search box looks and behaves.
| Option | What it does | Default |
|---|---|---|
watermark |
Hint text shown in the empty box. @self is replaced with the name of the current space. |
|
inputFieldWidth |
Width of the box, as a CSS width, for example 200px. |
300px |
showSearchButton |
Shows or hides the search button. | shown |
searchButtonHTML |
Text of the search button. @self is replaced with the name of the current space. |
|
focus |
Puts the cursor in the box when the page loads. | false |
tabOrder |
Position of the box in the page's tab order. | |
track |
Records what readers search for. See Search tracking. | false |
Options: results
These options change what each result shows.
| Option | What it does | Default |
|---|---|---|
limit |
Largest number of results listed. | 5 |
excerptLength |
Rough length of the excerpt under each result, in characters. Set it to 0 to show no excerpts. |
40 |
resultWidth |
Width of the results box, for example 400px. |
|
showSpaceKey |
Shows the space of each result. | false |
showLabels |
Shows the labels of each result. | false |
showBreadCrumbs |
Shows where each result sits in the page tree. | false |
showDateCreated |
Shows the date the content was created. | false |
showDateLastModified |
Shows the date the content was last changed. | false |
showLikes |
Shows the number of likes. | false |
sortLikes |
Sorts results by the number of likes: asc or desc. |
|
hideExcerptMacro |
Leaves the text of the page's Excerpt macro out of the result's excerpt. | false |
hideText |
Hides text in the excerpts that matches a regular expression (Java syntax). Separate several expressions with _,_. |
|
replaceText |
Text shown in place of what hideText hid. Separate several replacements with _,_, in the same order. |
empty |
Options: filters
Filters decide which content the box searches. Several filters can be combined.
| Option | What it does |
|---|---|
spaceKey |
Searches only the given space. Separate several keys with commas. @self means the space the page is in. |
type |
Searches only the given content types, separated by commas: page, blogpost, comment, attachment, userinfo, spacedesc, personalspacedesc, space, draft, mail, custom. |
label |
Searches only content with these labels, separated by commas or spaces. By default one matching label is enough. Put + before a label to require it, or - to leave out content that has it. |
spaceCategory |
Searches only spaces of the given category type. |
spaceLabel |
Searches only spaces with the given space categories, separated by commas. |
contributor |
Searches only content the given user has contributed to. |
lastModified |
Searches only content changed within a period: 3d is the last 3 days, 1m3d is the last month and 3 days. |
likesFilter |
Keeps only results with more or fewer likes than a number: >3 means more than 3 likes. |
filter |
Keeps or drops results by their URL. Put + (the default) before a text to require it in the URL, or - to drop results whose URL contains it. Separate several with commas or spaces. Keywords, used alone: @none (the default), @self, @parent, @home. |
Examples
Each example lists the options to set in the macro.
| What you want | Options |
|---|---|
| A search of one space that shows the space key and has no button | spaceKey = DOC, showSpaceKey = true, showSearchButton = false |
| A compact search of one space's pages, for a sidebar | spaceKey = DOC, type = page, limit = 3, inputFieldWidth = 200px, excerptLength = 0, watermark = Search articles |
| Pages changed in the last 3 days, with the date shown | spaceKey = DOC, type = page, lastModified = 3d, showDateLastModified = true |
| Only content that has all three labels | label = +atlassian,+confluence,+content |
| A search of the current space, wherever the page is copied to | spaceKey = @self, watermark = Search in @self |
Wiki markup (Data Center)
On Data Center the macro can also be written as wiki markup. Use this form where the macro browser is not available, for example in a space sidebar, a layout or a template. Options are separated with |.
{instantsearch}
{instantsearch:spaceKey=DOC|showSpaceKey=true|showSearchButton=false}
{instantsearch:spaceKey=DOC|type=page|limit=3|inputFieldWidth=200px|excerptLength=0|watermark=Search articles|showSearchButton=false}
{instantsearch:spaceKey=DOC|type=page|limit=3|lastModified=3d|showDateLastModified=true}
{instantsearch:spaceKey=DOC|label=+atlassian,+confluence,+content|excerptLength=0}
{instantsearch:spaceKey=@self|label=+atlassian,+confluence,+content|filter=@self}
{instantsearch:spaceKey=DOC|showLabels=true|showBreadCrumbs=true|hideExcerptMacro=true|inputFieldWidth=200px}
{instantsearch:spaceKey=DOC1,DOC2|resultWidth=400px|focus=true|track=true}
Styling with CSS (Data Center)
On Data Center each part of the search box can be given your own CSS class, so the box matches the look of your space. Define the classes in the space or site stylesheet, then name them in the macro.
| Option | Part it styles |
|---|---|
searchClass |
The search box as a whole |
inputClass |
The text input |
watermarkClass |
The hint text in the empty input |
searchDivClass |
The container of the search button |
searchButtonClass |
The search button |
resultClass |
The results box |
{instantsearch:spaceKey=DOC|resultClass=mystyle|resultWidth=400px}
Replace the Confluence search box (Data Center, experimental)
The option makeGlobal replaces the search box in the Confluence header with Instant Search on the page that holds the macro. Placed in a space's sidebar or layout, it does so for the whole space.
{instantsearch:makeGlobal=true}
This option is experimental: check it on a test page before you use it for a whole space.
Search tracking
With tracking on, Instant Search records what readers type into the box and whether anything was found. Two lists come out of it:
- Popular searches: what readers look for most. These are the pages worth keeping up to date and easy to reach.
- Searches with no results: what readers look for and do not find. These point to missing content, or to pages that need other words or labels.
Tracking is off by default. Turn it on for a search box with the option track.
Only the search text is recorded. Nothing that identifies the reader is stored with it. On Data Center the records are kept in your own Confluence database and never leave your server.
See the results (Data Center)
Add the Instant Search Log Table macro to a page, for example a page only space administrators can view:
{instantsearch-log}
{instantsearch-log:showFailedTable=false}
The macro lists the tracked searches in tables. showFailedTable=false leaves out the table of searches with no results.
Help & Support
Please raise a support request here, or email us at support@votazz.co.