wezterm.format()

Format text with terminal graphics attributes including colors, bold, italic, and underlines

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

ANSI 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

ANSI 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.

Related Functions

• 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