README.md

💎 tmux-status.nvim

Keep your setup clean by having only 1 status bar.

tmux-status.nvim_demo.mp4

✨ Features

• 🛠️ Integrate Tmux status directly into your Neovim statusline (i.e: lualine.nvim)
• 👀 Automatically hide/show Tmux status so that there's only ever 1 line
• 📍 Both Neovim and Tmux command line in the same location (tell them apart through color)
• 🌐 Component-based design for flexibility and portability
• 🎨 Customize colors
• 🖼️ Customize Tmux status windows flag with your favorite icons

⚡️ Requirements

• Neovim >= 0.9.5
• Tmux >= 3.2
• (Optional) a Nerd Font for icons in components, such as the Tmux status window flags

📦 Installation

lazy.nvim

  {
    "christopher-francisco/tmux-status.nvim",
    lazy = true,
    opts = {},
  },

🖋️ Usage

Just call the component function: require('tmux-status').tmux_windows()

lualine.nvim

local opts = {
  sections = {
    lualine_c = {
      -- ...other lualine components
      {
        require('tmux-status').tmux_windows,
        cond = require('tmux-status').show,
        padding = { left = 3 },
      },
    },
    lualine_z = {
      -- ...other lualine components
      {
        require('tmux-status').tmux_session,
        cond = require('tmux-status').show,
        padding = { left = 3 },
      },
    }
  }
}

🧩 Components

Component	Description
require('tmux-status').tmux_windows()	Returns Tmux windows with their highlight groups (active, recently inactive, inactive) and the icon corresponding to their window flags
require('tmux-status').tmux_session()	Returns Tmux session name with its highlight group
require('tmux-status').tmux_datetime()	Returns the datetime (see man date) with its highlight group
require('tmux-status').tmux_battery()	Returns the battery (requires pmset, may not be availabe in all OS) with its highlight group
require('tmux-status').tmux_render_format(format)	Advanced component for those who want extra control. Requires familiarity with Tmux configurations. See Advance usage

⚙️ Configuration

Default Options

---@type TmuxStatusOptions
local defaults = {
  window = {
    separator = "  ",
    icon_zoom = "",
    icon_mark = "",
    icon_bell = "",
    icon_mute = "",
    icon_activity = "",
    text = "dir",
  },
  session = {
    icon = ""
  },
  datetime = {
    icon = "󱑍",
    format = "%a %d %b %k:%m",
  },
  battery = {
    icon = "󰂎",
  },
  colors = {
    window_active = "#e69875",
    window_inactive = "#859289",
    window_inactive_recent = "#3f5865",
    session = "#a7c080",
    datetime = "#7a8478",
    battery = "#7a8478",
  },
  force_show = false,        -- Force components to be shown regardless of Tmux status
  manage_tmux_status = true, -- Set to false if you do NOT want the plugin to turn Tmux status on/off
}

Advance usage

Advanced components for those who want extra control. Must be familiar with Tmux config. Renders a format. See FORMATS in tmux manual.

local lualine_x = {
  {
    function ()
      local text = '%#my_custom_highlight_title# Catppuccin: %#my_custom_highlight_description#'
      return text .. require('tmux-status').tmux_render_format('@catppuccin_flavour')
    end,
    cond = require('tmux-status').show,
  },
}