The Confluence Live Search macro: what it does, and where it breaks

A search box sitting on a page looks like the obvious way to help people find things. It works, but not in the three ways most teams assume.

Short answer. Yes, Confluence Cloud has it. In the editor type /live search and insert the Live Search macro. You get a search field on the page, and you can restrict it to a space key, to one or more labels, and to a content type, plus set the field size, the placeholder text, and what appears under each result. What it does not do: it does not search the page it is sitting on, it cannot match the middle of a word, and it shows nothing at all until a reader types something.

What the macro actually is

The Live Search macro is a search field rendered inside page content. Someone starts typing, and Confluence suggests matching content underneath. The parameters Atlassian documents are these:

• Restrict to this Space Key — a space key, case sensitive, or @self for the space the macro lives in.
• Restrict to label(s) — limits results to content carrying those labels.
• Size — medium or large search field.
• Placeholder text — what the empty field says, for example Search this space.
• Type — pages, live docs, blogs, comments, space descriptions, or all content.
• Additional — whether to show the space name, a content excerpt, or nothing under each result.

That is a reasonable feature, and for a space landing page with a clear audience it does its job. The trouble starts where expectation and behaviour part ways.

Three things people expect and do not get

It does not search within the page

This is the most common misunderstanding, and it is baked into how people search for the feature: live search within page. The macro is placed on a page, but it searches the space, or whatever labels you restricted it to. The text of the page the reader is looking at is not what it looks through.

If the goal really is to find a word on the current page, nothing in Confluence beats the browser: Ctrl+F, or Command+F on a Mac. No macro needed, and it searches what is actually on screen.

It cannot match the middle of a word

The macro uses ordinary Confluence search, so it inherits a rule that surprises people. Atlassian's search syntax documentation puts it plainly:

Confluence doesn't allow wildcards at the beginning of your search. For example, you can't search for *hum* or ?hum*, as they begin with a wildcard.

In practice that means budget* finds budgeting and budgets, but there is no way to find annual-budget-2026 by typing budget if the word starts somewhere else in the title. The reader types a word they are sure is in the document, gets an empty dropdown, and concludes the page does not exist. It does. The search just cannot start in the middle.

This hits hardest in spaces where titles follow a convention, because conventions tend to put the useful word last: 2026-Q3-Finance-Budget.

It shows nothing until someone types

A search field is a question waiting for a question. It assumes the reader already knows what they are looking for and can name it in the same words the author used. New joiners, auditors and anyone arriving from a link do not meet that assumption. They look at an empty box and leave.

There is a second, quieter cost: a search box leaves no trace of what is in the space. A list does. Anyone glancing at a page with twelve linked documents learns the shape of the space in two seconds, without typing anything.

When a search box is the wrong tool

Use the macro when the reader knows the name of the thing and the space is large: a knowledge base with hundreds of articles and a clear naming scheme is a good home for it.

Reach for a list instead when any of this is true:

• the reader does not know what exists and cannot name it;
• the set of pages is defined by a rule rather than a word, such as everything in a space with a given label, or everything not updated in six months;
• the page is meant to be an index that someone will link to and cite;
• you want the page itself to show that the documentation is alive.

The hand-maintained index, and why it dies

The usual answer to all this is a page of links written by hand. It works beautifully for about a month.

Count the real cost. A team space gains and retires maybe eight pages a month, which is modest. Keeping an index honest means checking it roughly every two weeks: fifteen minutes to walk the space, find what is new, drop what has been archived, fix the titles that changed. Call it thirty minutes a month, six hours a year, for one index. Teams that take documentation seriously keep four or five of them.

What actually happens is that nobody does it. The index drifts for a quarter, somebody notices a dead link in a meeting, and it gets rebuilt from scratch. Then the cycle repeats.

A live list instead

The alternative is a list defined once by conditions and rebuilt by Confluence every time the page is opened: a space, a label, a content type, an age. Nothing to maintain, nothing to retype, and the page reads as an index rather than an empty box.

Disclosure: I build one of these. Our Smart Search macro puts that list on a page from plain conditions, without anyone writing a query language: choose a space, add labels, say not updated for 180 days, and the list keeps itself current. It is free for up to ten people, and it runs entirely inside your own site.

If your case is simpler than that, use what you already have. One space, a clear naming convention and readers who know the vocabulary — the Live Search macro is free, it is already in your editor, and it will do the job.

Questions people actually ask

Where is the Live Search macro in the new editor? Type /live search on a page and pick it from the list. It is a standard macro in Confluence Cloud, nothing to install.

Can I restrict it to more than one space? The space parameter takes a single space key, or @self for the current space. Covering several spaces means several macros, or restricting by label instead and labelling consistently across spaces.

Why do my results change depending on whether I press Enter or click through? With two or more labels this used to differ: pressing Enter required all labels to match, while the suggestion list showed pages with any of them. Atlassian tracked that as CONFCLOUD-53716, it collected 27 votes and is now closed as fixed. If you still see something like it, compare the suggestions against the full search results screen before assuming the pages are missing.

Can I make the search box appear in the sidebar? No. The macro lives in page content. The sidebar is built from the space navigation, and macros do not render there.

Does any of this change on Premium or Enterprise? Not for this macro. The search syntax rule about wildcards is the same on every plan, because it comes from the search engine rather than the subscription. What Premium adds is the space content manager, which is an admin screen rather than something you can put on a page.