Skip to main content
The wezterm.format() function produces formatted strings with terminal graphic attributes such as bold, italic, colors, and underlines. The resulting string contains WezTerm-compatible escape sequences.

​
Signature

function wezterm.format(items: FormatItem[]) -> string

​
Parameters

​
items
FormatItem[]
required
An array of format items that define the text and its styling. Each item can be:
  • {Text="string"} - Text content to render
  • {Foreground=color} - Set foreground color
  • {Background=color} - Set background color
  • {Attribute=attribute} - Set text attribute (bold, italic, underline)
  • "ResetAttributes" - Reset all attributes to default

​
Return Value

​
string
string
A string with embedded escape sequences for the specified formatting

​
Format Items

​
Text

{Text = "Hello, World!"}
The text content can include any string expression, including escape sequences not directly supported by wezterm.format.

​
Foreground Color

{Foreground = {AnsiColor = "Red"}}
{Foreground = {AnsiColor = "Blue"}}
{Foreground = {AnsiColor = "Fuchsia"}}
Available ANSI colors: Black, Maroon, Green, Olive, Navy, Purple, Teal, Silver, Grey, Red, Lime, Yellow, Blue, Fuchsia, Aqua, White

​
Background Color

{Background = {AnsiColor = "Black"}}
{Background = {AnsiColor = "Navy"}}

​
Text Attributes

​
Underline

{Attribute = {Underline = "None"}}    -- Disable underline
{Attribute = {Underline = "Single"}}  -- Single underline
{Attribute = {Underline = "Double"}}  -- Double underline
{Attribute = {Underline = "Curly"}}   -- Curly underline
{Attribute = {Underline = "Dotted"}}  -- Dotted underline
{Attribute = {Underline = "Dashed"}}  -- Dashed underline

​
Intensity

{Attribute = {Intensity = "Normal"}}  -- Normal intensity
{Attribute = {Intensity = "Bold"}}    -- Bold text
{Attribute = {Intensity = "Half"}}    -- Half intensity (dim)

​
Italic

{Attribute = {Italic = true}}   -- Enable italic
{Attribute = {Italic = false}}  -- Disable italic

​
Reset Attributes

Reset all attributes to their default values: 
"ResetAttributes"

​
Examples

​
Basic Colored Text

local wezterm = require 'wezterm'

local formatted = wezterm.format {
  { Foreground = { AnsiColor = 'Red' } },
  { Text = 'This text is red' },
}

wezterm.log_info(formatted)

​
Bold and Colored

local wezterm = require 'wezterm'

local formatted = wezterm.format {
  { Attribute = { Intensity = 'Bold' } },
  { Foreground = { Color = '#00ff00' } },
  { Text = 'Bold green text' },
}

​
Underlined Text with Background

local wezterm = require 'wezterm'

local formatted = wezterm.format {
  { Attribute = { Underline = 'Single' } },
  { Foreground = { AnsiColor = 'Fuchsia' } },
  { Background = { Color = 'blue' } },
  { Text = 'Underlined purple on blue' },
  'ResetAttributes',
  { Text = ' - back to normal' },
}

​
Status Bar with Date/Time

local wezterm = require 'wezterm'

local success, date, stderr = wezterm.run_child_process { 'date' }

local status = wezterm.format {
  { Attribute = { Underline = 'Single' } },
  { Foreground = { AnsiColor = 'Fuchsia' } },
  { Background = { Color = 'blue' } },
  { Text = 'Hello ' .. date .. ' ' },
  'ResetAttributes',
  { Text = 'this text has default attributes' },
}

wezterm.log_info(status)

​
Multiple Styles

local wezterm = require 'wezterm'

