Carousel for Vim/NeoVim

Carousel 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

1. Installation
2. Loading Themes
3. Theme/Colorscheme Switching
4. Background Toggling
5. Colorcolumn Toggling
6. Colorize/Italicize
7. Get Syntax Highlighting
8. Cursor Shapes
9. Reset Functions
10. Default Key Mappings
11. 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 to vimrc
• CoC
  • CoC Warning, Error, Info message as well as GitGutter highlights are customized
  • (can be disabled by adding let g:carousel_coc_highlights = 0 to vimrc
• 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 to vimrc
• Vim Better Whitespace
  • Vim-Better-Whitespace ExtraWhitespace highlight is underlined in red
  • (can be disabled by adding let g:carousel_extra_whitespace_highlights = 0 to vimrc
• 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 when g:carousel_mappings_enabled=1
  • (can be disabled by adding let g:carousel_clap_provider_enabled = 0 to vimrc

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.

---