Skip to content
Tabs & Containers

Tabs & Containers

SamWM supports grouping windows into tabbed containers for better organization.

Tabs

Create Tab Group

-- Tab two windows together
samwm.tabs("create", window1_id, window2_id)

Add Window to Tab Group

-- Add focused window to tab group
samwm.bind("SUPER", "W", "tab", "Add to tab group")

Tab Operations

-- Switch tabs
samwm.bind("SUPER", "1", "tab next", "Next tab")
samwm.bind("SUPER", "2", "tab prev", "Previous tab")

-- Close tab (close window, remove from group)
samwm.bind("SUPER", "Q", "tab close", "Close current tab")

-- Detach tab (remove from group, tile normally)
samwm.bind("SUPER+SHIFT", "W", "tab detach", "Detach from group")

Tab Bar

Tabs render as a bar at the top of the container:

┌─────────────────────────────────────────────┐
│ [Firefox] [Tab 2] [Tab 3]                    │
├─────────────────────────────────────────────┤
│                                             │
│           Window Content                    │
│                                             │
└─────────────────────────────────────────────┘

Tab Configuration

samwm.tabs({
    -- Tab bar position
    position = "top", -- top, bottom

    -- Tab bar height
    height = 30,

    -- Show title or icon
    show = "title", -- title, icon, both

    -- Active tab styling
    active = {
        bg = "#1e1e2e",
        fg = "#cdd6f4",
    },

    -- Inactive tab styling
    inactive = {
        bg = "#313244",
        fg = "#a6adc8",
    },
})

Containers

Containers let you split workspace area into multiple panes.

Split Container

-- Split current container vertically
samwm.bind("SUPER", "V", "split v", "Split vertical")

-- Split current container horizontally
samwm.bind("SUPER", "H", "split h", "Split horizontal")

Container Types

Type Description
split v Vertical split (stack top/bottom)
split h Horizontal split (side by side)
split toggle Toggle split direction

Container Navigation

-- Navigate between containers
samwm.bind("SUPER", "left", "focus left", "Focus left container")
samwm.bind("SUPER", "right", "focus right", "Focus right container")
samwm.bind("SUPER", "up", "focus up", "Focus up container")
samwm.bind("SUPER", "down", "focus down", "Focus down container")

-- Move containers
samwm.bind("SUPER+SHIFT", "left", "move left", "Move to left container")
samwm.bind("SUPER+SHIFT", "right", "move right", "Move to right container")

Resize Containers

-- Resize active container
samwm.bind("SUPER", "R", "resize grow width", "Grow width")
samwm.bind("SUPER+SHIFT", "R", "resize shrink width", "Shrink width")

Stacking Layout

The stacking layout shows one window at a time, with others hidden:

samwm.layout("stack")

-- Stack-specific keybindings
samwm.bind("SUPER", "Tab", "stack next", "Next in stack")
samwm.bind("SUPER+SHIFT", "Tab", "stack prev", "Previous in stack")

Tab/Container Lua API

Create Tab Group

local group = samwm.tab_group.new(window1, window2)
group:add(window3)

Set Tab Group Layout

group:set_layout("tabbed")  -- Tabs at top
group:set_layout("stacked") -- Stacked vertically

Get Tab Group

local windows = group:windows()
for _, w in ipairs(windows) do
    print(w.title)
end

Split Workspace

-- Split current workspace into two containers
local left, right = samwm.split("horizontal")

-- Split with specific ratio
local left, right = samwm.split("horizontal", 0.7) -- 70% / 30%

Container Tree

-- Get container tree structure
local tree = samwm.get_tree()
print(tree.layout)  -- "split"
print(tree.ratio)   -- 0.5

for _, child in ipairs(tree.children) do
    print(child.type) -- "leaf" or "split"
    print(child.window.title)
end

Event Hooks

samwm.on("tab_create", function(group)
    print("New tab group created")
end)

samwm.on("tab_close", function(group, remaining)
    print("Tab closed,", remaining, "tabs remain")
end)

samwm.on("tab_change", function(group, index)
    print("Switched to tab", index)
end)

samwm.on("split_create", function(direction, left, right)
    print("Created split:", direction)
end)

Example Config

-- Tabs and containers
samwm.bind("SUPER", "W", "tab", "Tab container")
samwm.bind("SUPER+SHIFT", "W", "tab detach", "Detach from container")

samwm.bind("SUPER", "V", "split v", "Split vertical")
samwm.bind("SUPER", "H", "split h", "Split horizontal")

samwm.bind("SUPER", "left", "focus left", "Focus left")
samwm.bind("SUPER", "right", "focus right", "Focus right")
samwm.bind("SUPER", "up", "focus up", "Focus up")
samwm.bind("SUPER", "down", "focus down", "Focus down")

samwm.bind("SUPER+SHIFT", "left", "move left", "Move left")
samwm.bind("SUPER+SHIFT", "right", "move right", "Move right")

-- Tab bar styling
samwm.tabs({
    position = "top",
    height = 32,
    show = "title",
    active = { bg = "#1e1e2e", fg = "#cdd6f4" },
    inactive = { bg = "#313244", fg = "#a6adc8" },
})

Preset Layouts

Two-Pane

┌──────────────┬──────────────┐
│              │              │
│   Pane A     │    Pane B    │
│              │              │
│              │              │
└──────────────┴──────────────┘

Three-Column

┌──────────┬──────────┬──────────┐
│          │          │          │
│  Column  │  Column  │  Column  │
│    A     │    B     │    C     │
│          │          │          │
└──────────┴──────────┴──────────┘

Main + Stack

┌──────────────────┬──────────────┐
│                  │   Stack 1    │
│      Main        ├──────────────┤
│                  │   Stack 2    │
│                  ├──────────────┤
│                  │   Stack 3    │
└──────────────────┴──────────────┘