# Theme & Appearance
Jay's visual appearance -- colors, fonts, sizes, and layout -- is controlled by
the `[theme]` table and a handful of top-level toggles. Every setting described
here can also be adjusted at runtime from the control center's **Look and Feel**
pane, which provides color pickers and live preview.
## Colors
Colors are specified as hex strings in one of four formats:
`#rgb` (e.g. `#f00`)
: Short RGB
`#rrggbb` (e.g. `#ff0000`)
: Full RGB
`#rgba` (e.g. `#f008`)
: Short RGB + alpha
`#rrggbbaa` (e.g. `#ff000080`)
: Full RGB + alpha
The available color keys in the `[theme]` table are:
`bg-color`
: Desktop background
`bar-bg-color`
: Bar background
`bar-status-text-color`
: Status text in the bar
`border-color`
: Borders between tiled windows
`focused-border-color`
: Border color used where at least one of the adjacent windows is focused. This
applies to the border of a focused floating window, and -- when the `full`
[container border style](#container-borders) is enabled -- to the borders
touching the focused window inside a container. Defaults to the same color as
`border-color`.
`focused-title-bg-color`
: Background of the focused window's title
`focused-title-text-color`
: Text color of the focused window's title
`unfocused-title-bg-color`
: Background of unfocused window titles
`unfocused-title-text-color`
: Text color of unfocused window titles
`focused-inactive-title-bg-color`
: Background of focused-but-inactive titles
`focused-inactive-title-text-color`
: Text color of focused-but-inactive titles
`attention-requested-bg-color`
: Background of titles that have requested attention
`captured-focused-title-bg-color`
: Background of focused titles that are being recorded
`captured-unfocused-title-bg-color`
: Background of unfocused titles that are being recorded
`separator-color`
: Separator between title bars and window content
`highlight-color`
: Accent color used to highlight parts of the UI
"Focused-inactive" refers to a window that was most recently focused in its
container but whose container is not the active one. The "captured" colors apply
when a window is being recorded (e.g. via screen sharing).
### Example
```toml
[theme]
bg-color = "#1e1e2e"
bar-bg-color = "#181825"
bar-status-text-color = "#cdd6f4"
border-color = "#313244"
focused-title-bg-color = "#89b4fa"
focused-title-text-color = "#1e1e2e"
unfocused-title-bg-color = "#313244"
unfocused-title-text-color = "#cdd6f4"
attention-requested-bg-color = "#f38ba8"
highlight-color = "#f5c2e7"
```
## Sizes
`border-width`
: Width of borders between windows (px)
`title-height`
: Height of window title tabs (px)
`bar-height`
: Height of the bar (px). Defaults to the same as `title-height`.
`bar-separator-width`
: Width of the bar's bottom separator (px). Default: `1`.
```toml
[theme]
border-width = 2
title-height = 24
bar-height = 28
```
## Fonts
`font`
: General font for the compositor
`title-font`
: Font used in window title bars. Defaults to the same as `font`.
`bar-font`
: Font used in the status bar. Defaults to the same as `font`.
```toml
[theme]
font = "JetBrains Mono 10"
title-font = "Inter 10"
bar-font = "Inter 10"
```
## Bar Position
The `bar-position` field controls whether the bar appears at the top or bottom
of each output. The default is `top`.
```toml
[theme]
bar-position = "bottom"
```
## Container Borders
The `container-borders` field controls how borders are drawn within tiled
containers:
`separators`
: Only separators are drawn between the children of a container (default).
`full`
: A border is drawn around the entire container, in addition to the separators
between children.
`full-smart`
: A border is drawn around the entire container, in addition to the separators
between children, unless the container has only one child and is the root
container of the workspace.
```toml
[theme]
container-borders = "full"
```
The width and color of these borders are controlled by `border-width` and
`border-color`.
## Changing the Theme at Runtime
Use the `set-theme` action in a shortcut to change theme properties on the fly:
```toml
[shortcuts]
alt-F9 = { type = "set-theme", theme.bg-color = "#000000" }
```
Only the fields you include are changed; everything else stays the same.
## Per-Window Themes
The `[theme]` table applies to all windows. Individual windows and containers
can override parts of it. There are two kinds of overrides:
Window theme
: Applies to any window.
Container theme
: Applies to the decorations a container draws for its children.
Overrides are set with actions, usually from a shortcut or a
[window rule](../window-rules.md):
`set-window-theme`
: Sets overrides in the window theme. Takes a `theme` table.
`reset-window-theme`
: Removes all overrides from the window theme. This is a simple action and is
written as a plain string.
`set-container-theme`
: Sets overrides in the container theme. Takes a `theme` table and an optional
`target`.
`reset-container-theme`
: Removes all overrides from the container theme. Takes an optional `target`.
In a window rule, these actions apply to the matched window. Otherwise they
apply to the focused window. As with `set-theme`, the `set-*` actions only
change the fields that are included in the `theme` table.
The `target` field selects the container relative to that window, in the same
way as for [`toggle-split`](shortcuts.md):
`parent`
: The parent container of the window (default).
`self`
: The window itself.
`auto`
: The window itself if it is a container, otherwise its parent container.
If the target is not a container, the container actions have no effect.
### Available Fields
Both kinds of theme accept the following fields. They have the same meaning as
the corresponding fields in the `[theme]` table.
- `attention-requested-bg-color`
- `border-color`
- `focused-border-color`
- `focused-inactive-title-bg-color`
- `focused-inactive-title-text-color`
- `focused-title-bg-color`
- `focused-title-text-color`
- `separator-color`
- `unfocused-title-bg-color`
- `unfocused-title-text-color`
- `border-width`
- `title-height`
- `title-font`
- `show-titles`
- `show-window-icons`
- `window-icons-grayscale`
The container theme also accepts `container-borders`.
Settings that are not set fall back to other themes and finally to the
`[theme]` table. Not every setting has an effect on every window. The control
center marks settings that currently have no effect as unused.
### Examples
Remove the title and borders around a splash screen:
```toml
[[windows]]
match.title = "GIMP Startup"
match.app-id = "gimp"
initial-tile-state = "floating"
action = {
type = "set-window-theme",
theme = { show-titles = false, border-width = 0 },
}
```
Use thicker borders and full container borders in the container of the focused
window:
```toml
[shortcuts]
alt-F10 = {
type = "set-container-theme",
target = "auto",
theme = { border-width = 8, container-borders = "full" },
}
alt-shift-F10 = { type = "reset-container-theme", target = "auto" }
```
Per-window themes can also be inspected and edited in the control center. See
[Window Search](../control-center.md#window-search).
The full list of fields is in the
[auto-generated specification](https://github.com/mahkoh/jay/blob/master/toml-spec/spec/spec.generated.md).
## Window Icons
Applications can provide custom icons for their windows via the
`xdg_toplevel_icon_manager_v1` protocol. These icons are displayed in the
title bar next to the window title.
`show-window-icons`
: Show window icons set by clients. Default: `true`.
`window-icons-grayscale`
: Render window icons in grayscale. Only supported by the Vulkan renderer.
Default: `false`.
```toml
[theme]
show-window-icons = true
window-icons-grayscale = false
```
These settings can also be changed at runtime via the `set-theme` action:
```toml
[shortcuts]
alt-i = { type = "set-theme", theme.show-window-icons = false }
```
## Showing and Hiding UI Elements
These top-level settings control whether the bar and title bars are visible:
`show-bar`
: Show the built-in status bar. Default: `true`.
`show-titles`
: Show window title bars. Default: `true`.
```toml
show-bar = false
show-titles = false
```
Corresponding actions let you toggle these at runtime:
`show-bar`
: Shows the bar
`hide-bar`
: Hides the bar
`toggle-bar`
: Toggles bar visibility
`show-titles`
: Shows title bars
`hide-titles`
: Hides title bars
`toggle-titles`
: Toggles title bars
```toml
[shortcuts]
alt-b = "toggle-bar"
alt-t = "toggle-titles"
```
## Workspace Display Order
The `workspace-display-order` top-level setting controls how workspace tabs
appear in the bar:
`manual`
: Workspaces can be reordered by dragging (default)
`sorted`
: Workspaces are displayed using natural ordering.
```toml
workspace-display-order = "sorted"
```