theming
rovr can be themed in two ways, via theme files in the themes folder and the style.tcss file.
main tcss files
Section titled “main tcss files”theme files
Section titled “theme files”themes live as tcss files in <config folder>/themes/<name>.tcss. the file name becomes the theme name in the theme picker. a file with the same name as a bundled theme overrides it. theme files are hot-reloaded while rovr is running, so you can tweak colors and watch them apply live.
a theme file is a list of variable declarations:
$primary: <color>;$secondary: <color>;$warning: <color>;$error: <color>;$success: <color>;$accent: <color>;$foreground: <color>;$background: <color>;$surface: <color>;$panel: <color>;$dark: true;
/* progress bar gradients (optional) */$bar-gradient-default: <color> <color>;$bar-gradient-error: <color> <color>;
/* any other variable used by textual or rovr's css */$block-cursor-background: <color>;Every default variable is required to be declared, but you can add any other variable that is used by textual or rovr’s css.
theme files can also contain regular tcss rules below the variable declarations:
$primary: #88c0d0;
FileList { text-style: italic;}#file_list_container { border: double $primary;}these rules only apply while the theme is active, so there is no need to scope selectors to the theme. when two rules with the same specificity conflict, the theme’s rule wins over style.tcss; a more specific selector in style.tcss still wins as usual.
you can take a look at the reference in textual, or the table below
| Variables | Description |
|---|---|
| primary | The primary color, can be considered the branding color. Typically used for titles, and backgrounds for strong emphasis. |
| secondary | An alternative branding color, used for similar purposes as primary, where an app needs to differentiate something from the primary color. |
| foreground | The default text color, which should be legible on background, surface, and panel. |
| background | A color used for the background, where there is no content. Used as the default background color for screens. |
| surface | The default background color of widgets, typically sitting on top of background. |
| panel | A color used to differentiate a part of the UI from the main content. Used sparingly in Textual itself. |
| boost | A color with alpha that can be used to create layers on a background. |
| warning | Indicates a warning. Typically used as a background color. text-warning can be used for foreground. |
| error | Indicates an error. Typically used as a background color. text-error can be used for foreground. |
| success | Used to indicate success. Typically used as a background color. text-success can be used for foreground. |
| accent | Used sparingly to draw attention. Typically contrasts with primary and secondary. |
| dark | A boolean indicating whether the theme is dark or light. |
| ansi | Whether it is an ansi theme (which automatically disables the background color). |
any other declaration becomes a custom variable, usable by textual’s additional variables and rovr’s own css.
style.tcss
Section titled “style.tcss”style.tcss is a global style file that is loaded on top of the theme. it can be used to override any theme variable, or add additional styling to widgets. it is located in <config folder>/style.tcss. this file is also hot-reloaded while rovr is running.
what is tcss?
Section titled “what is tcss?”styling in textual is handled by tcss files, a simplified version of the web’s css. Do look at Textual’s official CSS documentation on CSS and Styles Reference for a more detailed guide on Textual CSS
This guide will cover the basics of Textual CSS, including how to apply styles to rovr widgets, and themes.
Textual CSS is a powerful way to style rovr, it is a subset of CSS specifically designed for Textual applications. Let’s go over the main few things you need to take note of
DOM Tree
Section titled “DOM Tree”Similar to HTML’s DOM, Textual has a DOM tree that represents the ancestors/siblings/children of widgets. The DOM tree can be printed to stdout using
rovr --tree-domwhich will print the tree to stdout. If piped, the colors will be stripped.
Alternatively, if you want to get the DOM at runtime, you can add the folllowing to your keys.toml:
[app]"alt+t" = "print_dom"and press alt+t to print the DOM tree to stdout. You can even do
rovr --force-tty > dom.txtand press alt+t to get the DOM tree in a file.
an example truncated dom would look like this:
Application( title='rovr @ rovr', classes={'-dark-mode', '-theme-nord'}, pseudo_classes={'dark', 'focus', 'ansi'})└── _RovrScreen(id='_default', classes='-all-vertical -all-horizontal') └── Vertical(id='root', classes='comfy-panels compact-buttons') └── HorizontalGroup(id='main') └── FileListContainer(id='file_list_container') ├── SearchInput(classes='-textual-compact') ├── Static(id='file_list_details_header') └── FileList( id='file_list', name='File List', classes='file-list' )tcss works the same as css, so, if you want to target the FileList inside the #file_list_container you can do
#file_list_container > FileList { ...}/* or */#file_list { ...}CSS nesting is also allowed, so you can do
#file_list_container { FileList { ... }}however, if you took a look at the DOM tree, you may notice that class inheritance is not shown:
for example, FileList inherits from SelectionList, which inherits from OptionList, ScrollView, ScrollableContainer and finally Widget
Although this is not recommended, you can target the FileList using its parent classes:
ScrollableContainer#file_list { ...}rovr includes some extra classes that can be used to narrow down the elements, or style them based on certain scenarios.
Checkbox selection lists
Section titled “Checkbox selection lists”Lists using rovr’s checkbox renderer, including FileList, Clipboard and the TrashSelectionList, expose a component class for styling the entire checked option.
| Component Classes | Description | Example |
|---|---|---|
selection-list--option-checked |
applied on options that are checked | Clipboard > .selection-list--option-checked |
*--hovered |
used when the checked option is hovered | FileList > .selection-list--option-checked--hovered |
*--highlighted |
used when the checked option is highlighted | FileList > .selection-list--option-checked--highlighted |
FileList
Section titled “FileList”This is the main file list that you will be navigating
| Class | Description | Example |
|---|---|---|
select-mode |
applied to the FileList when in select mode, where you can select multiple files. |
FileList.select-mode |
| Component Classes | Description | Example |
|---|---|---|
filelist--cut |
applied on files/folders that are cut | FileList > .filelist--cut |
filelist--broken-link |
applied on files/folders that are broken links | FileList > .filelist--broken-link |
filelist--link |
applied on files/folders that are links | FileList > .filelist--link |
filelist--hidden |
applied on files/folders that are hidden | FileList > .filelist--hidden |
These component classes also come with their own sub classes due to textual limitations. When multiple classes apply, checked styling is used as the base and file-specific styling takes precedence for properties it defines.
| Component Classes | Description | Example |
|---|---|---|
*--hovered |
used when the option is currently hovered | FileList > .filelist--cut--hovered |
*--highlighted |
used when the option is currently highlighted | FileList > .filelist--link--highlighted |
detail columns get their own component classes. these do not have --hovered or --highlighted sub classes; only the foreground color and text style apply, on top of the row’s background.
| Component Classes | Description | Example |
|---|---|---|
filelist--detail-size |
applied on the size column | FileList > .filelist--detail-size |
filelist--detail-mtime |
applied on the modified time column | FileList > .filelist--detail-mtime |
filelist--detail-atime |
applied on the accessed time column | FileList > .filelist--detail-atime |
filelist--detail-ctime |
applied on the created time column | FileList > .filelist--detail-ctime |
filelist--detail-permissions |
applied on the permissions column | FileList > .filelist--detail-permissions |
filelist--detail-owner |
applied on the owner column | FileList > .filelist--detail-owner |
filelist--detail-group |
applied on the group column | FileList > .filelist--detail-group |
filelist--git-staged |
applied on the staged character of the git column | FileList > .filelist--git-staged |
filelist--git-unstaged |
applied on the unstaged character of the git column | FileList > .filelist--git-unstaged |
filelist--git-untracked |
applied on the git column for untracked entries | FileList > .filelist--git-untracked |
ProgressBarContainer
Section titled “ProgressBarContainer”This is the wrapper container for progress bars seen at the bottom left part of the UI.
| Class | Description | Example |
|---|---|---|
error |
applied when an error occurred while in the process | ProgressBarContainer.error |
done |
applied when the process is done, regardless of the result | ProgressBarContainer.done |
| Component Classes | Description | Example |
|---|---|---|
bar--bar |
The default bar, used when the process is working | ProgressBarContainer > .bar--bar |
bar--indeterminate |
Used when the process is still calculating and has not started yet | ProgressBarContainer > .bar--indeterminate |
bar--complete |
Used when the process is complete | ProgressBarContainer > .bar--complete |
Fuzzy Screens
Section titled “Fuzzy Screens”This is the base screen for other screens like ripgrep, fd and zoxide.
| Class | Description | Example |
|---|---|---|
empty |
applied on the OptionList when there are no options to show | ModalSearchScreen OptionList.empty |
commonly asked styles:
Section titled “commonly asked styles:”how to unseparate the header (the action buttons and the path input)
#menu_wrapper { layout: horizontal; & > Widget { width: auto; } #menu Button:last-child { margin-right: 0; } #below_menu { border-top: none !important; height: 1; Button:first-child { margin-left: 0; } }}.compact-buttons #menu_wrapper PathAutoCompleteInput { margin: -1px 1px 0 12px;}