local output = wezterm.format {
  -- Red and bold
  { Attribute = { Intensity = 'Bold' } },
  { Foreground = { AnsiColor = 'Red' } },
  { Text = 'ERROR: ' },
  
  -- Reset and normal text
  'ResetAttributes',
  { Text = 'Something went wrong ' },
  
  -- Italic detail
  { Attribute = { Italic = true } },
  { Foreground = { AnsiColor = 'Grey' } },
  { Text = '(see logs for details)' },
}

​
Custom Underline Color

You can use arbitrary escape sequences for advanced features like underline colors: 
local wezterm = require 'wezterm'

local formatted = wezterm.format {
  -- Turn on underlines
  { Attribute = { Underline = 'Single' } },
  -- Make the underline red using escape sequence
  { Text = '\x1b[58:2::255:0:0m' },
  -- The underlined text
  { Text = 'hello' },
}

wezterm.log_info(formatted)

​
Common Use Cases

​
Tab Title Formatting

local wezterm = require 'wezterm'

wezterm.on('format-tab-title', function(tab, tabs, panes, config, hover, max_width)
  local title = tab.active_pane.title
  
  if tab.is_active then
    return wezterm.format {
      { Attribute = { Intensity = 'Bold' } },
      { Foreground = { AnsiColor = 'Blue' } },
      { Text = ' ' .. title .. ' ' },
    }
  end
  
  return wezterm.format {
    { Foreground = { AnsiColor = 'Grey' } },
    { Text = ' ' .. title .. ' ' },
  }
end)

​
Status Bar

local wezterm = require 'wezterm'

wezterm.on('update-status', function(window, pane)
  local date = wezterm.strftime('%Y-%m-%d %H:%M:%S')
  
  window:set_right_status(wezterm.format {
    { Attribute = { Intensity = 'Bold' } },
    { Foreground = { AnsiColor = 'Green' } },
    { Text = '🕐 ' },
    { Foreground = { AnsiColor = 'White' } },
    { Text = date .. ' ' },
  })
end)

​
Workspace Indicator

local wezterm = require 'wezterm'

wezterm.on('update-status', function(window, pane)
  local workspace = window:active_workspace()
  
  window:set_left_status(wezterm.format {
    { Background = { Color = '#2e3440' } },
    { Foreground = { Color = '#88c0d0' } },
    { Text = ' ' .. workspace .. ' ' },
  })
end)

​
Log Messages

local wezterm = require 'wezterm'

local function log_error(msg)
  wezterm.log_error(wezterm.format {
    { Attribute = { Intensity = 'Bold' } },
    { Foreground = { AnsiColor = 'Red' } },
    { Text = '[ERROR] ' },
    'ResetAttributes',
    { Text = msg },
  })
end

local function log_info(msg)
  wezterm.log_info(wezterm.format {
    { Foreground = { AnsiColor = 'Blue' } },
    { Text = '[INFO] ' },
    'ResetAttributes',
    { Text = msg },
  })
end

​
Color Specifications

​
Named Colors

You can use CSS color names:
  • "red", "blue", "green", "yellow", etc.

​
Hex Colors

Use standard hex format:
  • "#ff0000" (red)
  • "#00ff00" (green)
  • "#0000ff" (blue)

​
ANSI Colors

Use the 16 standard ANSI colors (indices 0-15):
  • Black (0), Maroon (1), Green (2), Olive (3)
  • Navy (4), Purple (5), Teal (6), Silver (7)
  • Grey (8), Red (9), Lime (10), Yellow (11)
  • Blue (12), Fuchsia (13), Aqua (14), White (15)

​
Performance Considerations

The wezterm.format() function generates escape sequences at runtime. For frequently called event handlers (like update-status), consider caching formatted strings when possible.
  • wezterm.log_info() - Log info messages (supports formatted strings)
  • wezterm.log_warn() - Log warning messages
  • wezterm.log_error() - Log error messages
  • window:set_left_status() - Set left status bar content
  • window:set_right_status() - Set right status bar content

​
Source Reference

Implementation: lua-api-crates/termwiz-funcs/src/lib.rs:17,146-148