Smear cursor for Neovim
Neovim plugin to animate the cursor with a smear effect in all terminals. Inspired by Neovide's animated cursor.
This plugin is intended for terminals/GUIs that can only display text and do not have graphical capabilities (unlike Neovide, or the Kitty terminal). Also, check out the karb94/neoscroll.nvim plugin for smooth scrolling!
🚀 Demo
smear_cursor_demo.mp4
Some configuration examples:
| Default | Faster |
|---|---|
 |
 |
| Smooth cursor without smear | Smooth caret |
|---|---|
 |
 |
| Fire hazard |
|---|
 |
📦 Installation
Note
After enabling the plugin in your configuration, you can toggle the smear cursor on and off with the :SmearCursorToggle command or with :lua require("smear_cursor").toggle().
Minimum requirements
- Neovim 0.10.2
Using vim.pack
In your ~/.config/nvim/init.lua, add:
vim.pack.add({ "https://github.com/sphamba/smear-cursor.nvim", }) require('smear_cursor').setup({ -- Your options })
Using lazy.nvim
In ~/.config/nvim/lua/plugins/smear_cursor.lua, add:
return { "sphamba/smear-cursor.nvim", opts = {}, }
Using vim-plug
In your init.vim, add:
call plug#begin() Plug 'sphamba/smear-cursor.nvim' call plug#end() lua require('smear_cursor').enabled = true
⚙ Configuration
Using lazy.nvim
Here are the default configuration options:
return { "sphamba/smear-cursor.nvim", opts = { -- Smear cursor when switching buffers or windows. smear_between_buffers = true, -- Smear cursor when moving within line or to neighbor lines. -- Use `min_horizontal_distance_smear` and `min_vertical_distance_smear` for finer control smear_between_neighbor_lines = true, -- Draw the smear in buffer space instead of screen space when scrolling scroll_buffer_space = true, -- Set to `true` if your font supports legacy computing symbols (block unicode symbols). -- Smears and particles will look a lot less blocky. legacy_computing_symbols_support = false, -- Smear cursor in insert mode. -- See also `vertical_bar_cursor_insert_mode` and `distance_stop_animating_vertical_bar`. smear_insert_mode = true, }, }
Refer to lua/smear_cursor/config.lua and lua/smear_cursor/color.lua for the full list of configuration options that can be set with opts.
Tip
Some terminals override the cursor color set by Neovim. If that is the case, manually put the actual cursor color in your config to get a matching smear color:
opts = { -- Smear cursor color. Defaults to Cursor GUI color if not set. -- Set to "none" to match the text color at the target cursor position. -- Can be a hex color code, or a highlight group name. cursor_color = "#d3cdc3", }
Note
Fonts with legacy computing symbols support seems to be rare. One notable example is Cascadia Code. You can still use smear-cursor.nvim without such a font.
Examples
Tip
See videos at the top for visual examples.
🔥 Faster smear
As an example of further configuration, you can tune the smear dynamics to be snappier:
opts = { -- Default Range stiffness = 0.8, -- 0.6 [0, 1] trailing_stiffness = 0.6, -- 0.45 [0, 1] stiffness_insert_mode = 0.7, -- 0.5 [0, 1] trailing_stiffness_insert_mode = 0.7, -- 0.5 [0, 1] damping = 0.95, -- 0.85 [0, 1] damping_insert_mode = 0.95, -- 0.9 [0, 1] distance_stop_animating = 0.5, -- 0.1 > 0 },
If you notice a low framerate, you can try lowering the time interval between draws (default is 17ms):
opts = { time_interval = 7, -- milliseconds },
You can also change the "bounciness" of the smear by adjusting the damping and damping_insert_mode parameters (default to 0.85 and 0.9 respectively). Decreasing them (e.g. to 0.65) will make the smear appear more elastic (overshooting target position).
🔥 FIRE HAZARD 🔥
Feel free to experiment with all the configuration options, but be aware that some combinations may cause your cursor to flicker or even catch fire. That can happen with the following settings:
opts = { cursor_color = "#ff4000", particles_enabled = true, stiffness = 0.5, trailing_stiffness = 0.2, trailing_exponent = 5, damping = 0.6, gradient_exponent = 0, gamma = 1, never_draw_over_target = true, -- if you want to actually see under the cursor hide_target_hack = true, -- same particle_spread = 1, particles_per_second = 500, particles_per_length = 50, particle_max_lifetime = 800, particle_max_initial_velocity = 20, particle_velocity_from_cursor = 0.5, particle_damping = 0.15, particle_gravity = -50, min_distance_emit_particles = 0, }
█ Smooth cursor without smear
If you wish to only have a smoother cursor that keeps its rectangular shape (without the trail), you can set the following options:
opts = { stiffness = 0.5, trailing_stiffness = 0.5, matrix_pixel_threshold = 0.5, },
🌌 Transparent background
Drawing the smear over a transparent background works better when using a font that supports legacy computing symbols, therefore setting the following option:
opts = { legacy_computing_symbols_support = true, },
If your font does not support legacy computing symbols, there will be a shadow under the smear. You may set a color for this shadow to be less noticeable:
opts = { transparent_bg_fallback_color = "#303030", },
🔲 No GUI colors
If you are not using termguicolors, you need to manually set a color gradient for the smear (it can be a single color):
opts = { cterm_cursor_colors = { 240, 245, 250, 255 }, cterm_bg = 235, }
If you are not using guicursor, and you notice the cursor getting duplicated (smear visible at the same time as the real cursor), try setting
opts = { hide_target_hack = true, never_draw_over_target = true, }
Using init.vim
You can set the configuration variables in your init.vim file like this:
lua require('smear_cursor').setup({ \cursor_color = '#d3cdc3', \})
🤕 Known issues
- There is a shadow around the smear (text become invisible). This is inherent to the way the smear is rendered, as Neovim is not able to render superimposed characters. The shadow is less noticeable when the smear is moving faster (see configuration options).
- Likely not compatible with other plugins that modify the cursor.
👨💻 Contributing
Please feel free to open an issue or a pull request if you have any suggestions or improvements! This project uses pre-commit hooks to ensure code quality (with StyLua) and meaningful commit messages (following Conventional Commits)
Requirements
- Neovim >= 0.10.2
- Make
- pre-commit (
pip install pre-commit)
Setup
- Clone the repository
- Run
make installto install the pre-commit hooks