Component: Item

The item is the most fundamental component in SketchyBar. It is a general-purpose container for displaying icons, labels, and backgrounds. Most elements in your bar will be of this type.

Creation

You create a standard item using the --add item command.

# Syntax: sketchybar --add item <name> <position>

sketchybar --add item clock right

This adds a new item named clock to the right side of the bar.

General Properties

Standard items can be configured with a wide range of properties. These properties are modified using the --set command.

sketchybar --set clock icon= label="Loading..." script="$PLUGIN_DIR/clock.sh"

Below are some of the most common properties. For a complete list, refer to the CLI Reference.

Content

  • icon=<STRING>: Sets the icon. Often uses symbols from a Nerd Font.
  • label=<STRING>: Sets the text label.
  • icon.drawing=<on|off>: Toggles the visibility of the icon.
  • label.drawing=<on|off>: Toggles the visibility of the label.

Fonts and Colors

  • icon.font="<FAMILY>:<STYLE>:<SIZE>": Sets the font for the icon.
  • label.font="...": Sets the font for the label.
  • icon.color=<HEX_COLOR>: Sets the icon's color.
  • label.color=<HEX_COLOR>: Sets the label's color.
  • highlight=<on|off>: When on, uses the highlight_color instead of the regular color.
  • highlight_color=<HEX_COLOR>: Sets the color to use when highlight=on.

Sizing and Positioning

  • padding_left=<INT>: Sets the padding on the left of the item's content.
  • padding_right=<INT>: Sets the padding on the right of the item's content.
  • y_offset=<INT>: Offsets the item vertically. Can be positive or negative.
  • width=<INT|dynamic>: Sets a fixed width for the item. If set to dynamic, the width will expand and contract to fit its content.

Background

  • background.drawing=<on|off>: Toggles the item's background.
  • background.color=<HEX_COLOR>: Sets the background color.
  • background.corner_radius=<INT>: Sets the corner radius for the background.
  • background.height=<INT>: Sets a specific height for the background.

Scripting

  • script="<PATH_TO_SCRIPT>": Path to the script that updates this item.
  • update_freq=<SECONDS>: How often to run the script.
  • click_script="<PATH_TO_SCRIPT>": Script to run when the item is clicked.

Example: A Complete Clock Item

sketchybar --add item clock right \
           --set clock \
                 icon= \
                 icon.font="Hack Nerd Font:Regular:16.0" \
                 icon.color=0xffa6da95 \
                 label.color=0xffeed49f \
                 background.color=0xff282738 \
                 background.corner_radius=5 \
                 background.padding_right=5 \
                 padding_left=10 \
                 update_freq=10 \
                 script="$PLUGIN_DIR/clock.sh"