portal.nvim
A Neovim plugin that enhances navigation through location lists (jumplist, changelist, quickfix) using labelled floating windows called portals.
What is portal.nvim?
Portal.nvim is a Neovim plugin that reimagines navigation through location lists like the jumplist, changelist, and quickfix list. Instead of cycling through entries with commands like `<c-o>` and `<c-i>`, it presents locations as labelled floating windows (portals) that users can jump to directly. It solves the problem of disorienting and inefficient list traversal by providing visual context and instant access.
Neovim users who frequently work with location lists, such as developers navigating codebases, debugging with quickfix, or managing complex edit histories. It's especially valuable for those seeking more control and visibility over their navigation flow.
Developers choose Portal.nvim because it transforms a fundamental but often cumbersome aspect of Vim-style editing. Its visual portals reduce cognitive load, its extensible query system allows for precise navigation, and its seamless integration with Neovim's built-in lists and popular plugins makes it a powerful upgrade over default motions.
Overview
Neovim plugin for improved location list navigation
Use Cases
Best For
- Quickly jumping to specific locations in a long jumplist history
- Filtering quickfix results to show only entries in modified buffers
- Combining jumplist and grapple tag navigation in a single search
- Creating custom navigation workflows with predicate-based filters
- Enhancing code exploration with visual context for jump destinations
- Replacing `<c-o>`/`<c-i>` with a more intuitive and direct interface
Not Ideal For
- Neovim users who prefer minimal, keyboard-only navigation with default commands like `<c-o>` and `<c-i>` without floating windows
- Developers working in terminal environments with poor floating window support or over SSH with limited GUI capabilities
- Teams relying on custom location lists not covered by built-in queries and lacking Lua expertise to implement iterators
- Workflows needing automatic, context-aware navigation without manual portal invocation for every jump
Pros & Cons
Pros
Replaces sequential list traversal with labelled floating windows that show context snippets, allowing direct jumps and reducing disorientation from commands like `<c-i>`.
Supports custom filters, slots, and a declarative iterator API for precise control over searches, enabling composable queries across multiple location lists.
Integrates with Grapple and Harpoon out-of-the-box, extending navigation to tagged files and marks without extra bridging code.
Allows combining built-in lists like jumplist and quickfix into a single search, streamlining complex debugging or code exploration workflows.
Cons
Requires manual keybind setup and Lua knowledge for advanced features like custom filters, unlike plug-and-play navigation plugins.
Depends on Neovim >= 0.8 and optionally 0.9 for features like floating window titles, limiting compatibility with older setups.
The iterator API and custom query logic involve complex Lua programming, making it inaccessible for users unfamiliar with Neovim's internals.
Without customization, basic portal usage might not offer significant advantages over native motions for simple jumplist navigation.
Frequently Asked Questions
Related Projects
leap.nvimNeovim's answer to the mouse 🦘
flash.nvimNavigate your code with search labels, enhanced character motions and Treesitter integration
lightspeed.nvimdeprecated in favor of leap.nvim
precognition.nvim💭👀precognition.nvim - Precognition uses virtual text and gutter signs to show available motions.
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.