Themes

One setting, theme, picks the colors: :set theme=nord, the config file’s top-level theme key, or the settings screen (Space ,), where moving over the names previews them (Enter keeps one, Esc goes back).

╭ Explorer ────────────╮ 1 console 1 ×
│ ╭ Settings ────────────────────────────────────────────────────────────────╮─╮
│▾│ Display                                                                  │ │
│ │   Nerd Font icons           ‹ on            ›  Nerd Font icons → on      │e│
│ │   Command line position     ‹ popup         ›  A popup near the top of … │ │
│ │   Theme                     ‹ terminal      ›  Your terminal's own colo… │ │
│ │   Explorer: size colours    ‹ 3             ›  3 levels: amber from 1 M… │ │
│ │   Tips                      ‹ always        ›  Always, in empty places   │ │
│ │   Background                ‹ theme         ›  The theme's               │ │
│ │ Editor                                                                   │ │
│ │   Cursor shape              ‹ on            ›  By mode (block or bar)    │ │
│ │   Yanks to the clipboard    ‹ on            ›  Yes, as Vim with clipboa… │ │
│ │   Formatter: keywords       ‹ preserve      ›  As written                │ │
│ │   Formatter: indent         ‹ 4             ›  4 spaces                  │t│
│ │   Auto-pairs                ‹ off           ›  Off, every key types its… │ │
│ │   Backspace to tab stop     ‹ on            ›  On, spaces back to the t… │ │
│ │   Run hints                 ‹ on            ›  On, the outcome after ea… │ │
│ │   Completion delay (ms)     ‹ 60            ›  Opens once no key came f… │t│
│ │ Results                                                                  │ │
│ │   Cell detail               ‹ panel         ›  A panel on the right of … │ │
│ │   Flash copied cells        ‹ on            ›  On, copied cells flash b… │ │
│ ╰────────────────────────────────────── j/k move · h/l change · Esc close ─╯ │
╰──────────────────────╯╰──────────────────────────────────────────────────────╯
 NORMAL  local-pg │ Connected to local-pg                                    EN

Background detection

The terminal’s background is asked once at startup (OSC 11). A terminal that does not answer counts as dark, and the settings screen says which it found. This only matters for the families that follow the background (catppuccin, tokyo-night, gruvbox).

The terminal’s background

ui.background = "terminal" (:set ui.background=terminal, or the settings screen’s Background row) leaves your terminal’s own background where the theme would paint the panes and the result grid’s alternate rows, so a translucent or image background shows through. Text, selections, the grid’s cursor cell and column header and the marks of edits keep the theme’s colours; the status bar, the grid’s headers, dialogs, menus and popups keep the theme’s surface, and the screen behind a dialog stays see-through (only its text is dimmed). The default, "theme", paints everything.

Wide highlight bands, which would show as opaque blocks, are left out and their cue moves to the gutter:

• In the editor, the statement a run would take is an accent bar ▎ beside its lines, and their line numbers are in the accent; the cursor’s line number is bold. A selection keeps its fill.
• In the result grid, the cursor’s row has no band: the cursor’s cell keeps its fill and its row number is in the accent and bold. A selected range keeps its fill.

Switching to it while the theme has a background of its own (every built-in theme but terminal) says so in one line: the theme’s text colours were made for its background, so on a terminal background far from it some of them may be hard to read.

Terminals of 256 colours

A terminal that draws 256 colours shows each of a theme’s colours as the nearest one of its palette, so a faint tint can come out as the very background it sits on. When COLORTERM is not truecolor or 24bit and TERM names 256 colours (such as xterm-256color), the tints that mark the grid’s cursor row and column header, the cursor’s line, the statement a run would take, the selection, a selected range and the item under the pointer each get a palette colour apart from their background, lighter on a dark theme and darker on a light one. Other colours are left to the terminal. A terminal that draws 24-bit colours but does not say so in COLORTERM can set COLORTERM=truecolor to keep the theme’s own tints.

Your own theme

A theme file sets some tokens and takes the rest from extends (a built-in theme; terminal without it). Colours are #rrggbb, an ANSI name (red, bright-black, …) or default:

# themes/mine.toml next to config.toml, used with theme = "mine"
extends = "dark"

[colors]
accent = "#89b4fa"
warning = "yellow"

[styles]
selection = { bg = "#45475a", modifiers = ["bold"] }

Every token, with what it colours, is listed on the theme file format page. A mistake in the file (an unknown token, a bad colour), an unknown name, or a file named like a built-in theme is reported with the file and line, and the app draws with terminal until it is fixed.

To start a theme file, let datarig write it:

• :theme copy <from> <name> writes themes/<name>.toml with every token of <from> (a built-in theme or a theme file) set to its value, each under a comment saying what it colours.
• :theme new <name> writes one that extends the current theme (when it is built in, else dark) with every token commented out, showing the value it inherits.
• On the settings screen, c on the theme row copies the theme shown there and asks for a name.

None of them replaces a file: a taken name, a built-in theme’s name, a Windows device name (con, nul, com1, …) or a name that is not letters, digits, - and _ is refused. The new theme is then used and saved, and its path is shown.

Tokens added since your file was written

When a version of datarig adds tokens, a theme file written before does not list them: they take their value from the theme it extends (except the grid’s cursor tints, made from the file’s own colours when it sets its own bg or selection, for the header surface or selection, and those are RGB colours). The first time such a file is used, at launch or when you choose it, the status line says how many tokens it does not list. It says so once, and again only when the tokens it does not list change (the note is kept in the state folder; where that cannot be read or written, it is said each time).

:theme update (the current theme) or :theme update <name> adds them to the file, each under its description and commented out with the value it takes now, at the end of its section (the [colors] or the [styles] table, added when the file has none). Nothing the file sets changes: no line of it is touched, and nothing is written unless the file reads exactly as before. A built-in theme, a file with an error, one that cannot be written, or one written with colors.<token> = … keys instead of a [colors] table is refused and left as it is. A file that lists every token already says so. In the command line, :theme update lists your theme files (never a built-in theme), the current theme’s first, and typing narrows them.