Color scheme reporting
Color Scheme Reporting (Mode 2031) is a DECSET/DECRST mode that enables the terminal to notify applications when the color scheme changes between light and dark modes.
Syntax
CSI ? 2031 h DECSET — Enable color scheme change reporting
CSI ? 2031 l DECRST — Disable color scheme change reporting
DECSET-mode2031 = 0x1b, "[", "?", "2", "0", "3", "1", "h" ; DECRST-mode2031 = 0x1b, "[", "?", "2", "0", "3", "1", "l" ;
Description
Mode 2031 enables applications to receive notifications when the terminal's color scheme changes. This allows applications to dynamically adapt their color palette when the user switches between light and dark modes at the operating system or terminal level.
- Set — The terminal sends a report whenever the color scheme changes.
- Reset — Color scheme changes are not reported. This is the default.
Report format
When the color scheme changes and Mode 2031 is enabled, the terminal sends a DECRPM-style report:
CSI ? 997 n
The application can then query the current color scheme using:
CSI ? 996 n
The terminal responds with:
| Response | Meaning |
|---|---|
CSI ? 997 ; 1 n | Dark mode |
CSI ? 997 ; 2 n | Light mode |
Use cases
Color scheme reporting is valuable for:
- TUI applications that want to automatically switch between light and dark themes when the operating system or terminal theme changes
- Shell prompts that use different color palettes for readability in light vs dark backgrounds
- Terminal-based editors that adapt syntax highlighting colors based on the background
Querying without Mode 2031
Even without enabling Mode 2031, an application can perform a one-time query of the current color scheme using CSI ? 996 n. Mode 2031 adds the ability to receive ongoing notifications as changes occur, rather than needing to poll.
Alternative approaches
Applications can also detect the background color by querying the terminal's background color using OSC 11 (report background color). This returns the actual RGB values, from which the application can infer whether the scheme is light or dark. Mode 2031 provides a more direct and reliable signal.
Mode 2031 is a recent proposal and terminal support varies. Applications should fall back to OSC 11 background color queries or static configuration if Mode 2031 is not available.
Examples
printf '\e[?2031h' # Enable color scheme change reporting
# Query current color scheme:
printf '\e[?996n'
# Response: \e[?997;1n (dark) or \e[?997;2n (light)
# When the user switches themes, the terminal sends:
# \e[?997n
# The application should then re-query with \e[?996n
printf '\e[?2031l' # Disable color scheme change reporting
Specifications
| Specification | Section |
|---|---|
| Contour Color Scheme Reporting | — |
Terminal support
| Terminal | Support | Version | Notes |
|---|---|---|---|
| Terminal Emulators | |||
| Alacritty | ✗ | No | |
| Bobcat | ? | ? | Not explicitly configured in Bobcat. TerminalCtrl may support this, but cannot confirm from Bobcat's code. |
| contour | ✓ | v0.4.0.6245 | Implemented as DECMode::ReportColorPaletteUpdated at primitives.h:733 |
| foot | ✓ | 1.23.0 | |
| Ghostty | ✓ | v1.0.0 | |
| iTerm2 | ✓ | v20260216-nightly | |
| Kitty | ✓ | Yes | |
| Konsole | ✗ | No | |
| mintty | ✗ | No | |
| mlterm | ✗ | No | |
| PuTTY | ✗ | No | |
| Rio | ✗ | No | |
| rxvt-unicode | ✗ | No | |
| st | ✗ | No | |
| terminology | ✗ | No | |
| VT100 | ✗ | No | |
| VTE | ✓ | Yes | |
| WezTerm | ✗ | No | |
| Windows Terminal | ✗ | No | No implementation found in codebase |
| xterm | ✗ | No | |
| xterm.js | ✓ | Yes | Added after 6.0.0, not yet in a release tag |
| Multiplexers | |||
| cy | ✗ | No | |
| GNU Screen | ✗ | No | |
| tmux | ✓ | 3.6 | |
| tuios | ✗ | No | |
| Zellij | ✗ | No | |
See also
- Grapheme Clustering — Mode 2027 — Another modern terminal capability mode
- Synchronized Output — Mode 2026 — Tear-free rendering for theme transitions