hammerspoon2-docs
    Preparing search index...

    Class HSChooser

    A keyboard-driven floating chooser panel. Create via hs.chooser.create(). Configure choices, set callbacks, then call .show().

    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

    {
     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") }
     ]
    }
    Index

    Constructors

    constructor

    Properties

    enableDefaultForQuery identifier isVisible onHide onInvalid onQueryChange onSelect onShow placeholder query searchSubText selectedRow typeName visibleRows width

    Methods

    hide refreshChoices select selectedRowContents setChoices show

    Constructors

    Properties

    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).

    identifier: string

    Stable UUID string for this chooser instance.

    isVisible: boolean

    true if the chooser panel is currently on screen.

    onHide: (() => void) | null

    Called after the panel is hidden (for any reason: selection, Escape, or hide()), or null to remove the handler.

    onInvalid: ((item: Record<string, any>) => void) | null

    Called when the user activates a row whose valid field is false, or null to remove the handler. The chooser stays open; the argument is the row dict (same shape as onSelect). If unset, activating an invalid row is silently ignored.

    onQueryChange: ((query: string) => void) | null

    Called on every keystroke with the new query string, or null to remove the handler. Use this to debounce expensive searches or trigger async data fetching.

    onSelect: ((item: Record<string, any> | null) => void) | null

    Called when the user confirms a selection, or null to remove the handler. 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).

    onShow: (() => void) | null

    Called after the panel becomes visible, or null to remove the handler.

    placeholder: string

    Placeholder text shown in the empty search field (default: "Search...").

    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.

    selectedRow: number

    The zero-based index of the currently highlighted row (-1 when empty).

    typeName: string

    Read-only type identifier.

    visibleRows: number

    Maximum number of rows visible at once without scrolling (default: 10).

    width: number

    Width of the chooser as a fraction of the screen width (default: 0.5 = 50 %).

    Methods

    • Hide the chooser without making a selection. Restores focus to the previously active window.

      Returns HSChooser

      Self for chaining

    • Re-apply filtering (static choices) or re-invoke the choices function (dynamic). Call after updating an external data source in an async onQueryChange handler.

      Returns HSChooser

      Self for chaining

    • 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.

      Parameters

      • row: number | null

        Zero-based row index, or omit to use the current selection.

      Returns HSChooser

      Self for chaining

    • 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.

      Parameters

      • row: number | null

        Zero-based row index, or omit to query the highlighted row.

      Returns Record<string, any> | null

      The row dict ({ text, subText?, image?, valid, ...extras }) or null.

    • on show. The function is responsible for filtering; the chooser displays all items it returns.

      Parameters

      • choices: Record<string, any>[] | ((query: string) => Record<string, any>[])

        An array of choice objects, or a function (query) => [...]

      Returns HSChooser

      Self for chaining

    Settings

    Member Visibility

    On This Page

    Choice formatKeyboard shortcuts
    Constructors
    Properties
    Methods