Screenkey.nvim

Screenkey is a Neovim plugin that displays the keys you are typing in a floating window, just like screenkey does. It is useful for screencasts, presentations, and live coding sessions.

📺 Showcase

https://github.com/NStefan002/screenkey.nvim/assets/100767853/29ea0949-4fd3-4d00-b5a3-2c249bb84360

⚡️ Requirements

• Neovim version >= 0.10.0
• a Nerd Font (optional, but recommended)

📋 Installation

lazy:

return {
    "NStefan002/screenkey.nvim",
    lazy = false,
    version = "*", -- or branch = "dev", to use the latest commit
}

packer:

use({ "NStefan002/screenkey.nvim", tag = "*" })

rocks.nvim

:Rocks install screenkey.nvim

[!NOTE]

• There is no need to call the setup function, only call it if you need to change some options
• There is no need to lazy load Screenkey, it lazy loads by default.

⚙️ Configuration

• Default settings

require("screenkey").setup({
    win_opts = {
        row = vim.o.lines - vim.o.cmdheight - 1,
        col = vim.o.columns - 1,
        relative = "editor",
        anchor = "SE",
        width = 40,
        height = 3,
        border = "single",
        title = "Screenkey",
        title_pos = "center",
        style = "minimal",
        focusable = false,
        noautocmd = true,
    },
    compress_after = 3,
    clear_after = 3,
    disable = {
        filetypes = {},
        buftypes = {},
        events = false,
    },
    show_leader = true,
    group_mappings = false,
    display_infront = {},
    display_behind = {},
    filter = function(keys)
        return keys
    end,
    keys = {
        ["<TAB>"] = "󰌒",
        ["<CR>"] = "󰌑",
        ["<ESC>"] = "Esc",
        ["<SPACE>"] = "␣",
        ["<BS>"] = "󰌥",
        ["<DEL>"] = "Del",
        ["<LEFT>"] = "",
        ["<RIGHT>"] = "",
        ["<UP>"] = "",
        ["<DOWN>"] = "",
        ["<HOME>"] = "Home",
        ["<END>"] = "End",
        ["<PAGEUP>"] = "PgUp",
        ["<PAGEDOWN>"] = "PgDn",
        ["<INSERT>"] = "Ins",
        ["<F1>"] = "󱊫",
        ["<F2>"] = "󱊬",
        ["<F3>"] = "󱊭",
        ["<F4>"] = "󱊮",
        ["<F5>"] = "󱊯",
        ["<F6>"] = "󱊰",
        ["<F7>"] = "󱊱",
        ["<F8>"] = "󱊲",
        ["<F9>"] = "󱊳",
        ["<F10>"] = "󱊴",
        ["<F11>"] = "󱊵",
        ["<F12>"] = "󱊶",
        ["CTRL"] = "Ctrl",
        ["ALT"] = "Alt",
        ["SUPER"] = "󰘳",
        ["<leader>"] = "<leader>",
    },
})

[^1]: This is currently an experimental feature. Please report any issues you encounter. Use it responsibly, do not set too many conditions, as it can slow down the plugin. Also, if the conflict occurs (e.g. two floating windows are present at the same time - one with the filetype that matches the display_infront condition and the other with the filetype that matches the display_behind condition), nothing will happen (this is subject to change)

[^2]: Same as above

❓ How to use

• :Screenkey toggle (or just Screenkey) to toggle the screenkey

• Don't worry about leaking your passwords when using sudo while streaming/recording because you forgot to turn off your display-key application, Screenkey will only show pieces of information about your input in Neovim.

• This plugin exposes get_keys function that you can use in a statusline component. You can use :Screenkey toggle_statusline_component or change vim.g.screenkey_statusline_component to toggle this feature on/off. For lualine it would look something like this:

vim.g.screenkey_statusline_component = true

vim.keymap.set("n", "<leader>ssc", function()
    vim.g.screenkey_statusline_component = not vim.g.screenkey_statusline_component
end, { desc = "Toggle screenkey statusline component" })

require("lualine").setup({
    -- other options ...
    sections = {
        -- other sections ...
        lualine_c = {
            -- other components ...
            function()
                return require("screenkey").get_keys()
            end,
        },
    },
})

• Run :checkhealth screenkey to diagnose possible configuration problems

• Screenkey exposes redraw function that redraws the Screenkey window, could be used like this:

require("screenkey").redraw()

or

:Screenkey redraw

• Screenkey exposes is_active function that returns true if the Screenkey window is active, false otherwise, could be used like this:

local screenkey = require("screenkey")
local notify = require("notify")
local toggleScreenKey = function()
    vim.cmd("Screenkey toggle")
    -- change notification position
    notify.setup({
        top_down = screenkey.is_active(),
    })
end

vim.keymap.set("n", "<leader>tsk", toggleScreenKey, { desc = "[T]oggle [S]creen[K]ey" })

[!NOTE] If you're using a terminal inside of the Neovim, and you want screenkey to automatically stop displaying your keys when you're > inside of the terminal, see disable option in the plugin configuration.

• For fully custom statusline users, screenkey will fire User events if vim.g.screenkey_statusline_component is enabled. There are two patterns: ScreenkeyUpdated on keypress and ScreenkeyCleared when clearing screenkey after inactivity (see clear_after option). If you are experiencing performance issues and do not rely on these events, you can disable them with the disable.events option. Example usage with heirline:

require("heirline").setup({
    statusline = {
        {
            provider = function()
                return require("screenkey").get_keys()
            end,
            update = {
                "User",
                pattern = "Screenkey*",
                callback = vim.schedule_wrap(function()
                    vim.cmd("redrawstatus")
                end),
            },
        },
    },
})

• One example of how you could use the filter function:

-- filter out j and k keys, but only if they are not part of a mapping
require("screenkey").setup({
    filter = function(keys)
        return vim.iter(keys)
            :filter(function(k)
                return (k.key ~= "j" and k.key ~= "k") or k.is_mapping
            end)
            :totable()
    end,
})

🙏 I took inspiration (and some code) from

• nvim-best-practices
• harpoon v2

👀 Similar projects

• keys.nvim: