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.

<!-- prettier-ignore -->

[!WARNING] This README tracks the main branch and may include unstable or in-progress features. For the stable version, please switch to the latest tag release, and refer to the README.md in that tag.

📜 Table of Contents

• 📜 Table of Contents
• 🧠 Why
• 📺 Showcase
• 🔥 Requirements
• 📋 Installation
• 🔧 Configuration
• 🛠 Usage
  • 💻 Commands
  • 📦 API
  • 🎨 Customizing colors
  • 🧩 Statusline integration
  • ✨ Random examples
• 🙏 Inspiration
• 👀 Similar projects
• 🤝 Contributing

🧠 Why

• Don't worry about leaking your passwords (e.g. 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.
• You can use Screenkey to show your keys in a presentation or a screencast, so your audience can follow along.
• You can use Screenkey to show your keys in a live coding session, so your neovim-newbie friends can understand what you are doing.

📺 Showcase

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

🔥 Requirements

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

📋 Installation

lazy:

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

packer:

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

rocks.nvim

:Rocks install screenkey.nvim

<!-- prettier-ignore -->

[!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,
    },
    hl_groups = {
        ["screenkey.hl.key"] = { link = "Normal" },
        ["screenkey.hl.map"] = { link = "Normal" },
        ["screenkey.hl.sep"] = { link = "Normal" },
    },
    winblend = 0,
    compress_after = 3,
    clear_after = 3,
    emit_events = true,
    disable = {
        filetypes = {},
        buftypes = {},
        modes = {},
    },
    show_leader = true,
    group_mappings = false,
    display_infront = {},
    display_behind = {},
    filter = function(keys)
        return keys
    end,
    colorize = function(keys)
        return keys
    end,
    separator = " ",
    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>",
    },
    notify_method = "echo",
    log = {
        min_level = vim.log.levels.OFF,
        filepath = vim.fn.stdpath("data") .. "/screenkey_log",
    },
})

| option | explanation | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | win_opts | see :h nvim_open_win, note1: other options from nvim_open_win help can be provided (such as win, bufpos, zindex etc.), the ones listed above are just defaults) | | hl_groups | highlight groups used to color different types of displayed text: mappings, keys and separators (see ':h nvim_set_hl()') | | winblend | transparency of the floating window (0-100) | | compress after | compress input when repeated <compress_after> times (for example jjjj will be compressed to j..x4) | | clear_after | clear the input after <clear_after> seconds of inactivity, it would not be cleared if <clear_after> is below or equal to zero | | emit_events | enable/disable User events | | disable | temporarily disable screenkey for specific filetype (e.g. toml, see :h 'filetype'), buftype (e.g. terminal, see :h 'buftype') or mode (e.g. t, see :h vim-modes and :h mode()) | | group_mappings | for example: <leader>sf opens up a fuzzy finder, if the group_mappings option is set to true, every time you open up a fuzzy finder with <leader>sf, Screenkey will show ␣sf instead of ␣ s f to indicate that the used key combination was a defined mapping. | | show_leader | if this option is set to true, in the last example instead of ␣ s f Screenkey will display <leader> s f (of course, if the <space> is <leader>), if the current key is not a defined mapping, Screenkey will display <space> as ␣ | | display_infront[^1] | if the floating window containing the buffer of the same filetype as in display_infront is opened, screenkey window will be reopened in front of that window (if necessary), Note: you can define filetypes as lua regex, for example "Telescope*" to match every filetype that starts with Telescope | | display_behind[^1] | if the floating window containing the buffer of the same filetype as in display_behind is opened, screenkey window will be reopened behind of that window (if necessary), Note: you can define filetypes as lua regex, for example "Telescope*" to match every filetype that starts with Telescope | | filter | function that takes an array of objects of type screenkey.queued_keys[^2] (keys) as input and returns a filtered array of the same keys, allowing customization of which keys should be displayed, see below for example | | colorize | function that takes an array of screenkey.colored_keys[^2] (keys) as input and returns a modified array with the desired highlight groups applied, this enables dynamic styling of keys based on user preferences, see below for example | | separator | string of any length that separates the keys, space by default | | keys | how to display the special keys (or any other keys that you want to display differently)