Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Themes

uji starts out in default, or in the theme you saved, and uji.ui.configure switches to another one by name.

uji.ui.configure({ theme = "harbor" })

A name loads lua/uji/themes/<name>.lua from your config directory or from a pack, and that file returns the theme. You can also pass the theme itself.

Choosing and keeping a theme

uji.modules("uji.themes") lists every theme uji can load, from uji, your config directory and your packs. uji.ui.save_theme keeps one for the next start.

local names = {}
for index, module in ipairs(uji.modules("uji.themes")) do
  names[index] = module:match("[^.]+$")
end
uji.ui.select({ title = "Theme", items = names }, function(name)
  if name then
    uji.ui.configure({ theme = name })
    uji.ui.save_theme(name)
  end
end)

uji puts the saved theme on before it runs your config, so a theme your config sets still wins.

Building a theme

require("uji.themes.default") is a function that takes the parts you change and returns a whole theme. Everything you leave out keeps its default.

local ito = require("ito")

return require("uji.themes.default")({
  name = "harbor",
  colors = {
    text = ito.rgb(0xc0caf5),
    muted = ito.rgb(0x565f89),
    accent = ito.rgb(0x7aa2f7),
    user_bg = ito.rgb(0x24283b),
  },
  styles = function(colors)
    return {
      user = ito.TextStyle({ foreground = colors.text, background = colors.user_bg, italic = true }),
    }
  end,
  symbols = { pointer = "▸" },
})

Changing a colour also changes every default style drawn in it, so a new accent recolours the headings, the chosen items and the rest. styles is a table of the styles you change, or a function that takes the theme’s colours and returns that table.

A theme that builds on another one reads its values:

local ito = require("ito")
local harbor = require("uji.themes.harbor")

return require("uji.themes.default")({
  name = "harbor_warm",
  colors = {
    text = harbor.colors.text,
    muted = harbor.colors.muted,
    accent = ito.rgb(0xff9e64),
  },
})

The theme table

KeyMeaning
nameThe theme’s name. Error messages use it.
colorsNamed colours.
stylesNamed text styles.
symbolsThe symbols uji draws. See Symbols, words and sizes.
bordersThe characters of each kind of box. See Borders.
textThe words uji draws.
limitsSizes and timings.
optionsAnything the theme wants to keep for itself.
viewsReplacements for the views uji draws. See The screen and Views.

Build a theme with uji.themes.default, which fills in everything you leave out. colors and styles can also hold names of your own, for your own views.

Colours

A colour is an ito.Color value, made in one of three ways:

  • ito.rgb(0xd4d4d4) gives a colour from its red, green and blue parts.
  • ito.Color.indexed(245) gives one of the terminal’s 256 colours, numbered from 0 to 255.
  • ito.Color.cyan is one of the terminal’s named colours. The names are black, red, green, yellow, blue, magenta, cyan, white, gray, dark_gray, light_red, light_green, light_yellow, light_blue, light_magenta and light_cyan.

The default theme has these colours.

ColourDefault
textito.rgb(0xd4d4d4)
mutedito.rgb(0x808080)
codeito.rgb(0xe0af68)
accentito.Color.cyan
user_bgito.rgb(0x343541)
selected_bgito.rgb(0x3a3a4a)
cursorito.Color.white
errorito.Color.red
noticeito.Color.red
warningito.Color.yellow
syntax.keyword, syntax.string, syntax.number, syntax.commentito.Color.cyan, ito.rgb(0xe0af68), ito.rgb(0xe0af68), ito.rgb(0x808080)
syntax.func, syntax.type, syntax.constantito.rgb(0xdcdcaa), ito.rgb(0x4ec9b0), ito.rgb(0x569cd6)
call.doneito.rgb(0x87d787)
diff.added, diff.removedito.rgb(0x5fd75f), ito.rgb(0xd75f5f)
diff.added_bg, diff.removed_bgito.rgb(0x005f00), ito.rgb(0x5f0000)
diff.added_word_bg, diff.removed_word_bgito.rgb(0x008700), ito.rgb(0x870000)

syntax and diff are groups: tables of colours under one name. syntax colours the code in replies and diffs, and diff colours the lines a diff adds and removes. A theme that sets a group sets every colour in it.

A theme can also set these colours, which the default theme leaves out.

