Animations

SketchyBar includes a powerful animation system that allows you to smoothly transition numerical properties from a starting value to a target value. This can be used to create fluid and visually appealing effects for your bar items.

The --animate Command

Animations are defined using the --animate command, which acts as a prefix to standard --set or --bar commands.

Syntax

sketchybar --animate <easing_function> <duration_in_frames> \
           --set <item_name> <property>=<target_value> ... \
           --bar <property>=<target_value> ...
  • <easing_function>: Determines the rate of change of the animation over time. See the list of available functions below.
  • <duration_in_frames>: The length of the animation. A value of 60 roughly corresponds to 1 second on a 60Hz display. A duration of 0 will cause the property to change instantly.

Example

Let's say you want to animate the background color of an item named my_item from its current color to red (0xffff0000) over the course of 1 second, using a smooth sine easing function.

sketchybar --animate sin 60 --set my_item background.color=0xffff0000

SketchyBar will automatically interpolate the Red, Green, Blue, and Alpha components of the color over 60 frames to create a smooth transition.

Easing Functions

Easing functions control the acceleration and deceleration of the animation. The following functions are available:

  • linear (l): A constant rate of change. No easing.
  • quadratic (q): Starts slow and accelerates. (Ease-in)
  • sin (s): A smooth ease-in and ease-out based on a sine curve.
  • tanh (t): A smooth ease-in and ease-out based on a hyperbolic tangent function.
  • exp (e): An exponential curve.
  • circ (c): A circular easing function.

Animatable Properties

You can animate any property that accepts a numerical value, including:

  • Colors: e.g., background.color, icon.color, shadow.color.
  • Positions and Sizes: e.g., y_offset, padding_left, width, background.height.
  • Numerical Values: e.g., background.corner_radius, icon.font.size, slider.percentage.
  • Floating-Point Values: e.g., background.clip, icon.blur_radius.

Chaining Animations

When you issue a new animation command for a property that is already being animated, the new animation will start from the property's current value in the ongoing animation, not its original starting point. This allows for smooth, interruptible animations.

Practical Use Case: Highlighting a Space

A common use case is to animate the background color of a space item when it becomes active.

# In your space.sh script for a space item

if [ "$SELECTED" = "true" ]; then
  sketchybar --animate sin 10 --set $NAME background.color=0xff9dd274
else
  sketchybar --animate tanh 15 --set $NAME background.color=0x40ffffff
fi

This will cause the active space to smoothly fade to a green color, and inactive spaces to fade back to a semi-transparent white.