# Format-token fields

Source: https://libtmux.org/en/ts/latest/topics/format-tokens/

> The typed fields every object exposes, mirroring tmux's own format tokens, and why a field is sometimes absent.

Object fields expose values from tmux's
[FORMATS](https://man.openbsd.org/tmux.1#FORMATS), such as [`pane_id`](https://libtmux.org/en/tmux/latest/catalog/formats/pane_id/),
[`window_zoomed_flag`](https://libtmux.org/en/tmux/latest/catalog/formats/window_zoomed_flag/), and [`session_name`](https://libtmux.org/en/tmux/latest/catalog/formats/session_name/). The available fields depend on the
accessor, object scope, tmux version, and data requested by the read.

A token needs the right **scope** and **tmux version**. For example, a pane
token needs a pane context, and a token added after your tmux release may be
absent. Check the accessor's result before using a field that can be missing, as
described below.

<a id="the-absence-idiom-per-port"></a>

## Handling an absent field

An excluded field has the value [`undefined`](<https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/undefined>).

These examples read optional fields, including [`pane_dead_signal`](https://libtmux.org/en/tmux/latest/catalog/formats/pane_dead_signal/) on tmux 3.3 or
newer:

```typescript
pane.deadSignal; // undefined under the same conditions
```

<a id="a-generated-table-under-the-accessor"></a>

## Field availability

Field accessors retain the scope and version requirements of tmux tokens.

[`packages/libtmux/src/_generated/format_fields.ts`](<https://github.com/libtmux/libtmux-ts/blob/f8ca14551254f81800faedc8bee9151565044ef1/packages/libtmux/src/_generated/format_fields.ts>) records each token's
scope and first tmux version. For example, [`pane_zoomed_flag`](https://libtmux.org/en/tmux/latest/catalog/formats/pane_zoomed_flag/) has pane scope
and requires tmux 3.7. [`packages/libtmux/src/_generated/field_aliases.ts`](<https://github.com/libtmux/libtmux-ts/blob/f8ca14551254f81800faedc8bee9151565044ef1/packages/libtmux/src/_generated/field_aliases.ts>)
supplies the camelCase alias `pane.zoomedFlag`.

Version gates describe tmux behavior: [`pane_dead_signal`](https://libtmux.org/en/tmux/latest/catalog/formats/pane_dead_signal/)
and [`pane_dead_time`](https://libtmux.org/en/tmux/latest/catalog/formats/pane_dead_time/) arrived in tmux 3.3, and a cluster of pane-geometry and
floating-pane tokens ([`pane_floating_flag`](https://libtmux.org/en/tmux/latest/catalog/formats/pane_floating_flag/), [`pane_pb_progress`](https://libtmux.org/en/tmux/latest/catalog/formats/pane_pb_progress/), [`pane_x`](https://libtmux.org/en/tmux/latest/catalog/formats/pane_x/),
[`pane_y`](https://libtmux.org/en/tmux/latest/catalog/formats/pane_y/), [`pane_z`](https://libtmux.org/en/tmux/latest/catalog/formats/pane_z/), [`pane_zoomed_flag`](https://libtmux.org/en/tmux/latest/catalog/formats/pane_zoomed_flag/), [`bracket_paste_flag`](https://libtmux.org/en/tmux/latest/catalog/formats/bracket_paste_flag/),
[`synchronized_output_flag`](https://libtmux.org/en/tmux/latest/catalog/formats/synchronized_output_flag/), among others) arrived together in 3.7.

## Fields promoted from the active child

tmux's format engine includes active-child fields when listing a parent. A
[`list-sessions -F`](https://libtmux.org/en/tmux/latest/manual/list-sessions/) row can include [`window_id`](https://libtmux.org/en/tmux/latest/catalog/formats/window_id/) and [`pane_id`](https://libtmux.org/en/tmux/latest/catalog/formats/pane_id/) for the active
window and pane. Check the port reference for typed access to those fields, or
use the explicit relationships described in [Traversal](https://libtmux.org/en/ts/latest/topics/traversal/).

A pane context can include parent window and session fields. A session cannot
identify one attached client when several clients may be attached, so client
tokens such as [`client_name`](https://libtmux.org/en/tmux/latest/catalog/formats/client_name/) require a client context.