Component: Space

The space component provides native integration with macOS Mission Control spaces. It allows you to create items that visually represent each space, show which space is active, and switch between them.

Creation

You create a space item using the --add space command. It is typically done in a loop to create an item for each space you want to display.

# Syntax: sketchybar --add space <name_prefix>.<space_id> <position>

sketchybar --add space space.1 left
sketchybar --add space space.2 left
# ... and so on

Space-Specific Properties

In addition to all the standard item properties, the space component has one unique required property.

• space=<SPACE_ID>: This property associates the SketchyBar item with a specific Mission Control space. <SPACE_ID> is an integer (1, 2, 3, etc.).

Example

SPACE_ICONS=("1" "2" "3") # Icons for the first three spaces

for i in "${!SPACE_ICONS[@]}"
do
  sid="$(($i+1))" # Space IDs are 1-indexed

  sketchybar --add space space.$sid left \
             --set space.$sid \
                   space=$sid \
                   icon=${SPACE_ICONS[i]} \
                   label.drawing=off \
                   script="$PLUGIN_DIR/space.sh" \
                   click_script="yabai -m space --focus $sid"
done

Scripting with Spaces

When you assign a script to a space item, SketchyBar automatically triggers that script whenever the active space changes. It also provides a special environment variable to the script:

• $SELECTED: This variable will be set to true if the space associated with the item is currently the active space on its display, and false otherwise.

This allows you to dynamically change the appearance of a space item to highlight it when it's active.

Example space.sh Script

The default plugins/space.sh script demonstrates this concept perfectly:

#!/bin/sh

# The $SELECTED variable is available for space components and indicates if
# the space invoking this script (with name: $NAME) is currently selected.

sketchybar --set "$NAME" background.drawing="$SELECTED"

This simple script toggles the background.drawing property based on whether the space is selected. When combined with the configuration from the Quick Start guide, this makes the active space appear with a highlighted background.

You can extend this to animate properties for a smoother effect:

#!/bin/sh

if [ "$SELECTED" = "true" ]; then
  sketchybar --animate sin 10 --set $NAME icon.color=0xff1e1e2e background.color=0xffcba6f7
else
  sketchybar --animate tanh 15 --set $NAME icon.color=0xffcdd6f4 background.color=0x40cdd6f4
fi