Quick Start: Understanding the Default Configuration

This guide will walk you through the default sketchybarrc file to help you understand the core concepts of configuring SketchyBar. The default configuration provides a functional and informative bar that serves as an excellent foundation for your own customizations.

After following the Installation guide, your ~/.config/sketchybar/sketchybarrc file should contain the following code.

# This is a demo config to showcase some of the most important commands.
# It is meant to be changed and configured, as it is intentionally kept sparse.
# For a (much) more advanced configuration example see my dotfiles:
# https://github.com/FelixKratz/dotfiles

PLUGIN_DIR="$CONFIG_DIR/plugins"

##### Bar Appearance #####
# Configuring the general appearance of the bar.
# These are only some of the options available. For all options see:
# https://felixkratz.github.io/SketchyBar/config/bar
# If you are looking for other colors, see the color picker:
# https://felixkratz.github.io/SketchyBar/config/tricks#color-picker

sketchybar --bar position=top height=40 blur_radius=30 color=0x40000000

##### Changing Defaults #####
# We now change some default values, which are applied to all further items.
# For a full list of all available item properties see:
# https://felixkratz.github.io/SketchyBar/config/items

default=(
  padding_left=5
  padding_right=5
  icon.font="Hack Nerd Font:Bold:17.0"
  label.font="Hack Nerd Font:Bold:14.0"
  icon.color=0xffffffff
  label.color=0xffffffff
  icon.padding_left=4
  icon.padding_right=4
  label.padding_left=4
  label.padding_right=4
)
sketchybar --default "${default[@]}"

##### Adding Mission Control Space Indicators #####
# Let's add some mission control spaces:
# https://felixkratz.github.io/SketchyBar/config/components#space----associate-mission-control-spaces-with-an-item
# to indicate active and available mission control spaces.

SPACE_ICONS=("1" "2" "3" "4" "5" "6" "7" "8" "9" "10")
for i in "${!SPACE_ICONS[@]}"
do
  sid="$(($i+1))"
  space=(
    space="$sid"
    icon="${SPACE_ICONS[i]}"
    icon.padding_left=7
    icon.padding_right=7
    background.color=0x40ffffff
    background.corner_radius=5
    background.height=25
    label.drawing=off
    script="$PLUGIN_DIR/space.sh"
    click_script="yabai -m space --focus $sid"
  )
  sketchybar --add space space."$sid" left --set space."$sid" "${space[@]}"
done

##### Adding Left Items #####
# We add some regular items to the left side of the bar, where
# only the properties deviating from the current defaults need to be set

sketchybar --add item chevron left \
           --set chevron icon= label.drawing=off \
           --add item front_app left \
           --set front_app icon.drawing=off script="$PLUGIN_DIR/front_app.sh" \
           --subscribe front_app front_app_switched

##### Adding Right Items #####
# In the same way as the left items we can add items to the right side.
# Additional position (e.g. center) are available, see:
# https://felixkratz.github.io/SketchyBar/config/items#adding-items-to-sketchybar

# Some items refresh on a fixed cycle, e.g. the clock runs its script once
# every 10s. Other items respond to events they subscribe to, e.g. the
# volume.sh script is only executed once an actual change in system audio
# volume is registered. More info about the event system can be found here:
# https://felixkratz.github.io/SketchyBar/config/events

sketchybar --add item clock right \
           --set clock update_freq=10 icon=  script="$PLUGIN_DIR/clock.sh" \
           --add item volume right \
           --set volume script="$PLUGIN_DIR/volume.sh" \
           --subscribe volume volume_change \
           --add item battery right \
           --set battery update_freq=120 script="$PLUGIN_DIR/battery.sh" \
           --subscribe battery system_woke power_source_change

##### Force all scripts to run the first time (never do this in a script) #####
sketchybar --update

Breakdown of the sketchybarrc

1. Bar Appearance

sketchybar --bar position=top height=40 blur_radius=30 color=0x40000000
This first command sets the global properties of the bar itself using the --bar command.

  • position=top: Places the bar at the top of the screen.
  • height=40: Sets the bar's height to 40 points.
  • blur_radius=30: Applies a background blur effect (for transparent colors).
  • color=0x40000000: Sets a semi-transparent black background color (0xAA RRGGBB format).

2. Default Item Properties

default=(
  padding_left=5
  # ... other properties
)
sketchybar --default "${default[@]}"
Instead of setting properties for every single item, you can define defaults. The --default command applies these settings to all items added afterward. Here, we're setting default padding, fonts, and colors for icons and labels.

3. Mission Control Spaces

for i in "${!SPACE_ICONS[@]}"
do
  sid="$(($i+1))"
  # ...
  sketchybar --add space space."$sid" left --set space."$sid" "${space[@]}"
done
This loop creates a special space component for each of the first 10 Mission Control spaces.

  • --add space space."$sid" left: Adds a new space item named space.1, space.2, etc., to the left of the bar.
  • space="$sid": Associates this item with the corresponding space ID.
  • script="$PLUGIN_DIR/space.sh": This script is executed whenever the space changes. It receives a $SELECTED variable to determine if it's the active space and changes its appearance accordingly. See the space plugin for details.
  • click_script="yabai -m space --focus $sid": Specifies a command to run when the space item is clicked. This example assumes you are using yabai.

4. Left and Right Items

Items are added to the bar in a similar way.

Example: Clock 

sketchybar --add item clock right \
           --set clock update_freq=10 icon=  script="$PLUGIN_DIR/clock.sh"

  • --add item clock right: Adds a standard item named clock to the right side of the bar.
  • --set clock ...: Sets properties for the clock item.
  • update_freq=10: Tells SketchyBar to run the item's script every 10 seconds.
  • script="$PLUGIN_DIR/clock.sh": The script that fetches the current time and updates the item's label.

Example: Volume 

sketchybar --add item volume right \
           --set volume script="$PLUGIN_DIR/volume.sh" \
           --subscribe volume volume_change
This item is different. It doesn't run on a timer.

  • --subscribe volume volume_change: This subscribes the volume item to the volume_change event. The script will only run when you change the system volume, making it much more efficient.

Next Steps

This default configuration demonstrates the key principles of SketchyBar: adding items, setting their properties, and using scripts that respond to timers or events.

  • Dive into the Usage Guide to understand the core concepts in more detail.
  • Explore the Components section to see all the different types of items you can create.
  • Check out the CLI Reference for a complete list of commands and properties.