> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/wezterm/wezterm/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```lua theme={null}
function wezterm.format(items: FormatItem[]) -> string
```

## Parameters

<ParamField path="items" type="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
</ParamField>

## Return Value

<ResponseField name="string" type="string">
  A string with embedded escape sequences for the specified formatting
</ResponseField>

## Format Items

### Text

```lua theme={null}
{Text = "Hello, World!"}
```

The text content can include any string expression, including escape sequences not directly supported by `wezterm.format`.

### Foreground Color

<CodeGroup>
  ```lua ANSI Color theme={null}
  {Foreground = {AnsiColor = "Red"}}
  {Foreground = {AnsiColor = "Blue"}}
  {Foreground = {AnsiColor = "Fuchsia"}}
  ```

  ```lua RGB Color theme={null}
  {Foreground = {Color = "#ff0000"}}
  {Foreground = {Color = "yellow"}}
  {Foreground = {Color = "blue"}}
  ```
</CodeGroup>

**Available ANSI colors:** `Black`, `Maroon`, `Green`, `Olive`, `Navy`, `Purple`, `Teal`, `Silver`, `Grey`, `Red`, `Lime`, `Yellow`, `Blue`, `Fuchsia`, `Aqua`, `White`

### Background Color

<CodeGroup>
  ```lua ANSI Color theme={null}
  {Background = {AnsiColor = "Black"}}
  {Background = {AnsiColor = "Navy"}}
  ```

  ```lua RGB Color theme={null}
  {Background = {Color = "#000080"}}
  {Background = {Color = "blue"}}
  ```
</CodeGroup>

### Text Attributes

#### Underline

```lua theme={null}
{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

```lua theme={null}
{Attribute = {Intensity = "Normal"}}  -- Normal intensity
{Attribute = {Intensity = "Bold"}}    -- Bold text
{Attribute = {Intensity = "Half"}}    -- Half intensity (dim)
```

#### Italic

```lua theme={null}
{Attribute = {Italic = true}}   -- Enable italic
{Attribute = {Italic = false}}  -- Disable italic
```

### Reset Attributes

Reset all attributes to their default values:

```lua theme={null}
"ResetAttributes"
```

## Examples

### Basic Colored Text

```lua theme={null}
local wezterm = require 'wezterm'

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

wezterm.log_info(formatted)
```

### Bold and Colored

```lua theme={null}
local wezterm = require 'wezterm'

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

### Underlined Text with Background

```lua theme={null}
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

```lua theme={null}
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

```lua theme={null}
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:

```lua theme={null}
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

```lua theme={null}
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

```lua theme={null}
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

```lua theme={null}
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

```lua theme={null}
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

<Note>
  The `wezterm.format()` function generates escape sequences at runtime. For frequently called event handlers (like `update-status`), consider caching formatted strings when possible.
</Note>

## 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`