Ninzalo/tmux-style
A powerful tmux plugin that enhances your status line with custom themes and dynamic widgets. Easily configure layouts and colors for a fully personalized tmux experience.
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:
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-leftstatus-rightwindow-status-formatwindow-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 | grep ^@tmstEach 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