Components -- Special Items with special properties
Components are essentially items, but with special properties. Currently there are the components (more details in the corresponding sections below):
- graph: showing a graph,
- space: representing a mission control space
- bracket: brackets together other items
- alias: an alias of a menu bar item from the macOS bar
- slider: a slider that shows a progression and can be clicked/dragged to set a new value
Data Graph -- Draws an arbitrary graph into the bar
sketchybar --add graph <name> <position> <width in points>
Additional graph properties:
|Color of the graph line|
|Fill color of the graph|
|Width of the line in points|
Push data points into the graph via:
sketchybar --push <name> <data point> ... <data point>
<data point> is a floating point number between 0 and 1.
Graphs usually take the entire height of the bar as a drawing canvas, however,
if you set a background for the graph item and set a height for it, the graph
will draw inside of the background. With a background enabled, the graph can
also be moved via a
sketchybar --set <graph name> background.color=0xff00ff00 background.height=20 y_offset=2
Space -- Associate mission control spaces with an item
sketchybar --add space <name> <position>
The space component overrides the definition of the following properties:
- space: Which space this item represents
- (optional) display: On which display the space is shown.
spaceproperty must be set to properly associate this item with the corresponding mission control space. Optionally, you can provide an
displayto force a space item to stay on a specific display, otherwise the item will draw on the screen on which the space is currently located.
The space component has additional variables available in scripts:
$SELECTED has the value
true if the associated space is selected and
false if the associated space is not selected, while
$SID holds the space id and
$DID the display id.
By default the space component invokes the following script:
sketchybar --set $NAME icon.highlight=$SELECTED
which you can freely configure to your liking by supplying a different script to the space component:
sketchybar --set <name> script=<script/path>
For performance reasons the space script is only run on a change in the
$SELECTED variable, i.e. if the associated space has become active
or has resigned being active.
Item Bracket -- Group Items in e.g. colored sections
It is possible to create a common background for any number of items, i.e. to bracket together items, via the command:
sketchybar --add bracket <name> <member name> ... <member name>
<member name> is a name of any item in the bar that should be added to the bracket.
<member name> can also be a
It is now possible to set properties for the bracket, just as for any item or component. Brackets currently only support all background features.
E.g., if I wanted a colored background around my space components (which are named space.1, space.2, space.3) I would set it up like this:
sketchybar --add bracket spaces space.1 space.2 space.3 \
--set spaces background.color=0xffffffff \
Alternatively, if I had a number of spaces, called space.1, space.2, etc. the regex syntax comes in handy:
sketchybar --add bracket spaces '/space\..*/' \
--set spaces background.color=0xffffffff \
this draws a white background below all my space components.
Brackets are very flexible with their members, i.e. it is no problem to bracket together a
left and a
the background will span all the way between those items.
Item Alias -- Mirror items of the original macOS status bar into sketchybar
It is possible to create an alias for default menu bar items (such as MeetingBar, etc.) in sketchybar. The default menu bar can be set to autohide and this should still work.
To create an alias of a default menu bar item use the following syntax:
sketchybar --add alias <application_name> <position>
this operation requires screen capture permissions, which should be granted in the system preferences.
This will put the default macOS menu bar item into sketchybar. If an application has multiple menu bar widgets the command can be overloaded by providing a window_owner and a window_name
sketchybar --add alias "<window_owner>,<window_name>" <position>
this way the default system items can also be aliased in sketchybar as well, e.g.:
- "Control Center,Bluetooth"
- "Control Center,WiFi"
Or the individual widgets of Stats:
All further macOS menu bar items currently available on your system can be found via the command
sketchybar --query default_menu_items
where all items with their respective owner and name are listed.
You can override the color of an alias via the property:
sketchybar --set <name> alias.color=<argb_hex>
and change its scale via:
sketchybar --set <name> alias.scale=<float>
By default, an alias will update once a second, the update interval can be adapted via:
sketchybar --set <name> alias.update_freq=<positive_integer>
Slider -- A draggable progression indicator
A slider can be added to the bar via the command:
sketchybar --add slider <name> <position> <width>
Like all components, the slider only adds some additional properties and functionality to a regular item. Thus all properties of regular items are available for the slider. Additionally the slider exposes the additional properties:
|Total width of the slider in points|
|Progression of the slider in percent (0-100)|
|Color that highlights the progression of the slider|
|Knob of the slider|
|The slider knob supports all |
|The slider supports all |
The slider can be enabled to receive
mouse.clicked events by subscribing to this event.
A slider will receive the additional environment variable
$PERCENTAGE on a click in its
script, which represents the percentage corresponding to the click location.
If a slider is dragged by the mouse it will only send a single event on drag release and
track the mouse during the drag.