# Themes
Use themes to control Oyo colours.
Oyo has two theme types:
- UI themes control the chrome, diff markers and interface elements
- syntax themes control code token colours
You can set them separately. If you do not set a syntax theme, Oyo tries to use the UI theme name.
## Set a UI theme
Set a built-in UI theme in `config.toml`:
```toml
[ui.theme]
name = "tokyonight"
```
Set light or dark mode:
```toml
[ui.theme]
name = "tokyonight"
mode = "light" # or "dark"
```
List built-in UI themes:
```sh
oy themes
```
## Built-in UI themes
| `aura` | yes | no |
| `ayu` | yes | no |
| `catppuccin` | yes, mocha | yes, latte |
| `catppuccin-frappe` | yes | no |
| `catppuccin-macchiato` | yes | no |
| `cobalt2` | yes | no |
| `dracula` | yes | no |
| `everforest` | yes | yes |
| `flexoki` | yes | yes |
| `github` | yes | yes |
| `gruvbox` | yes | yes |
| `kanagawa` | yes | no |
| `material` | yes | no |
| `monokai` | yes | no |
| `nightowl` | yes | yes |
| `nord` | yes | no |
| `one-dark` | yes | yes |
| `palenight` | yes | no |
| `rosepine` | yes | yes, dawn |
| `solarized` | yes | yes |
| `synthwave84` | yes | no |
| `tokyonight` | yes | yes, day |
| `zenburn` | yes | no |
UI theme tokens are defined in [theme schema](../crates/oyo/themes/schema.json).
## Add a custom UI theme
Put JSON theme files in one of these locations:
```text
~/.config/oyo/MyTheme.json
~/.config/oyo/themes/MyTheme.json
```
Then use the file name in your config. The extension is optional.
```toml
[ui.theme]
name = "MyTheme"
```
You can provide light and dark variants:
```text
~/.config/oyo/themes/MyTheme-light.json
~/.config/oyo/themes/MyTheme-dark.json
```
Oyo picks the variant that matches `ui.theme.mode`. If one variant is missing, Oyo falls back to the other.
## Use ANSI colour names
Theme tokens can use ANSI colour names from your terminal palette.
```json
{
"theme": {
"diffAdded": { "dark": "green" },
"diffRemoved": { "dark": "red" }
}
}
```
Supported names are:
- `black`
- `red`
- `green`
- `yellow`
- `blue`
- `magenta`
- `cyan`
- `gray`
- `dark_gray`
- `light_red`
- `light_green`
- `light_yellow`
- `light_blue`
- `light_magenta`
- `light_cyan`
- `white`
- `default`
- `reset`
- `transparent`
## Set a syntax theme
Syntax highlighting uses TextMate `.tmTheme` files. Use a built-in syntax theme or provide your own file.
```toml
[ui.syntax]
mode = "on" # "on" or "off"
theme = "tokyonight"
```
If `ui.syntax.theme` is empty, Oyo uses `ui.theme.name`. If Oyo still cannot resolve a syntax theme, it uses `ansi`.
## Set syntax warmup budgets
Use warmup budgets to control how much syntax highlighting Oyo prepares for large files.
```toml
[ui.syntax.warmup]
active_lines = 100
pending_lines = 300
idle_lines = 1000
debounce_ms = 80
```
## Use light syntax variants
When `ui.theme.mode = "light"`, Oyo tries a light syntax variant first.
| `tokyonight` | `tokyonight-day` |
| `rosepine` | `rosepine-dawn` |
| `catppuccin` | `catppuccin-latte` |
Custom syntax themes can also provide light and dark variants. For example:
```text
cyberdream-light.tmTheme
cyberdream-dark.tmTheme
```
Oyo picks the variant that matches `ui.theme.mode`. If one variant is missing, Oyo falls back to the other.
You can also choose a variant directly:
```toml
[ui.syntax]
theme = "tokyonight-day"
```
## List syntax themes
Run:
```sh
oy syntax-themes
```
This lists:
- embedded syntax themes for built-in UI themes
- `.tmTheme` files in `~/.config/oyo/themes`
## Add a custom syntax theme
Put a `.tmTheme` file in:
```text
~/.config/oyo/themes/MyTheme.tmTheme
```
Then use the theme name:
```toml
[ui.syntax]
theme = "MyTheme"
```
You can also pass a full path:
```toml
[ui.syntax]
theme = "/path/to/MyTheme.tmTheme"
```
If Oyo cannot load the file, it falls back to `ansi`.
## Override themes from the CLI
```sh
oy --theme-name tokyonight --theme-mode light
oy --syntax-theme tokyonight-day
```
Oyo strips syntax theme backgrounds so the UI and diff backgrounds stay consistent.