button Component

Use the button component to create a standard control for initiating actions within your UI.

{
  "type": "button",
  "text": "Click Me!"
}

When clicking a button, an "actioned" event trigger is dispatched.

Tip

Use the shortcut shared property to assign relevant key combos to buttons.

For example ⌘S to a "Save" button.

Properties

image
IMAGE | null [getter]
null removes the image

The IMAGE displayed on this button.

text
STRING [getter]
Default: "Button"

The text displayed on the button.

font
FONT | null
null sets the default font

The FONT for this button's text.

bordered
BOOL
Default: true

Set if this button has a border or not.

bordershape
ENUM
Default: "auto", macOS 26+

When bordered is set to true, set the shape of the border.

Value Description
"auto" The shape will be determined automatically.
"capsule" A capsule type border shape.
"roundedrectangle" A rounded rect border shape.
"circle" A circular border shape.
effect
ENUM
Default: "default", macOS 26+

Change the effect of the button. Use sparingly as per Apple's HIG.

Value Description
"default" The default style for macOS.
"glass" A glass style button.
contenttintcolour
COLOUR | null
null sets the default tint colour

An optional tint COLOUR for the button content when bordered is set to false.

Also see Shared Properties.

Event Triggers

This component dispatches the following event triggers:

Trigger Description
"actioned" The default and native action for a button.
"mousedown" Trigger as soon as mouse is down, overriding the native actioned event. This will disable button highlighting and the ability to drag out to cancel triggering, so use sparingly.

Examples

Play a sound when clicked

{
  "type" : "button",
  "text" : "Play Sound",
  "events": [
    {
      "triggers": "actioned",
      "action": {
        "type": "json",
        "src": {
          "sound": {
            "src": "Funk"
          }
        }
      }
    }
  ]
}