HSChooser
TypeA keyboard-driven floating chooser panel.
Create via hs.chooser.create(). Configure choices, set callbacks, then call .show().
Choice format
Each choice is a plain object with required text and optional subText, image, valid,
and contextMenu fields. All other fields are passed through to the onSelect callback unchanged.
The contextMenu array defines per-row right-click menu entries. Each entry is either
{ title: "...", action: (item) => {} } for a button or { type: "divider" } for a separator:
{
text: "Open Safari", subText: "com.apple.Safari",
image: HSImage.fromAppBundle("com.apple.Safari"), valid: true, myData: 42,
contextMenu: [
{ title: "Open", action: () => hs.urlevent.openURL("https://apple.com") },
{ type: "divider" },
{ title: "Copy bundle ID", action: () => hs.pasteboard.writeString("com.apple.Safari") }
]
}
Keyboard shortcuts
- Return — confirm selection
- Escape — dismiss (calls
onSelectwithnull) - ↑ / ↓ — move through results
Properties
query
string
The current text in the search field. Setting this from JS updates the display but
does not invoke the `onQueryChange` callback.
searchSubText
boolean
Whether searches match against `subText` in addition to `text` (default: `false`).
Only applies when a static choices array is provided.
enableDefaultForQuery
boolean
When `true` and the query is non-empty but there are no matching choices, `onSelect`
is called with `{ text: <query> }` instead of `null` (default: `false`).
onSelect
JSValue
Called when the user confirms a selection.
The argument is the chosen row object (the original dict you passed to `setChoices`,
with `text`, `subText`, `image`, `valid`, and any custom fields intact).
The argument is `null` when dismissed (Escape).
onQueryChange
JSValue
Called on every keystroke with the new query string.
Use this to debounce expensive searches or trigger async data fetching.
onInvalid
JSValue
Called when the user activates a row whose `valid` field is `false`.
The chooser stays open; the argument is the row dict (same shape as `onSelect`).
If unset, activating an invalid row is silently ignored.
Methods
setChoices(choices) -> HSChooser
on show. The function is responsible for filtering; the chooser displays all items it returns.
Declaration
setChoices(choices) -> HSChooserParameters
| Name | Type | Description |
|---|---|---|
| choices | JSValue | An array of choice objects, or a function `(query) => [...]` |
Returns
HSChooser
Self for chaining
Example
// Static
chooser.setChoices([{text: "Foo"}, {text: "Bar"}])
// Dynamic
chooser.setChoices(q => items.filter(i => i.text.toLowerCase().includes(q.toLowerCase())))refreshChoices() -> HSChooser
Re-apply filtering (static choices) or re-invoke the choices function (dynamic).
Call after updating an external data source in an async `onQueryChange` handler.
Declaration
refreshChoices() -> HSChooserReturns
HSChooser
Self for chaining
Example
chooser.refreshChoices()show() -> HSChooser
Show the chooser.
Declaration
show() -> HSChooserReturns
HSChooser
Self for chaining
Example
chooser.show()hide() -> HSChooser
Hide the chooser without making a selection. Restores focus to the previously active window.
Declaration
hide() -> HSChooserReturns
HSChooser
Self for chaining
Example
chooser.hide()select(row) -> HSChooser
Programmatically confirm a selection.
Omit `row` to confirm the currently highlighted row. Fires `onSelect` (or `onInvalid`
for rows with `valid: false`) and hides the chooser.
Declaration
select(row) -> HSChooserParameters
| Name | Type | Description |
|---|---|---|
| row | JSValue | Zero-based row index, or omit to use the current selection. |
Returns
HSChooser
Self for chaining
Example
chooser.select() // confirm highlighted row
chooser.select(2) // confirm row at index 2selectedRowContents(row) -> NSDictionary
Returns the dict for the highlighted row, or for a specific row by index.
Returns `null` if the index is out of range or no choices are set.
Declaration
selectedRowContents(row) -> NSDictionaryParameters
| Name | Type | Description |
|---|---|---|
| row | JSValue | Zero-based row index, or omit to query the highlighted row. |
Returns
NSDictionary
The row dict (`{ text, subText?, image?, valid, ...extras }`) or `null`.
Example
const item = chooser.selectedRowContents()
const item = chooser.selectedRowContents(2)