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

    backgroundColor borderColor borderWidth cornerRadius enableDefaultForQuery identifier isVisible onHide onInvalid onQueryChange onSelect onShow placeholder placeholderColor query queryColor querySize searchSubText selectedRow selectionColor subTextColor subTextSize textColor textSize typeName visibleRows width

    Methods

    hide refreshChoices select selectedRowContents setChoices show

    Constructors

    Properties

    backgroundColor: HSColor | null

    Background color of the chooser panel. When nil (the default), the panel uses the system's translucent glass/material effect. If you set this to a solid or near-opaque color, also set textColor, subTextColor, and placeholderColor to ensure readable contrast — they are not adjusted automatically.

    borderColor: HSColor | null

    Border color drawn around the chooser panel. When nil (the default), no border is drawn.

    borderWidth: number

    Width of the border drawn around the chooser panel, in points (default: 1). Has no effect unless borderColor is also set.

    cornerRadius: number

    Corner radius of the chooser panel, in points (default: 14).

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

    placeholderColor: HSColor | null

    Color of the placeholder text (and search icon) shown in an empty search field. When nil (the default), the system's secondary label color is used.

    query: string

    The current text in the search field. Setting this from JS updates the display but does not invoke the onQueryChange callback.

    queryColor: HSColor | null

    Color of the text the user types into the search field. When nil (the default), the system's primary label color is used.

    querySize: number

    Font size of the search field's typed text and placeholder, in points (default: 20). Changing this also rescales the search icon, and changes the search bar height (and therefore the panel height) to fit. Must be a positive, finite number; invalid values are ignored (with a warning logged).

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

    selectionColor: HSColor | null

    Background tint of the highlighted row. When nil (the default), a translucent tint of the system accent color is used.

    subTextColor: HSColor | null

    Color of each result row's subtext. When nil (the default), the system's secondary label color is used.

    subTextSize: number

    Font size of each result row's subtext, in points (default: 12). Changing this also changes the row height (and therefore the panel height) to fit. Must be a positive, finite number; invalid values are ignored (with a warning logged).

    textColor: HSColor | null

    Color of each result row's main text. When nil (the default), the system's primary label color is used.

    textSize: number

    Font size of each result row's main text, in points (default: 14). Changing this also rescales the ⌘-digit shortcut hint shown on the first ten rows, and changes the row height (and therefore the panel height) to fit. Must be a positive, finite number; invalid values are ignored (with a warning logged).

    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