activitybar.nvim

Small clickable activity bar for Neovim.

activitybar.nvim is a thin UI launcher. It renders a narrow clickable bar and executes user-configured commands or callbacks. It does not depend on a specific file explorer, picker, terminal, Git UI, or diagnostic UI.

The intended use case is an IDE-like starter setup where beginners can click common tools while gradually learning normal Neovim commands and leader keymaps.

Requirements

• Neovim 0.10+
• nui.nvim
• A Nerd Font if you use icon glyphs

Installation

Example for lazy.nvim:

{
  "garchomp-game/activitybar.nvim",
  tag = "v0.1.0",
  lazy = false,
  dependencies = {
    "MunifTanjim/nui.nvim",
  },
  opts = {
    position = "left",
    width = 7,
    item_height = 3,
    pinned = true,
    items = {
      {
        id = "files",
        icon = "󰙅",
        label = "Files",
        command = "Neotree toggle reveal",
        active = function()
          for _, winid in ipairs(vim.api.nvim_list_wins()) do
            local bufnr = vim.api.nvim_win_get_buf(winid)
            if vim.bo[bufnr].filetype == "neo-tree" then
              return true
            end
          end
          return false
        end,
      },
      {
        id = "search",
        icon = "󰱼",
        label = "Search",
        command = "Telescope find_files",
        post_action = false,
        focus_filetype = "TelescopePrompt",
      },
      {
        id = "terminal",
        icon = "",
        label = "Terminal",
        command = "ToggleTerm",
      },
    },
  },
}

Commands

• :ActivityBarOpen
• :ActivityBarClose
• :ActivityBarToggle
• :ActivityBarRefresh
• :ActivityBarPin
• :ActivityBarPosition left
• :ActivityBarPosition right
• :ActivityBarTogglePosition

Options

• position: "left" or "right", default "left"
• width: bar width, default 6
• item_height: height allocated to each item, default 3
• auto_open: open the bar on startup, default true
• mouse: enable mouse support, default true
• pinned: keep the bar at the configured edge, default true
• spacing: blank lines between items, default 1
• items: list of launcher items
• highlights: highlight group names
• highlight_definitions: default highlight definitions

Item Fields

• id: stable item id
• icon: text rendered in the bar
• label: human-readable name
• command: Ex command string
• callback: Lua function
• enabled: boolean or function
• active: function returning true when the item should be highlighted
• post_action: set to false to skip layout pinning after the item runs
• focus_filetype: filetype to focus after the item runs
• focus_delay: milliseconds to wait before applying focus_filetype

Only give active to toggle-like items. Omit it for one-shot commands such as pickers, package managers, or diagnostics lists when they should not look selected.

Use post_action = false and focus_filetype = "TelescopePrompt" for focus-sensitive floating UIs such as Telescope.

Highlights

• ActivityBarNormal: base item background
• ActivityBarActive: active item background
• ActivityBarDisabled: disabled item background

Override highlight_definitions.active to change the active background color.

opts = {
  highlight_definitions = {
    active = { bg = "#3a3a3a" },
  },
}

AI-Assisted Configuration Guide

This plugin intentionally keeps integrations outside the plugin. That makes it easy to configure with an AI assistant because each item can be described as:

1. What command should run?
2. Is it a toggle-like UI?
3. How can Neovim detect whether it is currently visible?
4. Does it open a focus-sensitive floating UI?

Prompt: Add A New Tool Button

I am configuring activitybar.nvim for Neovim.

Add an item for <plugin or command name>.
The item should run this command: <command>.
Use this icon if it is reasonable: <icon>.

If this item opens a persistent toggle window, add an active function that
checks the visible window filetype or buffer variable.
If this item opens a floating picker or prompt, set post_action = false and
focus the prompt filetype if needed.

Return only the Lua item table and explain where to paste it.

Prompt: Fix A Focus Or Layout Problem

I clicked an activitybar.nvim item and the focus/layout became wrong.

Here is the item config:
<paste item table>

Here is what should happen:
<describe expected behavior>

Please explain whether this should use active, post_action = false,
focus_filetype, or a callback. Return a corrected item table.

Prompt: Detect Whether An Item Is Active

I need an active function for activitybar.nvim.

The UI I want to detect is <Neo-tree/Trouble/toggleterm/etc>.
Please write a small Lua active function that loops over visible windows and
checks filetype, buftype, or buffer variables. Keep it defensive and avoid
throwing errors.

Design Notes

Neovim cannot scale the font size of one buffer independently in terminal UI. Use width and item_height to increase the clickable area and visual weight of each icon.

The bar is intentionally not a full layout manager. It tries to keep itself at the configured edge, but plugin UIs such as file explorers, pickers, terminals, and AI panels still own their own windows.

License

MIT