Skip to content
Shoji

Alerts

Shoji displays visual feedback when changing layouts. Alerts appear briefly and fade out automatically. This page covers alert behavior and examples. For the complete list of configuration options, see Configuration overview.

Configuration

spoon.Shoji:configure({
  show_layout_alerts = true,  -- Default: true
  show_layout_icon = true,    -- Default: true
  alert_duration = 0.5,       -- Default: 0.5 seconds
})

The alert shows the layout’s displayName (or name if no display name is set) plus context such as window count and ratio. Layouts with icons display their icon in the alert when show_layout_icon is enabled.

Disable alerts

spoon.Shoji:configure({
  show_layout_alerts = false,
})

Disable icons

Show text-only alerts without layout icons:

spoon.Shoji:configure({
  show_layout_icon = false,
})

Longer alert duration

spoon.Shoji:configure({
  alert_duration = 1.0,  -- 1 second
})

Alert behavior

Shoji uses Hammerspoon’s alert system (hs.alert.showWithImage() when an icon exists, otherwise hs.alert.show()):

  • Alerts appear centered on the current screen.
  • Fade in and out automatically.
  • Do not steal focus or interrupt workflow.
  • Stack when multiple appear in quick succession.

Custom styling

Hammerspoon allows global alert customization. Add this to ~/.hammerspoon/init.lua before loading Shoji:

-- Dark translucent background
hs.alert.defaultStyle.strokeColor = { white = 0, alpha = 0 }
hs.alert.defaultStyle.fillColor = { white = 0, alpha = 0.75 }
hs.alert.defaultStyle.textColor = { white = 1, alpha = 1 }


-- Typography
hs.alert.defaultStyle.textFont = ".AppleSystemUIFont"
hs.alert.defaultStyle.textSize = 24


-- Shape and animation
hs.alert.defaultStyle.radius = 10
hs.alert.defaultStyle.fadeInDuration = 0.15
hs.alert.defaultStyle.fadeOutDuration = 0.15


-- Position: 0 = center, 1 = top edge, 2 = bottom edge
hs.alert.defaultStyle.atScreenEdge = 0

These settings affect all Hammerspoon alerts, not just Shoji’s.

Custom alert logic

For full control over layout notifications, disable built-in alerts and use a hook:

spoon.Shoji:configure({
  show_layout_alerts = false,
  hooks = {
    layout_changed = function(spaceID, layout, prevLayout)
      -- Custom notification logic
      hs.alert.show("Layout: " .. layout, 0.3)
    end,
  },
})

The layout_changed hook receives:

  • spaceID: The macOS Space ID where the layout changed
  • layout: The new layout name
  • prevLayout: The previous layout name (or nil on first set)

See Hooks reference for event callbacks.