Skip to main content


Many of the API classes represent global objects in the script’s context — methods that are marked as static can be accessed through these global objects. All other functions are instance methods. Instance objects can be accessed through the global objects or constructed with the relevant constructors.

For example, to bind a key to a function, you construct a Key object. Notice that you must keep a reference to the handler, otherwise your callback will not get called, because the handler will be released from memory.

const handler = new Key('q', ['control', 'shift'], () => {});

To move the focused window to a new coordinate, you can call the setTopLeft method for a Window instance. To get a Window instance, you can for example get the focused window with the focused method for the global Window object.

Window.focused().setTopLeft({ x: 0, y: 0 });

To combine, bind a key to move the focused window.

const handler = new Key('q', ['control', 'shift'], () => {
Window.focused().setTopLeft({ x: 0, y: 0 });

As an other example, to bind an event to a function, you construct an Event object. Again notice that you must keep a reference to the handler, otherwise your callback will not get called. The callback will get triggered when the event with the specified name occurs.

const handler = new Event('screensDidChange', () => {});
Managed Handlers

You most likely do not want to handle the references manually. Therefore Phoenix supports “Managed Handlers”. This way you can let Phoenix take care of the state management for you.

Key.on('q', ['control', 'shift'], () => {});

Supported APIs

See below for an overview of the supported APIs. To read more, check the respective API documentation pages.

KeysLists all the available keys for binding callbacks to
EventsLists all the available events for binding callbacks to
PreferencesConfigure the behaviour of Phoenix
RequireSeparate your configuration into multiple files
PhoenixAccess global APIs and actions
StorageUse Storage to store values across reloads and reboots as JSON
PointA simple point object for 2D coordinates
SizeA simple 2D size object
RectangleA 2D rectangle representation of a Point and Size
IdentifiableObjects that implement Identifiable can be identified and compared
IterableObjects that implement Iterable can be traversed relatively to the current object
KeyUse Key to construct keys, bind callbacks, access their properties, and enable or disable them
EventUse Event to construct events, bind callbacks, access their properties or disable them
TimerUse Timer to construct and control timers
TaskUse Task to construct external tasks (such as running scripts), access their properties or terminate them
ImageUse Image to load images from the file system
ModalUse Modal to display content as modal windows (in front of all other windows). Modals can be used to display icons and/or text for visual cues.
ScreenUse Screen to access frame sizes and other screens on a multi-screen setup
SpaceUse the Space to control spaces
MouseUse the Mouse to control the cursor
AppUse App to control apps
WindowUse Window to control app windows