Vim/NeoVim
Carousel forCarousel is a theme-switcher that allows you to easily load and cycle through your colorschemes
It is also provides an interface to dynamically control several of Vim's visual elements and behavior: background, cursor, textwidth and cursorcolumn, and text styles.
Table of Contents
- Installation
- Loading Themes
- Theme/Colorscheme Switching
- Background Toggling
- Colorcolumn Toggling
- Colorize/Italicize
- Get Syntax Highlighting
- Cursor Shapes
- Reset Functions
- Default Key Mappings
- Dependencies/Integrations
Installation
For vim-plug users, add the following to your .vimrc
or init.vim
:
Plug 'frescoraja/carousel.vim'
Then exit Vim and execute vim +PlugInstall
from the command line, or restart Vim and run :PlugInstall
.
To enable theming functionality, the following global variable must be set:
let g:carousel_enabled = 1
To set a default theme to load on startup:
let g:carousel_theme_name='default'
For example, to set apprentice
theme to load on startup in diff
mode, with
random
theme otherwise:
if &diff
let g:carousel_theme_name='apprentice'
else
let g:carousel_theme_name='random'
endif
To use default key mappings:
let g:carousel_mappings_enabled=1
Plugin Commands Usage
Loading Themes
Use Carousel
to load specific theme of choice. Themes are a complementary colorscheme/vim-airline theme
combination, along with some highlighting tweaks I felt were beneficial or made theming more consistent. For example,
when a new theme is loaded, the background colors used by ALE are set to complement the
theme's existing background colors. See dependencies at the bottom for integrated plugins.
Use <Plug>Carousel
to bring up autocompletion menu with available themes to load.
" define custom mapping:
nmap <F1> <Plug>Carousel
" Load a specific theme:
nmap <F12> :Carousel blayu<CR>
Themes/Colorschemes Switching
Use <Plug>CarouselNext
to cycle forwards through theme carousel.
Use <Plug>CarouselPrev
to cycle backwards through theme carousel.
Use <Plug>ColorschemeNext
to cycle forwards through colorschemes.
Use <Plug>ColorschemePrev
to cycle backwards through colorschemes.
Toggle Background Color and Transparency
Use <Plug>ToggleDark
to toggle Vim background
option value between dark and light
Use <Plug>ToggleBackground
to toggle background color between the colorscheme's defined background and the
background color you have defined for your terminal. (sets guibg/ctermbg
to None, making Vim background transparent)
Works in both gui mode and cterm mode.
Toggle ColorColumn/Textwidth
Use <Plug>SetTextwidth
or SetTextwidth <num>
to set &textwidth value
Use <Plug>ToggleColumn
or SetTextwidth!
to toggle the cursorcolumn
As an example, the following mapping would enable you to type tw=90
+ Enter in normal mode to change the
textwidth to 90. (It will also move the colorcolumn to 90)
" Set textwidth
nmap tw= <Plug>SetTextwidth
Colorize/Italicize
Note Your terminal may not support displaying italicized fonts by default. See instructions
here for enabling italics in
iTerm2 and Mac default Terminal. You may also have to add the following lines to your .vimrc
:
let &t_ZH="\e[3m"
let &t_ZR="\e[23m"
" OR
set t_ZH=^[[3m
set t_ZR=^[[23m
" OR have plugin enable italics
let g:carousel_italics_enabled=1
the
^[
above is an escape sequence you can generate in insert mode by pressing CTRL + V then ESC
Use <Plug>ToggleItalics
to toggle italics mode for Comments and some other predefined syntax groups like
HTML attribute args. You can italicize specific syntax groups by appending them as a comma-separated list to the
<Plug>Italicize
or :Italicize
command:
:Italicize String,Comment
Use <Plug>Colorize
or :ColorizeSyntaxGroup
to apply a color to the syntax group of your choice.
For example, the following mapping would enable you to make the ColorColumn
syntax group red by typing F1:
nmap <F1> <Plug>Colorize ColorColumn red<CR>
when termguicolor
is enabled, you can specify hex code colors ie #FF0000
(the #
is optional when typing command)
You can toggle italics for any syntax group you'd like. Just use the Italicize!
method followed by the highlight
group you want to toggle italics for. You can specify multiple groups separated by a comma. You can make a mapping if
you like to italicize specific groups frequently, or perhaps set an autocmd to do it for specific filetypes:
" Shift+F1 to toggle italics for comments, html attributes, WildMenu
nmap <S-F1> <Plug>ToggleItalics
" Shift+F2 to toggle italics for String, Statement, Identifier
nmap <S-F2> <Plug>Italicize String,Statement,Identifier<CR>
" Automatically italicize Identifier keywords when opening javascript files
autocmd FileType javascript* Italicize! Identifier
Get Syntax Highlighting
<Plug>GetSyntax
This is useful for customizing themes and defining your own syntax highlighting colors. Will print
a statement in command line showing all the highlighting groups that apply to the word under the cursor, ie
<current word> => vimStatement, Statement
Custom Cursor Shapes
Set g:carousel_cursors_enabled
to apply the following cursors:
- block in normal mode - (
█
) - vertical line in insert mode (appears between characters so it's easier to see precisely where characters will be
inserted) - (
▎
) - underline in replace mode (
_
)
" enable custom cursors
let g:custom_cursors_enabled=1
Reset functions
Use <Plug>CarouseDefault
to reset custom theme to the default defined in g:carousel_theme_name
Use <Plug>CarouseRefresh
to reload current custom theme
Note if you add a new colorscheme while vim is loaded, or if for some reason the list of available themes/colorschemes is empty, you can refresh the cache:
Use <Plug>ColorschemesReload
to reload all available colorschemes (or type :ColorschemesReload
)
Use <Plug>CarouselReload
to reload all carousel themes (or type :CarouselReload
)
Default Key Mappings
If g:carousel_mappings_enabled
is set to 1
, the following keyboard shortcuts will work automatically (if they
are not already mapped in your .vimrc
or by other plugins loaded before this one. Vim will emit a warning if this
plugin tries to override any existing key mappings, and any mappings defined after plugin is loaded will override
mappings defined by this plugin):
F5 to select a custom theme from menu/floating window using clap
provider
Shift + F5 to select a random carousel theme
F7 to cycle backwards through carousel themes
F9 to cycle forwards through carousel themes
Shift + F7 to cycle backwards through colorschemes
Shift + F9 to cycle forwards through colorschemes
Integrations
Here is a list of plugins and colorschemes that carousel.vim
supports (They are not required)
Plugins
- Ale
- ALE Warning, Error, and Info message highlights are customized
- (can be disabled by adding
let g:carousel_ale_highlights = 0
tovimrc
- CoC
- CoC Warning, Error, Info message as well as GitGutter highlights are customized
- (can be disabled by adding
let g:carousel_coc_highlights = 0
tovimrc
- Vim-Airline / Vim-Airline-Themes
- Vim-Airline automatically selects airline_theme based on colorscheme, this plugin makes some customizations
- (can be disabled by adding
let g:carousel_airline_highlights = 0
tovimrc
- Vim Better Whitespace
- Vim-Better-Whitespace ExtraWhitespace highlight is underlined in red
- (can be disabled by adding
let g:carousel_extra_whitespace_highlights = 0
tovimrc
- Vim Clap
- Vim Clap integration enabled by default if installed, defining a
g:clap_provider_themes
provider which will list all carousel themes in a floating window via command:Clap themes
- F5 will be mapped to
:Clap themes
command wheng:carousel_mappings_enabled=1
- (can be disabled by adding
let g:carousel_clap_provider_enabled = 0
tovimrc
- Vim Clap integration enabled by default if installed, defining a
Colorschemes
- afterglow
- allomancer
- apprentice
- ayu
- blayu
- candid
- ceudah
- challenger_deep
- chito
- colorsbox
- deep-space
- default
- deus
- distill
- edar/elit
- edge
- everforest
- gotham
- gruvbox
- gruvbox8
- gruvbox-material
- gummybears
- hybrid-material
- iceberg
- jellybeans
- kafka/dark
- kuroi
- mango
- material-monokai
- material-theme
- material
- maui
- maui-airline
- miramare
- molokai
- neodark
- nightowl
- nord
- oceanic-next
- onedark
- onedarkafterglow
- plastic
- pink-moon
- quantum
- rigel
- seabird
- sonokai
- spring-night
- srcery
- tender
- thaumaturge
- tokyo-metro
- Tomorrow-Night
- one
- two-firewatch
- yowish
- vim-material
- The following colorschemes from vim-colorschemes
- busybee
- flatcolor
- znake
My appreciation goes to all the maintainers of above plugins/themes for their attention to aesthetics and detail.