Watch someone use a search box and you'll notice they rarely type a full query. They type "harry po", glance at the list that appears, and pick "Harry Potter and the Goblet of Fire". The suggestion did half the work, fixed a spelling they weren't sure about, and told them the thing they wanted actually exists in your catalog.
That's autocomplete. It looks like a small feature, but it changes how people search: fewer typos, fewer empty results, and queries that match what you actually have.
This post covers what makes autocomplete good, why it's harder to build than it looks, and how to add it to your app with an API.
What Good Autocomplete Does
A basic version matches the start of a string. A good one does a few more things:
- Completes the word you're on. "wireless hea" becomes "wireless headphones", using the word before it for context so you get headphones and not heaters.
- Suggests the next word. After "harry potter " with a space, it offers "and the" because that's what comes next in your data.
- Forgives typos. "headphnes" still finds "headphones". People type fast on phones and nobody wants to go back and fix one letter.
- Only suggests things that exist. A suggestion that leads to zero results is worse than no suggestion at all.
- Keeps up with typing. If suggestions arrive after the next keystroke, they flicker and feel broken.
That last point is the one people underestimate. Someone typing quickly presses a key every 100 to 200 milliseconds. Your suggestions have to arrive inside that window, every time.
Why It's Hard to Build Yourself
The simplest approach is a LIKE 'harry po%' query on your database. It works on a small table and falls apart fast:
- It's slow at scale. Prefix queries on millions of rows on every keystroke put real load on your primary database.
- It only matches the start of a field. "potter" won't find "Harry Potter" unless you index every word separately.
- It has no idea what's popular. Results come back in whatever order the database likes, so rare junk sits next to the thing everyone wants.
- It has no typo tolerance. One wrong letter and the list is empty.
Fixing those means building a word and phrase index, ranking by frequency, adding fuzzy matching, keeping it in memory so it's fast, and rebuilding it when your data changes. That's a project, not a feature.
Where Suggestions Should Come From
There are two common sources for suggestions:
- Past searches. Suggest what other users typed before. This needs a lot of traffic to work, can surface embarrassing queries, and suggests things that might return nothing.
- Your own content. Build suggestions from the words and phrases in your data. Every suggestion points at something real, and it works from day one with zero traffic.
Vecstore uses the second approach. It builds the index from the documents in your database and ranks suggestions by how often they appear. New stores and apps get useful suggestions immediately, without waiting for search history to pile up.
Adding It With Vecstore
Autocomplete works on any Vecstore text database. If you already insert documents for semantic search, you don't need to insert anything else.
Here's the request:
const BASE_URL = 'https://api.vecstore.app/api';
async function autocomplete(query, signal) {
const res = await fetch(`${BASE_URL}/databases/${DB_ID}/autocomplete`, {
method: 'POST',
headers: {
'X-API-Key': API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({ query, limit: 5 }),
signal,
});
return res.json();
}
And the response:
{
"suggestions": [
{ "text": "Harry Potter" },
{ "text": "harry potter and the" },
{ "text": "Harry Potter and the Chamber of Secrets" }
],
"status": "ready",
"search_time": "2.3ms"
}
It returns suggestion text only. When someone picks one, send it to the search endpoint to get the actual results.
Wiring It to an Input
Two details make the difference between autocomplete that feels instant and autocomplete that flickers:
- Debounce a little. Wait around 100ms after the last keystroke before calling. It cuts requests a lot without anyone noticing the delay.
- Cancel stale requests. If someone types "har" and then "harr", the answer for "har" might arrive second. Abort the old request so it can't overwrite the new one.
const input = document.querySelector('#search');
const list = document.querySelector('#suggestions');
let timer;
let controller;
input.addEventListener('input', () => {
clearTimeout(timer);
timer = setTimeout(async () => {
const query = input.value.trim();
controller?.abort();
if (!query) return (list.innerHTML = '');
controller = new AbortController();
try {
const { suggestions } = await autocomplete(query, controller.signal);
list.replaceChildren(
...suggestions.map((s) => Object.assign(document.createElement('li'), { textContent: s.text })),
);
} catch {}
}, 100);
});
list.addEventListener('click', (e) => {
if (e.target.tagName !== 'LI') return;
input.value = e.target.textContent;
list.innerHTML = '';
runSearch(input.value);
});
A few small touches help too. Show the part someone already typed in a lighter color and the completion in bold, so the eye goes straight to the new part. Support arrow keys and Enter. Close the list on Escape.
Things to Know
The first call builds the index. On a database that has never used autocomplete, the first request returns status: "building" with no suggestions. Retry after a moment and it switches to ready.
New documents aren't instant. The index refreshes on its own as you add and delete documents, but a document added a second ago may not appear in suggestions until the next refresh. For most catalogs that's fine. For a live chat feed, it isn't.
It's built for text databases. Image databases don't have words to suggest, so autocomplete isn't available on them.
It's cheap to call on every keystroke. Requests are billed at 1 credit per 25, because autocomplete is meant to be called a lot.
The Bottom Line
Autocomplete is the first thing people touch when they search, and it shapes everything after. Good suggestions fix typos before they happen, steer people toward what you actually have, and make your search feel fast before a single result loads.
You can try it live on the Autocomplete page, or try Vecstore for free. 100 credits on signup, no credit card. Insert a few documents into a text database and start typing.
