hs.chooser

A Spotlight-style chooser for presenting options to the user

hs.chooser lets you show a floating search panel that users can type into to filter and select from a list of items. It's ideal for launchers, emoji pickers, command palettes, and any interface where you want fast, keyboard-driven selection.

Quick Start

const chooser = hs.chooser.create()

chooser.setChoices([
    { text: "Open Safari", subText: "Web browser", action: "safari" },
    { text: "Open Terminal", subText: "Command line", action: "terminal" }
])

chooser.onSelect = (item) => {
    if (item) console.log("Selected: " + item.text + " (" + item.action + ")")
}

chooser.show()

Dynamic Choices

For search-as-you-type filtering powered by your own data:

const allApps = hs.application.runningApplications()

chooser.setChoices((query) => {
    const q = query.toLowerCase()
    return allApps
        .filter(a => a.title.toLowerCase().includes(q))
        .map(a => ({ text: a.title, subText: a.bundleID }))
})

Async Choices (with debounce)

For results fetched from an external source:

let debounceTimer = null
let cachedResults = []

chooser.setChoices(() => cachedResults)

chooser.onQueryChange = (query) => {
    if (debounceTimer) debounceTimer.invalidate()
    debounceTimer = hs.timer.doAfter(0.05, () => {
        fetchFromAPI(query).then(results => {
            cachedResults = results
            chooser.refreshChoices()
        })
    })
}