Overview

You will learn

• How to build layouts from scratch
• How to add configurable features to layouts
• How to use modifiers and combinators for composition

This section teaches you to build custom layouts for Shoji. By the end, you’ll understand how layouts work and have the skills to create your own.

Prerequisites

Before starting:

1. Shoji installed and running (Installation)
2. Basic Lua knowledge (variables, functions, tables)
3. A text editor for writing Lua files

The tutorials

Part 1: Your first layout

Build a simple column layout from scratch. You’ll learn the layout protocol and how Shoji uses layouts to position windows.

What you’ll build: A layout that arranges windows in equal vertical columns.

Time: Follow along at your own pace.

Start Part 1 →

Part 2: Making it configurable

Extend your layout to respond to user actions. Add capabilities that let users adjust the main ratio and number of master windows.

What you’ll build: A master-stack layout with adjustable regions.

Prerequisites: Complete Part 1.

Start Part 2 →

Part 3: Modifiers and composition

Transform existing layouts without rewriting them. Use modifiers and combinators to create layout variations.

What you’ll build: Custom modifiers and composed layouts.

Prerequisites: Complete Part 2.

Start Part 3 →

Reference material

After completing the tutorials, use these references (also in this section):

• Layout protocol — Full protocol specification
• Modifiers — Built-in modifiers documentation
• Chaining modifiers — Combining multiple modifiers

Testing your work

Throughout these tutorials, you’ll test layouts in Hammerspoon:

1. Save your layout file
2. Reload Hammerspoon from the menu bar (Reload config) or run hs.reload() in the Hammerspoon console
3. Cycle to your layout (Ctrl+Alt+Space)
4. Check the console for errors (menu bar > Console)

Keep the console open while developing to catch errors early.

Optional: Type annotations

If your editor supports EmmyLua annotations (VS Code with Lua extension, IntelliJ with EmmyLua plugin, or Neovim with lua-language-server), you can add type annotations to your layouts for autocomplete and error checking:

---@param params LayoutParams
---@return table<WindowID, Frame>
function MyLayout.arrange(params)

This is entirely optional. The tutorials work without annotations.