guihua.lua
A Lua GUI and utility library for creating floating windows and UI components in Neovim plugins.
What is guihua.lua?
Guihua is a GUI and utility library written in Lua specifically for Neovim plugin developers. It provides components like floating windows, ListView, TextView, and a fuzzy finder to help build interactive user interfaces within Neovim. It solves the problem of creating custom, responsive UIs for plugins without relying on external tools.
Neovim plugin developers who need to implement graphical interfaces, such as floating windows, list selectors, or preview panes, within their plugins.
Developers choose Guihua because it offers a dedicated, lightweight set of GUI tools tailored for Neovim, with built-in support for fuzzy finding, multigrid displays, and seamless integration with Neovim's native UI APIs.
Overview
A GUI library for Neovim plugin developers
Use Cases
Best For
- Building Neovim plugins with floating window interfaces
- Implementing fuzzy-searchable list selectors in plugins
- Creating custom preview panes for code or documentation
- Developing plugins that require external terminal or buffer displays
- Enhancing native Neovim UI components like vim.ui.input
- Adding interactive GUI elements to Neovim plugins without external dependencies
Not Ideal For
- Developers building plugins for Vim instead of Neovim, as it relies on Neovim-specific features like multigrid
- Projects requiring drag-and-drop or complex graphical interfaces beyond floating windows and basic components
- Teams seeking out-of-the-box, fully styled UI components without custom Lua coding and configuration
- Large-scale applications needing extensive documentation and broad community support, given its niche focus
Pros & Cons
Pros
Includes a modified wrapper for fzy, providing fast, fuzzy-search capabilities within lists, as demonstrated in the ListView integration with real-time filtering.
Leverages Neovim's multigrid feature for external buffers/terminals and patches vim.ui.input/select to enhance native UI interactions, ensuring tight ecosystem compatibility.
Offers ready-to-use TextView, ListView, and Preview components, simplifying the creation of rich interfaces without building from scratch, as shown in the test files.
Provides default keyboard mappings and icon sets that can be easily overridden via tbl_deep_extend(), allowing flexible adaptation to plugin needs.
Cons
Relies heavily on test files for usage examples, lacking comprehensive guides or tutorials, which can hinder onboarding and troubleshooting for developers.
Requires building fzy with `make` for FFI support, adding an extra step and potential cross-platform compatibility issues, as noted in the installation instructions.
Depends on external libraries like middleclass and fzy-lua-native, introducing maintenance risks and limiting its applicability outside the Neovim Lua plugin context.
Frequently Asked Questions
Related Projects
plenary.nvimplenary: full; complete; entire; absolute; unqualified. All the lua functions I don't want to write twice.
nui.nvimUI Component Library for Neovim.
lazydev.nvimFaster LuaLS setup for Neovim
sqlite.luaSQLite LuaJIT binding with a very simple api.
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.