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 verticallyGet Tab Group
local windows = group:windows()
for _, w in ipairs(windows) do
print(w.title)
endSplit 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)
endEvent 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 │
└──────────────────┴──────────────┘