ColourPaintsWithout it
backgroundThe screen style.The terminal’s own background.
linkLinks in the link style.Links in the text’s colour.

A theme with a background colour paints every cell. A terminal draws a painted cell fully opaque unless it applies its opacity to painted cells too, which Ghostty does with background-opacity-cells = true.

local ito = require("ito")

return require("uji.themes.default")({
  name = "night",
  colors = { background = ito.rgb(0x1a1b26), link = ito.rgb(0x7dcfff) },
})

Styles

A style is an ito.TextStyle value. It takes a table with foreground, background and any of the flags bold, dim, italic, underline, reverse, strikethrough and blink. The colours are ito.Color values, and every field can be left out.

local ito = require("ito")

local note = ito.TextStyle({ foreground = ito.Color.yellow, italic = true })

style:merge(other) gives a style with the colours and flags of other on top of those of style.

Styles come in groups too, such as styles.syntax and styles.diff. A theme that sets a group sets every style in it.

The default theme has these styles.

StyleUsed forDefault
plainText with the terminal’s own style.no style
screenThe background of the whole screen, and of the lists and boxes drawn over it.on background
textBody text.text
boldTitles and tool calls.text, bold
mutedSecondary text.muted
dimHints and counts.muted, dim
faintThe model’s thinking.muted, italic, dim
systemSystem messages.muted, italic
codeCode and maths.code
accentLarge headings and the chosen item.accent, bold
highlightKeywords in code and keys in hints.accent
userYour messages.text on user_bg
selectedThe background of a chosen row.on selected_bg
chosenA chosen row in a picker.text on selected_bg
chosen_nameThe name on a chosen suggestion.accent on selected_bg
chosen_descThe description on a chosen suggestion.muted on selected_bg
errorErrors and failed tool output.error
noticeA notice a uji.ui.Notice draws.notice
warningA warning drawn above the input, such as a deprecated plugin.warning
cursorThe cursor block, drawn over the character it sits on.cursor on cursor, blink
inputText on the input line.text
borderBorders.muted
reverseSelected text and the copy message.reverse
confirm_titleThe approval question’s title.text, bold
confirm_bodyThe approval question’s details.text
confirm_selectedThe chosen answer.accent, bold
confirm_unselectedThe other answer.muted
heading1 to heading6Markdown headings of each level.accent, bold for 1 and 2, text, bold for the rest
strong, emphasis, strikethrough, linkMarkdown bold, italic, struck and linked text, merged on top of the text around it.bold, italic, strikethrough, link underlined
table_headThe header row of a table, merged on top of each cell.bold
syntax.keyword, syntax.string, syntax.number, syntax.comment, syntax.func, syntax.type, syntax.constantHighlighted code, in replies and in diffs.the syntax colour of the same name, syntax.comment in italic
selectionText you select with the mouse.reverse
call.label, call.detailA tool call’s name and, in brackets after it, its subject.text, bold, and text
call.running, call.done, call.failedThe mark before a tool call while it runs, after it worked and after it failed. call.done also marks a job that finished.muted, call.done, error
diff.added, diff.removedAdded and removed lines in a diff, across the whole row.on diff.added_bg, text on diff.removed_bg
diff.added_sign, diff.removed_signThe number and the + or - of those lines.diff.added on diff.added_bg, diff.removed on diff.removed_bg
diff.added_word, diff.removed_wordThe words that changed on those lines, merged on top.on diff.added_word_bg, on diff.removed_word_bg

Symbols, words and sizes

