Component: Bracket (Group)

The bracket component (referred to as a group internally) is a special item that acts as a container for other items. Its primary purpose is to draw a single, continuous background or border around a set of related items.

This is useful for visually grouping elements like space indicators or status icons.

Creation

You create a bracket using the --add bracket command, followed by the names of the items you want to include in the group.

# Syntax: sketchybar --add bracket <name> <member_1> <member_2> ...

# Group three status items together
sketchybar --add bracket status wifi battery clock
  • <name>: A unique name for the bracket itself.
  • <member_1> ...: A space-separated list of the names of existing items to include in the group.

Important: The bracket item itself does not have a position. Its position and size are dynamically calculated to encompass all of its visible members.

How it Works

  • The bracket calculates the total width required to hold all of its currently drawn members, including their padding.
  • It then draws its own background behind all member items.
  • Member items are drawn on top of the bracket's background.

This means that the individual backgrounds of member items are usually turned off, and all styling (color, corner radius, borders) is applied to the bracket item instead.

Properties

A bracket is a specialized item, so it supports a limited set of standard item properties, primarily those related to the background and popups.

  • background.color=<HEX_COLOR>
  • background.border_color=<HEX_COLOR>
  • background.border_width=<INT>
  • background.corner_radius=<INT>
  • background.shadow=<on|off>
  • popup.<property>=<value>

Icon and label properties are ignored as brackets do not have their own icons or labels.

Example: Grouping Status Items

Let's create a bordered group for Wi-Fi and Battery indicators.

  1. Add the individual items without backgrounds: 

    sketchybar --add item wifi right \
           --set wifi icon= background.drawing=off \

sketchybar --add item battery right \
           --set battery icon= background.drawing=off

  2. Add the bracket to group them: 

    sketchybar --add bracket status_bracket wifi battery \
           --set status_bracket \
                 background.color=0x4089b4fa \
                 background.corner_radius=8 \
                 background.border_width=2 \
                 background.border_color=0xff89b4fa

This will result in a single, rounded rectangle being drawn behind both the Wi-Fi and battery icons, creating a visually cohesive unit.

Using Regular Expressions

You can also add members to a bracket using a regular expression by wrapping the pattern in slashes (/).

# Create some space items
sketchybar --add space space.1 left ...
sketchybar --add space space.2 left ...

# Add a bracket that groups all items whose names start with "space."
sketchybar --add bracket spaces_bracket /^space\./