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

Demo

📦 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 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.
    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 will blend better on all backgrounds.
    legacy_computing_symbols_support = false,
  },
}

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.
    cursor_color = "#d3cdc3",
  }

Examples

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.5,      -- 0.3      [0, 1]
    distance_stop_animating = 0.5, -- 0.1      > 0
    hide_target_hack = false,      -- true     boolean
  },

[!WARNING] *� 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 = "#ff8800",
    stiffness = 0.3,
    trailing_stiffness = 0.1,
    trailing_exponent = 5,
    gamma = 1,
  }

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",
  },

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,
  }

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

1. Clone the repository
2. Run make install to install the pre-commit hooks