KeyMeaningDefault
symbols.spinnerThe frames of the waiting animation.⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏
symbols.toolThe mark before a tool call.⏺
symbols.branchThe mark before a tool’s output.⎿
symbols.moreThe mark before the count of hidden output lines.…
symbols.shellThe mark before a command you ran.!
symbols.ruleThe line drawn where the session was compacted.─
symbols.noticeThe mark uji.ui.Notice puts before its text.!
symbols.thinkingThe bar beside the model’s thinking.│
symbols.queuedThe mark before a queued message.›
symbols.runningThe mark before the tool that is running, and before a job that runs in the jobs list.⋯
symbols.doneThe mark before a job in the jobs list that finished cleanly.✓
symbols.stoppedThe mark before a job in the jobs list that you stopped.⊘
symbols.failedThe mark before a job in the jobs list that failed or timed out.✗
symbols.separatorThe mark between the parts of the status line.·
symbols.jumpThe arrow on the jump to the bottom.↓
symbols.bulletsThe bullets of each list level, used in turn.• ◦ ▪
symbols.quoteThe bar beside a quote.│
symbols.columnThe line between table columns.│
symbols.task_done, symbols.task_openThe marks of a done and an open task.[x], [ ]
symbols.inputThe mark in front of each row of the input line, in the accent style.""
symbols.maskWhat hidden input, such as a key, shows instead of each character.•
symbols.pointerThe mark beside the chosen item in a list or an approval.›
symbols.promptThe mark before what you type in a picker or prompt.>
text.confirm_yesThe word that allows a tool call."Yes"
text.confirm_noThe word that refuses it."No"
text.exitThe word before a command’s exit status."exit"
text.compactedThe label where the session was compacted."compacted"
text.hiddenThe count of hidden output lines. %d is the count."+%d lines"
text.jumpThe label that takes you back to the bottom."Jump to bottom"
text.orderedThe number of an ordered list item. %d is the number."%d."
text.currentThe label beside the item in use, such as the current model."(current)"
text.rangeThe count under a long list. The numbers are the first and last shown and the total."%d–%d of %d"
text.confirm_allow, text.confirm_denyThe rest of each approval answer, after confirm_yes and confirm_no."proceed", "and tell uji what to do differently"
text.scrollThe line an approval shows when its details do not fit."lines %d-%d of %d, scroll for more"
text.workingThe line shown while the model works. %d is the seconds so far."Working (%ds)"
text.jobThe name of a background job wherever uji shows one: the jobs list, its notices and the job_output and stop_job lines. %d is its number."job %d"
text.jobs_hintThe line under the input once a job finishes, naming where its output went."/jobs to see finished jobs"
text.jobs_titleThe title of the jobs list that /jobs opens."Jobs"
text.jobs_countThe count beside that title. The first number is how many jobs run and the second how many jobs there are, those it names below included."%d/%d running"
text.jobs_moreThe line under a full jobs list, after symbols.more, naming the jobs it left out. %d is the count."%d more"
text.output, text.stop, text.closeWhat Enter, x and Esc do in the jobs list, after their keys."output", "stop", "close"
text.added, text.removedThe parts of the line above a diff, joined by a comma when both are there. %d is the count and %s is text.line or text.lines. The line starts with a capital letter."Added %d %s", "removed %d %s"
text.line, text.linesThe word for one line and for more."line", "lines"
text.copied, text.copied_terminalThe message after you copy a selection. %d is the line count."copied %d line(s)", "copied %d line(s) via the terminal"
text.pasted_lines, text.pasted_charsThe placeholder for a long paste in the input line. The numbers are the paste’s number and its size."[paste #%d +%d lines]", "[paste #%d %d chars]"
text.imageThe placeholder for an attached image."[image #%d]"
text.sessions_titleThe title of uji list. %s is the directory."Sessions in %s"
text.sessions_emptyWhat uji list says when there is nothing to show."No sessions in current directory"
text.column_title, text.column_updated, text.column_idThe column heads of uji list."TITLE", "UPDATED", "ID"
text.key_move, text.key_open, text.key_quitThe keys in the hint under uji list and the jobs list."↑/↓", "enter", "esc"
text.key_stopThe key in the jobs list hint that stops the chosen job."x"
text.navigate, text.resume, text.quitWhat those keys do."navigate", "resume", "quit"
limits.spinner_intervalSeconds between spinner frames.0.08
limits.suggest_rowsRows the command suggestions may use.5
limits.tool_previewRows of tool output shown before you open it.8
limits.diff_previewRows of a diff shown before you open it.20
limits.diff_contextUnchanged lines that uji.diff keeps around each change.3
limits.argument_previewCharacters of a tool call’s arguments shown when it has no subject.200
limits.message_gapBlank rows between messages.1
limits.section_gapBlank rows before the queue and the running tool.1
limits.bottom_gapRows kept free under the transcript, where the jump shows.1
limits.indentColumns each list or quote level is indented by.2
limits.rule_widthThe longest a markdown rule is drawn.60
limits.block_gapBlank rows between markdown blocks.1
limits.reply_marginColumns to the left of a reply.1
limits.input_rowsThe most rows the input line grows to.10
limits.select_rowsThe most rows a list takes, with the line under it that counts its items.13
limits.suggest_nameThe width of a command’s name in the suggestions.12
limits.preview_minThe width a picker needs on each side before it shows a preview.24
limits.sessions_updated, limits.sessions_idThe widths of the UPDATED and ID columns of uji list.14, 36
limits.float_width, limits.float_heightThe share of the screen, in percent, that a floating picker or overlay takes.90, 80
limits.flashSeconds a notice stays up, until one asks for its own time.1
limits.paste_lines, limits.paste_charsThe size a paste can be before the input line shows a placeholder for it.1, 80

