plugins.tmux-navigator.settings

The configuration options for tmux-navigator without the tmux_navigator_ prefix.

For example, the following settings are equivialent to these :setglobal commands:

  • foo_bar = 1 -> :setglobal tmux_navigator_foo_bar=1
  • hello = "world" -> :setglobal tmux_navigator_hello="world"
  • some_toggle = true -> :setglobal tmux_navigator_some_toggle
  • other_toggle = false -> :setglobal notmux_navigator_other_toggle

Type: attribute set of anything

Default: { }

Example:

{
  callback = {
    __raw = ''
      function()
        print('nixvim')
      end
    '';
  };
  foo_bar = 42;
  hostname = "localhost:8080";
}

Declared by:

plugins.tmux-navigator.settings.disable_when_zoomed

By default, if you zoom the tmux pane running vim and then attempt to navigate “past” the edge of the vim session, tmux will unzoom the pane. This is the default tmux behavior, but may be confusing if you’ve become accustomed to navigation “wrapping” around the sides due to this plugin.

This option disables the unzooming behavior, keeping all navigation within vim until the tmux pane is explicitly unzoomed.

Plugin default: false

Type: null or boolean or raw lua code

Default: null

Declared by:

plugins.tmux-navigator.settings.no_mappings

By default <C-h>, <C-j>, <C-k>, <C-l>, & <C-\\> are mapped to navigating left, down, up, right, & previous, respectively.

This option disables those default mappings being created.

You can use the plugin’s five commands to define your own custom mappings:

  keymaps = [
    {
      key = "<C-w>h";
      action = "<cmd>TmuxNavigateLeft<cr>";
    }
    {
      key = "<C-w>j";
      action = "<cmd>TmuxNavigateDown<cr>";
    }
    {
      key = "<C-w>k";
      action = "<cmd>TmuxNavigateUp<cr>";
    }
    {
      key = "<C-w>l";
      action = "<cmd>TmuxNavigateRight<cr>";
    }
    {
      key = "<C-w>\\";
      action = "<cmd>TmuxNavigatePrevious<cr>";
    }
  ];

You will also need to update your tmux bindings to match.

Plugin default: false

Type: null or boolean or raw lua code

Default: null

Declared by:

plugins.tmux-navigator.settings.no_wrap

By default, if you try to move past the edge of the screen, tmux/vim will “wrap” around to the opposite side.

This option disables “wrapping” in vim, but tmux will need to be configured separately.

Tmux doesn’t have a “no_wrap” option, so whatever key bindings you have need to conditionally wrap based on position on screen:

  is_vim="ps -o state= -o comm= -t '#{pane_tty}' \
    | grep -iqE '^[^TXZ ]+ +(\\S+\\/)?g?(view|l?n?vim?x?|fzf)(diff)?$'"

  bind-key -n 'C-h' if-shell "$is_vim" { send-keys C-h } { if-shell -F '#{pane_at_left}'   {} { select-pane -L } }
  bind-key -n 'C-j' if-shell "$is_vim" { send-keys C-j } { if-shell -F '#{pane_at_bottom}' {} { select-pane -D } }
  bind-key -n 'C-k' if-shell "$is_vim" { send-keys C-k } { if-shell -F '#{pane_at_top}'    {} { select-pane -U } }
  bind-key -n 'C-l' if-shell "$is_vim" { send-keys C-l } { if-shell -F '#{pane_at_right}'  {} { select-pane -R } }

  bind-key -T copy-mode-vi 'C-h' if-shell -F '#{pane_at_left}'   {} { select-pane -L }
  bind-key -T copy-mode-vi 'C-j' if-shell -F '#{pane_at_bottom}' {} { select-pane -D }
  bind-key -T copy-mode-vi 'C-k' if-shell -F '#{pane_at_top}'    {} { select-pane -U }
  bind-key -T copy-mode-vi 'C-l' if-shell -F '#{pane_at_right}'  {} { select-pane -R }

Plugin default: false

Type: null or boolean or raw lua code

Default: null

Declared by:

plugins.tmux-navigator.settings.preserve_zoom

As noted in disable_when_zoomed, navigating from a vim pane to another tmux pane normally causes the window to be unzoomed. Some users may prefer the behavior of tmux’s -Z option to select-pane, which keeps the window zoomed if it was zoomed.

This option enables that behavior.

Naturally, if disable_when_zoomed is enabled, this option will have no effect.

Plugin default: false

Type: null or boolean or raw lua code

Default: null

Declared by:

plugins.tmux-navigator.settings.save_on_switch

You can configure the plugin to write the current buffer, or all buffers, when navigating from vim to tmux.

null: don’t save on switch (default value) 1: :update (write the current buffer, but only if changed) 2: :wall (write all buffers)

Type: null or one of 1, 2

Default: null

Declared by: