APIs to more conveniently define action buttons (alternative to setting them via regular ^Library/Std/Config).

API

actionButton.define(spec)

Keys to define:

  • icon: a Lucide icon name for your button. The name profile is reserved: it renders the current account's avatar and opens the account menu, and needs neither command nor run.
  • command (optional): command name to invoke when clicked. When set, the command's keyboard shortcut is automatically shown in the tooltip. Replaces run.
  • run (optional): function to invoke once the button is pushed. Use this for custom logic that doesn't map to a single command.
  • description (optional): description of button (appears on hover)
  • priority (optional): determines priority of button (the higher, the earlier in the list)
  • mobile: when set to true this button will only appear on mobile devices
  • standalone: when set to true this button will only appear in standalone/PWA mode; when false, only in browser mode
  • accountManaged (optional): when set to true this button only appears on account-managed (multi-space) servers
  • readOnly (optional): when set to true this button only appears in a read-only space; when false, only in an editable one
  • dropdown (optional): when set to false, the button stays visible outside the dropdown menu on mobile (default: true)

Examples

-- Bind a button to a command (keyboard shortcut shown on hover)
actionButton.define {
  icon = "pen-tool",
  description = "Start journaling",
  command = "Journal: Today",
}

-- Custom button with a run function
actionButton.define {
  icon = "eye",
  run = function()
    editor.setUiOption("forcedROMode", true)
    editor.rebuildEditorState()
  end
}

Implementation

-- priority: 100

actionButton = actionButton or {}

--- Adds a button to the top bar.
--- @param spec table { icon: string, command?: string, run?: function, description?: string, priority?: number, mobile?: boolean, standalone?: boolean, accountManaged?: boolean, readOnly?: boolean, dropdown?: boolean }; set `command` or `run`
function actionButton.define(spec)
  local actionButtonConfig = config.get("actionButtons", {})
  table.insert(actionButtonConfig, spec)
end
Loading SilverBullet…