A key uji does not know is an error, so a misspelled one does not go unnoticed.

Borders

borders.plain and borders.rounded give the characters a box of that kind is drawn with. A horizontal border uses the plain border’s horizontal.

borders = {
  rounded = {
    top_left = "╭",
    top_right = "╮",
    bottom_left = "╰",
    bottom_right = "╯",
    horizontal = "─",
    vertical = "│",
  },
}

The default plain border is ┌ ┐ └ ┘ ─ │, and the rounded one is ╭ ╮ ╰ ╯ ─ │, in the same order as above.

The screen

uji.ui.Screen is the view of the whole screen, and a theme replaces it in views. The replacement takes screen, which holds uji’s parts, and each call gives a fresh view of that part:

CallWhat it shows
screen.transcript()The messages.
screen.composer()The input line, or the approval question, which takes the input line’s place while it is open.
screen.jobs()The jobs list under the input; takes no room while it is closed.
screen.status()The status line, or the bar a plugin set with uji.ui.status.
screen.modals()The lists to choose from, the prompts, the command suggestions and overlays opened with float = false. They take no room while none is open, and on a screen without this part they float in a box instead.
screen.activity()The line shown while the model works, with no room while the model is idle.
screen.greeting()The theme’s uji.ui.Greeting.

Plugins put their views in toolbar sections, and the screen decides where each section sits with ito.ToolbarItems(ito.ToolbarPlacement.x). A section the screen leaves out is not drawn. The theme never names a plugin, and no plugin names a part of the screen.

This screen puts the input line in a rounded box at the top, the row of keyboard items under it, and the bottom bar’s items side by side:

local ito = require("ito")

return require("uji.themes.default")({
  views = {
    [uji.ui.Screen] = function(screen)
      local placement = ito.ToolbarPlacement
      return ito.VStack({
        screen.composer():border(ito.theme().borders.rounded),
        screen.modals(),
        ito.ToolbarItems(placement.keyboard, ito.HStack),
        screen.transcript():grow(),
        screen.activity(),
        screen.jobs(),
        screen.status(),
        ito.ToolbarItems(placement.bottom_bar, ito.HStack),
      })
    end,
  },
})

The default screen is this view:

function(screen)
  local placement = ito.ToolbarPlacement
  return ito.VStack({
    ito.HStack({
      ito.ToolbarItems(placement.top_bar_leading, ito.HStack),
      ito.Spacer(),
      ito.ToolbarItems(placement.top_bar_trailing, ito.HStack),
    }),
    screen.greeting(),
    screen.transcript():grow(),
    screen.activity():padding({ vertical = 1 }),
    screen.modals(),
    ito.ToolbarItems(placement.keyboard),
    screen.composer():border(ito.theme().borders.plain, { edges = ito.Edges.horizontal }),
    screen.jobs(),
    screen.status(),
    ito.ToolbarItems(placement.bottom_bar),
  })
end

A screen that raises an error is replaced by the default screen for that frame, and uji records the problem once, where /diagnostics shows it.

Views

Everything uji draws is a view in uji.ui, and a theme replaces any of them in views, keyed by the view itself. A replacement is a function that takes the view’s props and returns a view.

local ito = require("ito")

