Tmux-style: Transform Your Tmux Status Line with Themes & Dynamic Widgets

Tmux-style is the ultimate tmux plugin for deep customization of your status line. With Tmux-style, easily apply beautiful, ready-made themes, or craft your own custom colorschemes for a look that’s all your own. Build powerful widgets that showcase dynamic data at a glance, and experience unparalleled flexibility with configuration options that let you control colors, styles, and layouts. Make your tmux workspace as productive and unique as you are.

Requirements:

To get started with Tmux-style, make sure you have the following:

• POSIX-compatible shell
• tmux
• sed

Installation

Using TPM (Tmux Plugin Manager)

To install Tmux-style using TPM, follow these steps:

# tmux.conf
set -g @plugin 'tmux-plugins/tpm'
set -g @plugin 'Ninzalo/tmux-style'

# Your Tmux-style configuration here...

# Initialize Tmux Plugin Manager (keep this line at the very bottom of tmux.conf)
run '~/.tmux/plugins/tpm/tpm'

Widgets

Built-in Widgets

Tmux-style includes several pre-built widgets that can be used as a part of your status line:

• session
• current-window
• default-window
• gitmux (requires gitmux to be installed)
• directory
• date-time

These widgets bring a visually appealing and highly functional status line to your tmux configuration.

Create Your Own Widget

You can create custom widgets directly in your tmux.conf file.

Use the format #{E:@tmst-[your-widget-name]-[parts-amount]-widget} to define a new widget:

set -ag status-left "#{E:@tmst-[your-widget-name]-[parts-amount]-widget}"

Note

The parts-amount attribute specifies the number of parts, defaulting to 4. You can create up to 20 parts.

Supported tmux variables for widget placement:

• status-left
• status-right
• window-status-format
• window-status-current-format

Each widget part comes with pre-defined parameters that are automatically created in your configuration, allowing for simple yet powerful customization without the need for extensive setup. For each part in a widget, the following parameters are generated:

• Value (@tmst-[your-widget-name]-p[part-number]-value)
• Foreground color (@tmst-[your-widget-name]-p[part-number]-fg)
• Background color (@tmst-[your-widget-name]-p[part-number]-bg)

To check automatically generated parameters, run:

tmux show-options -g

Each of these parameters can be customized directly in your tmux.conf file. To set a unique style for each part, specify the desired value (value), foreground color (fg), and background color (bg), as shown below:

# Customize a part of your widget
set -g @tmst-[your-widget-name]-p[part-number]-value "Your Text or Command Here"
set -g @tmst-[your-widget-name]-p[part-number]-fg "green"
set -g @tmst-[your-widget-name]-p[part-number]-bg "black"

This flexibility allows you to modify colors and text for each widget part, fitting any theme or personal preference effortlessly.

Colorschemes

Using Built-in Colorschemes

Apply a built-in colorscheme by setting the @tmst-colorscheme variable:

# tmux.conf
# ...

# Load built-in 'gruvbox-dark' colorscheme [Default: gruvbox-dark]
set -g @tmst-colorscheme "gruvbox-dark"

# ...

Available colorschemes:

• gruvbox-dark

• gruvbox-material

• gruvbox-light

• catppuccin-mocha

• catppuccin-macchiato

• catppuccin-frappe

• catppuccin-latte

• solarized-dark

• solarized-light

• vscode-dark

• vscode-light

Note

Built-in colorschemes are designed to work exclusively with all built-in widgets and default tmux variables, such as: status-bg, status-fg, message-style and message-command-style. For custom styling beyond these settings, consider using a custom colorscheme.

Adding a Custom Colorscheme

You can specify your own colorscheme file path in the @tmst-custom-colorscheme-path variable in tmux.conf:

# tmux.conf
# ...

# Load 'custom' colorscheme
set -g @tmst-custom-colorscheme-path "/path/to/custom.conf"

# ...

Important

When using a custom colorscheme, you don’t need to set @tmst-colorscheme as it will be overridden.

Example Configurations

Config 1 (used in this tmux.conf)

# tmux.conf
# ...

set -g status-left "" # Clear status-left
set -g status-right "" # Clear status-right

# Use Gruvbox-dark theme
set -g @tmst-colorscheme "gruvbox-dark"

# Set a value in the 3rd part of built-in 'gitmux' widget
set -g @tmst-gitmux-p3-value "#{?#(gitmux #{pane_current_path}), #(gitmux -cfg $HOME/.config/gitmux/.gitmux.conf #{pane_current_path}),}"

# Add built-in 'session' widget to status-left with 3 parts
set -ag status-left "#{E:@tmst-session-3-widget}"

# Add built-in widgets to status-right
set -ag status-right "#{E:@tmst-gitmux-widget}"
set -ag status-right "#{E:@tmst-directory-widget}"
set -ag status-right "#{E:@tmst-date-time-widget}"

# Add built-in window widgets
set -g window-status-current-format "#{E:@tmst-current-window-widget}"
set -g window-status-format "#{E:@tmst-default-window-widget}"

# ...

Config 2

# tmux.conf
# ...

set -g status-left "" # Clear status-left

# Define a 'custom' widget parameters
set -g @tmst-custom-p1-value "▜" # Set "▜" as a value in the 1st part of 'custom' widget
set -g @tmst-custom-p1-fg "#ffffff" # Set white as foreground color in the 1st part of 'custom' widget
set -g @tmst-custom-p1-bg "#{E:@tmst-thm-bg}" # Set @tmst-thm-bg as background color in the 1st part of 'custom' widget
set -g @tmst-custom-p2-value "♦ " # Set "♦ " as a value in the 2nd part of 'custom' widget
set -g @tmst-custom-p2-fg "cyan"
set -g @tmst-custom-p2-bg "#{E:@tmst-custom-p1-fg}"
set -g @tmst-custom-p3-value " my custom widget"
set -g @tmst-custom-p3-fg "#ffffff"
set -g @tmst-custom-p3-bg "cyan"
set -g @tmst-custom-p4-value "█▛"
set -g @tmst-custom-p4-fg "#{E:@tmst-custom-p3-bg}"
set -g @tmst-custom-p4-bg "#{E:@tmst-custom-p1-bg}"

# Add 'custom' widget to status-left
set -ag status-left "#{E:@tmst-custom-widget}" # Create default values for 'custom' widget with default amount of parts (4)
# Or: set -ag status-left "#{E:@tmst-custom-4-widget}" # Gives the same result

# ...

Config 3

# tmux.conf
# ...

set -g status-left "" # Clear status-left

# Define 'custom2' widget parameters
set -g @tmst-custom2-p1-value "▟"
set -g @tmst-custom2-p1-fg "white"
set -g @tmst-custom2-p1-bg "#{E:@tmst-thm-bg}"
set -g @tmst-custom2-p2-value "   my second custom widget"
set -g @tmst-custom2-p2-fg "red"
set -g @tmst-custom2-p2-bg "#{E:@tmst-thm-bg}"

# Add 'custom2' widget to status-left
set -ag status-left "#{E:@tmst-custom2-2-widget}" # Create default values for 'custom2' widget with 2 parts

# ...

Credits

• @morhetz - gruvbox colorscheme
• @sainnhe - gruvbox-material colorscheme
• @catppuccin - catppuccin colorscheme
• @altercation - solarized colorscheme
• @Mofiqul - vscode colorscheme