Command palette with Alpine.js and FlexSearch

For the sake of my sanity, and also showcasing a working version, the code being referenced will be the one that's currently being used on this website.

There are 2 components in the search file.

• A nice search input like button that opens up the command palette
• The actual command palette itself

You can see the full version on GitHub. The footer is separated as a partial file but since it's rather irrelevant for this post, we can ignore it.

*Latest version might look different

Since this sample is based on Alpine, make sure to have it installed. I recommend to use the CDN distributed version initially for simplicity.

<script defer src="https://cdn.jsdelivr.net/npm/@alpinejs/[email protected]/dist/cdn.min.js"></script>
<script defer src="https://cdn.jsdelivr.net/npm/[email protected]/dist/cdn.min.js"></script>

This code includes the Focus plugin for Alpine and Alpine itself. I'll explain why we want the plugin later.

The search functionality will be supported via FlexSearch. Similar to Alpine, I recommend to use the CDN distributed version for simplicity.

<script defer src="https://cdn.jsdelivr.net/gh/nextapps-de/[email protected]/dist/flexsearch.bundle.js"></script>

When searching something, you obviously need to provide the content to be searched for. Hugo by default generates HTML, AMP and RSS pages out of the box. However, it also has a way to generate custom data as well via custom outputs.

Since this website is using FlexSearch which is a JavaScript library, providing data as JSON makes it easier to feed it into FlexSearch.

outputFormats:
  SearchIndex:
    mediaType: application/json
    baseName: searchindex
    isPlainText: true
    isHTML: false
    notAlternative: true

outputs:
  home:
    - HTML
    - RSS
    - SearchIndex

This config declares a new output format called SearchIndex, that's data type is JSON and the filename for Hugo to reference is searchindex. Hugo will expect there to be a template file at /layouts/_default/list.searchindex.json which will be used to generate the JSON data content.

In order for Hugo to actually generate the data file, make sure to add SearchIndex to the outputs list. Once generated, the data can be seen at /searchindex.json. Feel free to take a look at the JSON data of this website to get an idea of what I'm talking about.

Here's an example of how the template will look like.

{{- $.Scratch.Add "searchindex" slice -}}

{{- range (where .Site.RegularPages "Type" "in" .Site.Params.mainSections) -}}
  {{- $.Scratch.Add "searchindex" (dict "id" .Params.uuid "type" .Type "title" .Title "href" .RelPermalink "summary" (.Summary | plainify) "content" .Plain) -}}
{{- end -}}

{{- $.Scratch.Get "searchindex" | jsonify -}}

You can see more details regarding Hugo's custom outputs here.

<div
  x-data="{ searchbar: false, searchterm: '', searchresults: [], index: createIndex() }"
>
  ...
</div>

The data being used for searching are initialized at the top DOM object of the file.

• searchbar decides if the palette can be shown or not
• searchterm is the term that's being searched
• searchresults is a list that contains the results that matches searchterm
• index is the Document object initialized from FlexSearch

The index object is a rather unique one compared the other rather self explanatory variables. It basically holds and indexes the list of contents, and will be the one used during searching as well.

  // Initiate and register all contents from "/searchindex.json"
  const createIndex = () => {
    const index = new FlexSearch.Document({
      tokenize: "forward",
      cache: 100,
      document: {
        id: "id",
        store: ["href", "title", "summary", "type"],
        index: ["title", "summary", "content"],
      },
    })

    // built by template /layouts/_default/list.searchindex.json
    fetch("/searchindex.json")
      .then(resp => resp.json())
      .then(contentList => {
        contentList.forEach(content => {
          // console.log(content)
          index.add(content)
        })
        console.log("Indexed contents")
      })
      .catch(err => console.error(err))

    return index
  }

You should see something like the code above at the end of the file. It's basically telling FlexSearch to,

• Which method to use for indexing – e.g. forward, there's a direct memory usage tradeoff here
• The capacity of cached entries
• Document structure – which field to use as ID, which fields to store and which to use as indices

And then retrieve the generated content data from /searchindex.json and insert each of them into the index.

You can see more details of FlexSearch's Document object here – v0.7.31.

There are a 2 ways to show the command palette.

1. Clicking on the search input like button
2. Type Ctrl k or Cmd k if you're on macOS or Windows

The hidden HTML class is used as the way to hide the command palette, and the searchbar variable is the one determining if the hidden class will be assigned or not.

<div
  :class="searchbar ? '' : 'hidden'"
  x-cloak