return require("uji.themes.default")({
  views = {
    [uji.ui.Queued] = function(props)
      local styles = ito.theme().styles
      return ito.HStack({ ito.Text("note: "):style(styles.accent), ito.Text(props.text):style(styles.text) })
    end,
  },
})
ViewPropsWhat it draws
uji.ui.Screenthe partsThe whole screen. See The screen.
uji.ui.GreetingnoneWhat the screen shows before you start, such as a logo. It draws nothing until a theme replaces it.
uji.ui.UserMessagemessageOne of your messages.
uji.ui.ToolCallcall, with name and argumentsA tool call, described the way its tool asks.
uji.ui.ToolOutputcontent, summary, diff, failed, expanded, toggleA tool’s result. It shows the diff when the result has one with changes, otherwise the summary until it is opened, otherwise the content. toggle opens or folds it, and the default view calls it when you click a line.
uji.ui.Diffdiff, limit, toggleThe lines of a diff, with their numbers and colours, in a tool’s result and in the approval question. diff is what uji.diff gives, limit, when given, folds it after that many rows, and toggle opens or folds it.
uji.ui.Shellcommand, code, output, failed, expanded, toggleA command you ran with !.
uji.ui.SystemMessage, uji.ui.ErrorMessage, uji.ui.Queued, uji.ui.ThinkingtextA message or line of that kind.
uji.ui.PartialtextThe last line of a reply that is still arriving.
uji.ui.CompactionnoneThe place where the session was compacted.
uji.ui.Runningname, lineThe tool that is running and the last line it printed.
uji.ui.JobjobA background job that is running. job has id, command and last, the last line it printed.
uji.ui.JumpfollowThe label that takes you back to the bottom, centred in the bottom row of the transcript. follow goes back.
uji.ui.Paragraphtokens, indent, hangingA markdown paragraph or list item. Each token has text, style and spaced, and indent and hanging start the first and the following lines.
uji.ui.Headinglevel, contentA markdown heading. content is the heading’s text as a view.
uji.ui.CodeBlocklanguage, linesA fenced code block: its language, then its code. lines holds the lines of code, and language can be nil.
uji.ui.Codelanguage, linesThe lines of a code block, highlighted for language, without the language above them.
uji.ui.MathBlocklinesDisplay maths, already turned into text.
uji.ui.TablerowsA table, its columns lined up. Each row has cells, one list of spans per cell, and head, which is true for the header row.
uji.ui.RulenoneA markdown rule.
uji.ui.ActivitynoneThe line shown while the model works.
uji.ui.FlashnoneThe copy message in the top right corner.
uji.ui.InputnoneThe input line.
uji.ui.SelectListtitle, query, items, matches, selection, currentA list to choose from. matches are the indexes into items that fit the query, and selection is a state that holds the chosen match, ready for ito.List.
uji.ui.PromptFieldtitle, valueA question with a text answer.
uji.ui.Suggestionsitems, selectionThe command suggestions. Its items have name and desc.
uji.ui.Approvaltitle, body, preview, allow, keys, scrollAn approval. scroll is the ito.ScrollState of its body.
uji.ui.Pickertitle, items, matches, selection, current, preview, query, totalThe picker with a preview.
uji.ui.Sessionsdirectory, sessions, selection, nowThe screen uji list shows. selection holds the chosen session’s index, ready for ito.List.

ito.theme() gives the theme’s colors, styles, symbols, borders, text, limits and options. Asking its styles for a name the theme does not have raises an error, such as the theme has no style named heading7. It also has these helpers.

HelperReturns
ctx:typed(field, styles)The spans of a text field with the cursor in it. field has text, cursor and hidden, and styles has text and cursor.
ctx:measure(text)The number of columns text takes.
ctx:first(text, count)The first count characters of text.

A replacement that raises an error is skipped, uji draws the view’s own default instead, and the problem is recorded once, such as theme view: no queue today, where /diagnostics shows it. A plugin’s views are replaced the same way: the plugin exports its view, and a theme keys its replacement by it.

A theme from a base16 palette

A base16 scheme gives sixteen colours, base00 to base0F. Keep them in a local table and pick the theme’s colours from it:

local ito = require("ito")

local base = {
  base03 = ito.rgb(0x707880),
  base05 = ito.rgb(0xc5c8c6),
  base08 = ito.rgb(0xcc6666),
  base0A = ito.rgb(0xf0c674),
  base0D = ito.rgb(0x81a2be),
}

return require("uji.themes.default")({
  name = "dusk",
  colors = {
    text = base.base05,
    muted = base.base03,
    code = base.base0A,
    accent = base.base0D,
    error = base.base08,
    notice = base.base08,
  },
})

Mistakes

A theme with a mistake raises an error that says where it is, such as theme.styles.user: must be an ito.TextStyle, not a table, and the theme in use stays on.