# smear-cursor.nvim
**Repository Path**: nvim_lip/smear-cursor.nvim
## Basic Information
- **Project Name**: smear-cursor.nvim
- **Description**: δ»εΊ mirror: https://github.com/sphamba/smear-cursor.nvim.git
- **Primary Language**: Unknown
- **License**: GPL-3.0
- **Default Branch**: dev
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-13
- **Last Updated**: 2026-02-25
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# Smear cursor for Neovim
_Neovim plugin to animate the cursor with a smear effect in all terminals. Inspired by [Neovide's animated cursor](https://neovide.dev/features.html#animated-cursor)._
This plugin is intended for terminals/GUIs that can only display text and do not have graphical capabilities (unlike [Neovide](https://neovide.dev/), or the [Kitty](https://sw.kovidgoyal.net/kitty/) terminal). Also, check out the [karb94/neoscroll.nvim](https://github.com/karb94/neoscroll.nvim) plugin for smooth scrolling!
## π Demo
[Demo](https://private-user-images.githubusercontent.com/17217484/389300116-fc95b4df-d791-4c53-9141-4f870eb03ab2.mp4?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3MzI0NzY0NDAsIm5iZiI6MTczMjQ3NjE0MCwicGF0aCI6Ii8xNzIxNzQ4NC8zODkzMDAxMTYtZmM5NWI0ZGYtZDc5MS00YzUzLTkxNDEtNGY4NzBlYjAzYWIyLm1wND9YLUFtei1BbGdvcml0aG09QVdTNC1ITUFDLVNIQTI1NiZYLUFtei1DcmVkZW50aWFsPUFLSUFWQ09EWUxTQTUzUFFLNFpBJTJGMjAyNDExMjQlMkZ1cy1lYXN0LTElMkZzMyUyRmF3czRfcmVxdWVzdCZYLUFtei1EYXRlPTIwMjQxMTI0VDE5MjIyMFomWC1BbXotRXhwaXJlcz0zMDAmWC1BbXotU2lnbmF0dXJlPTg1NjFhZjJlODQ4YmU2NjAzY2EzY2I3NWMzMzI5MWQ1Njk2MTExYmEwYmExNTMwMThmYTJjYjE2ZjIyOThjNjMmWC1BbXotU2lnbmVkSGVhZGVycz1ob3N0In0.Skw2VVyVWVkMe4ht6mvl_AZ_6QasJm8O6qsIZmcQ2XE)
## π¦ 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](https://lazy.folke.io/)
In `~/.config/nvim/lua/plugins/smear_cursor.lua`, add:
```lua
return {
"sphamba/smear-cursor.nvim",
opts = {},
}
```
### Using [vim-plug](https://github.com/junegunn/vim-plug)
In your `init.vim`, add:
```vim
call plug#begin()
Plug 'sphamba/smear-cursor.nvim'
call plug#end()
lua require('smear_cursor').enabled = true
```
## β Configuration
### Using [lazy.nvim](https://lazy.folke.io/)
Here are the default configuration options:
```lua
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 will blend better on all backgrounds.
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`](https://github.com/sphamba/smear-cursor.nvim/blob/main/lua/smear_cursor/config.lua) and [`lua/smear_cursor/color.lua`](https://github.com/sphamba/smear-cursor.nvim/blob/main/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:
> ```lua
> 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
π₯ Faster smear
As an example of further configuration, you can tune the smear dynamics to be snappier:
```lua
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
},
```
> **π₯ 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:
> ```lua
> opts = {
> cursor_color = "#ff8800",
> stiffness = 0.3,
> trailing_stiffness = 0.1,
> trailing_exponent = 5,
> gamma = 1,
> }
> ```
π 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:
```lua
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:
```lua
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):
```lua
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:
```vim
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](https://pre-commit.com/) hooks to ensure code quality (with [StyLua](https://github.com/JohnnyMorganz/StyLua)) and meaningful commit messages (following [Conventional Commits](https://www.conventionalcommits.org/))
### 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