DEV Community 👩‍💻👨‍💻

Cover image for A guide to create tmux like Custom Layouts in Spacemacs
Rajasegar Chandran
Rajasegar Chandran

Posted on

A guide to create tmux like Custom Layouts in Spacemacs

Coming from a vim world with tmux, I had really missed the multiple split window layout in Spacemacs. But after knowing how to define custom layouts this seemed to be an easy exercise for me.

So I thought, I should write a blog post about it to help others setup awesome layouts and workspaces with Spacemacs.

Some Terminology

Here I want to make some clarifications on the terminology surrounding vim, tmux and Emacs on windows, layouts, panes and buffers.

vim tmux emacs Spacemacs
Buffers Panes Buffers Buffers
Windows Windows Frames Frames
Tabs Windows Windows

vim: Buffers

A buffer is the in-memory text of a file which is actually an area of Vim's memory used to hold text read from a file for editing. In addition, an empty buffer with no associated file can be created to allow the entry of text.

vim: Windows

A window is a viewport onto a buffer. You can use multiple windows on one buffer, or several windows on different buffers.

Vim provides multiple ways to organize your work, one of them being the ability to open multiple split windows within the same tab page of a given Vim instance. This allows you to have multiple views on the same buffer or file, or even view multiple buffers side-by-side or in any arrangement you prefer.

vim: Tabs

A tab page is a collection of windows.

Alt Text

Emacs: Frames

A frame is a screen object that contains one or more Emacs windows. It is the kind of object called a “window” in the terminology of graphical environments; but we can't call it a “window” here, because Emacs uses that word in a different way.

A frame initially contains a single main window and/or a minibuffer window; you can subdivide the main window vertically or horizontally into smaller windows.

Emacs: Windows

A window is an area of the screen that is used to display a buffer.

Windows are grouped into frames. Each frame contains at least one window; the user can subdivide it into multiple, non-overlapping windows to view several buffers at once.

Alt Text


Each window displayed by tmux may be split into one or more panes; each pane takes up a certain area of the display and is a separate terminal.

Spacemacs: Layouts

Layouts are window configurations with buffer isolation, each layout can define several workspaces (think of them as sub-layouts) sharing the same list of buffers as their parent layout.

A layout is a window configuration associated with a list of buffers. The list of buffers can be an arbitrarily chosen set of buffers. Spacemacs provides some facilities to create meaningful sets of buffers, for instance the buffers related to a projectile project.

Spacemacs: Workspaces

Workspaces are sub-layouts, they allow to define multiple layouts into a given layout, those layouts share the same buffer as the parent layout.


A number of preset layouts are available in tmux. They are:

  • even-horizontal
  • even-vertical
  • main-horizontal
  • main-vertical
  • tiled

We will see each one in detail and also learn how to create each type of layout in Spacemacs

Custom Layouts

Custom layouts in Spacemacs can be defined using the macro spacemacs|define-custom-layout, they are accessible via SPC l o. You can define these custom layouts inside your*.spacemacs file under dotspacemacs/user-config* section.

Even Horizontal Layout

Panes are spread out evenly from left to right across the window.

Alt Text

;; even-horizontal
(spacemacs|define-custom-layout "@EVEN-HORIZONTAL"
  :binding "1"

Enter fullscreen mode Exit fullscreen mode

Even Vertical Layout

Panes are spread evenly from top to bottom.
Alt Text

;; even-vertical
(spacemacs|define-custom-layout "@EVEN-VERTICAL"
  :binding "2"

Enter fullscreen mode Exit fullscreen mode

Main Horizontal Layout

A large (main) pane is shown at the top of the window and the remaining panes are spread from left to right in the leftover space at the bottom. Use the main-pane-height window option to specify the height of the top pane.

Alt Text

;; main-horizontal
(spacemacs|define-custom-layout "@MAIN-HORIZONTAL"
  :binding "3"

Enter fullscreen mode Exit fullscreen mode

Main Vertical Layout

Similar to main-horizontal but the large pane is placed on the left and the others spread from top to bottom along the right.

Alt Text

;; main-vertical
(spacemacs|define-custom-layout "@MAIN-VERTICAL"
  :binding "4"

Enter fullscreen mode Exit fullscreen mode

Tiled layout

Panes are spread out as evenly as possible over the window in both rows and columns.

Alt Text

;; tiled
(spacemacs|define-custom-layout "@TILED"
  :binding "5"

Enter fullscreen mode Exit fullscreen mode

Example Custom Layout

So far we have seen how we can create custom layouts like tmux standard presets in Spacemacs. But the above examples are only skeletons, we don't load any files in the windows. Now we will see an actual example of how to create accessible custom layouts by loading the desired files, terminals and other programs inside Spacemacs.

Custom Layout in Spacemacs

Previously, in vim, I have been using tmuxinator for managing my tmux sessions and custom layouts for my projects. Since I will be working on multiple projects simultaneously, it was really helpful to define a standard and unique layout for each project.

Layout definition using tmuxinator

tmuxinator is a tool to manage complex tmux sessions easily. It has got some layout settings gets handed down to tmux directly, so you can choose from one of the five standard layouts or specify your own.

  - eslint-plugin-ember:
     layout: main-vertical
     root: ~/Documents/www/emberjs/eslint-plugin-ember
       - vim
       - nvm use 10.15.0

Enter fullscreen mode Exit fullscreen mode

The above same configuration can be easily ported to Spacemacs like below. All you need to do is to get familiar with different macros that are available in Spacemacs like find-fileeshellsplit-window-right, etc., Once you know how these macros work, it will be an easy task to setup custom layouts like this.

(spacemacs|define-custom-layout "@eslint-ember-plugin"
  :binding "p"
  (find-file "~/Documents/www/emberjs/eslint-plugin-ember/")
  (winum-select-window-1) ;; Go to the left window
  (split-window-right) ;; Create the right side but don't move focus
  (winum-select-window-2) ;; Go to the right window

Enter fullscreen mode Exit fullscreen mode

The resultant layout will look something similar to this:

Alt Text


Top comments (0)

👋 Welcome new DEV members in our Welcome Thread

Say hello to the newest members of DEV.