Component: Graph

The graph component allows you to display a time-series of data points as a simple line graph. This is ideal for visualizing metrics like CPU usage, network traffic, or memory consumption over a short period.

Creation

You create a graph using the --add graph command.

# Syntax: sketchybar --add graph <name> <position> <width>

sketchybar --add graph cpu.graph right 100
  • <name>: A unique name for the graph item.
  • <position>: left, center, or right.
  • <width>: The width of the graph in points. This also determines the number of data points the graph can hold.

Pushing Data to the Graph

Unlike other items, you don't set a label or icon for a graph. Instead, you push data points to it using the --push command.

# Syntax: sketchybar --push <name> <value>

sketchybar --push cpu.graph 0.75
  • <value>: A floating-point number between 0.0 (bottom of the graph) and 1.0 (top of the graph).

The graph operates like a circular buffer (or a queue). When you push a new value, the oldest value is discarded. This creates a moving window of your data.

Example: CPU Usage Graph

You would typically have a script that runs on a timer (update_freq) to fetch the latest data and push it to the graph.

  1. Create the graph item: 

    sketchybar --add graph cpu.graph right 100 \
           --set cpu.graph \
                 update_freq=2 \
                 color=0xff9dd274 \
                 script="$PLUGIN_DIR/cpu_usage.sh"

  2. Create the update script (cpu_usage.sh): 

    #!/bin/sh

# Get CPU usage as a percentage (e.g., 75.0)
CPU_PERCENTAGE=$(ps -A -o %cpu | awk '{s+=$1} END {print s}')

# Convert to a value between 0.0 and 1.0
CPU_VALUE=$(echo "scale=2; $CPU_PERCENTAGE / 100" | bc)

# Push the new value to the graph
sketchybar --push cpu.graph $CPU_VALUE

Graph-Specific Properties

Graphs have several unique properties to control their appearance.

  • graph.color=<HEX_COLOR>: Sets the color of the line. This also sets the default fill color with a low alpha.
  • graph.fill_color=<HEX_COLOR>: Sets a custom color for the area beneath the line.
  • graph.line_width=<FLOAT>: Sets the thickness of the line.
  • graph.rtl=<on|off>: Sets the drawing direction. off (default) draws left-to-right. on draws right-to-left.

Example Configuration

sketchybar --set cpu.graph \
           graph.color=0xfffab387 \
           graph.fill_color=0x40fab387 \
           graph.line_width=1.5