>
  ...
</div

So when the button is clicked, searchbar is set to true.

<button @click="searchbar = true">
  ...
</button>

The other way using Ctrl k or Cmd k is done like this.

<div
  @keydown.ctrl.k.prevent.document="searchbar = true"
  @keydown.meta.k.prevent.document="searchbar = true"
>
  ...
</div>

Which is basically the same as

document.addEventListener("keydown", (e) => {
  e.preventDefault()

  if ((e.ctrlKey && e.key === "k") || (e.metaKey && e.key === "k"))
    this.searchbar = true;
})

<div x-trap.inert.noscroll.noreturn="searchbar">
  ...
</div>

<ul
  @keydown.tab.document="$focus.wrap().next()"
>
  ...
</ul>

document.addEventListener("keydown", (e) => {
  e.preventDefault()

  if (e.key !== "Tab") return;

  const focusables = document.querySelectorAll("a")
  const currentItemIdx = focusables.indexOf(document.activeElement)
  const nextItemIdx = currentItemIdx + 1 < focusables.length ?
        currentItemIdx + 1 : 0

  focusables[nextItemIdx].focus()
})

If you can open something, you should be able to close it as well. Assuming you have been following, the closing of the command palette should be rather straightforward.

<div
  @keydown.escape.document="searchbar = false"
>
  ...
</div>

Yes, it's just assigning searchbar to false, and the hidden HTML class will be added back to the DOM object, which will result in hiding it completely.

That was a lot of thing to go through but we're finally at the search step. There'll be a couple of things to look into at this step.

1. Executing the search
2. Show the results of the search
3. Show No Results when nothing matches the search term

  const SEARCH_LIMIT = 5

  const searchItems = (term, index) => {
    const results = index.search(term, SEARCH_LIMIT, { enrich: true })

    // De-duplicate the results as search can match multiple fields
    // e.g. title, description
    const dedup = {}
    for (const result of results.flatMap(r => r.result)) {
      if (!dedup[result.id]) dedup[result.id] = result.doc
    }

    return Object.values(dedup) || []
  }

{
  "id": "<UUID>",
  "title": "some title",
  "type": "blog | note | project",
  "href": "link to the content",
  "summary": "short summary of the content",
  "content": "full text of the content"
}

<input
  type="text"
  placeholder="Search..."
  autocomplete="off"
  @keydown.debounce="searchterm = $event.target.value; searchresults = searchItems($event.target.value, index)"
/>

const debounce = (fn, timeout = 2500) => {
  let timer

  return (..args) => {
    clearTimeout(timer)
    timer = setTimeout(() => fn.apply(this, args), timeout)
  }
}

document.addEventListener("keydown", (e) => {
  debounce(() => {
    searchterm = e.target.value  // string input
    searchresults = searchItems(searchterm, index)
  })
})

<ul
  :class="searchresults.length === 0 && searchterm.length > 0 ? 'hidden' : ''"
  @keydown.tab.document="$focus.wrap().next()"
>
  <template x-for="item in searchresults">
    <li :key="item.id">
      <a :href="item.href">
        <icon />
        <div x-text="item.title"></div>
        <div x-text="item.summary"></div>
      </a>
    </li>
  </template>
<ul>

No results available

Similar to determining when the results are shown, there should also be a way to show that there is nothing found for the specified search term.

<div
  :class="searchresults.length === 0 && searchterm.length > 0 ? '' : 'hidden'"
>
  <p>No results found</p>
  <p>We couldn’t find anything with that term. Please try again.</p>
</div>

The logic is mostly similar with a slight twist, searchresults should be an empty list. This will result in the following UI.

This example is based on having a static JSON data that can be read by FlexSearch when the page loads. This might not be the case for you, depending on where your data is coming from.

Obviously if you have some kind of remote data source based on the kind of search infrastructure like Elasticsearch or Typesense, retrieving that data will need to be more involved.

The provided solution in this article will work a lot better for static content than dynamic content. For example, company blogs, or documentation websites where the content is generally static.

However, even with just static contents, it's unclear how performant this solution can be. The cache option for FlexSearch initialization can be pretty influential when it comes to resource consumption of the user's laptop.

Also, since I've not done any real load testing, it's unclear how much resources FlexSearch might require if there's a somewhat large data set.

Having said all that, it's very unlikely that you'll have millions of contents for company blogs or documentation websites so my rough educated guess is that this solution should work mostly fine.