Build rich, interactive Neovim plugin UIs with React-like components, hooks, and a fiber-based reconciler.
Instead of juggling nvim_buf_set_lines, highlight namespaces, and manual redraws, you describe your UI as functional components. ascii-ui.nvim renders it to a floating window or stdout, diffs the tree, and updates only what changed.
Building even a simple interactive UI in Neovim today means wiring together low-level APIs:
- Create a buffer, set lines, add highlights
- Track window IDs and buffer numbers
- Re-render manually every time state changes
- Handle focus, keymaps, and cleanup yourself
A counter that should take a few lines quickly becomes a tangle of buffer and window management.
ascii-ui.nvim brings a React-like model to Neovim plugin development:
local ui = require("ascii-ui")
local Paragraph = ui.components.Paragraph
local Button = ui.components.Button
local useState = ui.hooks.useState
local Counter = ui.createComponent("Counter", function()
local count, setCount = useState(0)
return {
Paragraph({ content = "Count: " .. count }),
Button({
label = "+1",
on_press = function()
setCount(count + 1)
end,
}),
}
end)
ui.mount(Counter)That is the whole component. State, rendering, diffing, and input are handled for you.
Built-in Neovim packages:
git clone https://github.com/ascii-ui/ascii-ui.nvim.git \
~/.config/nvim/pack/plugins/start/ascii-ui.nvimreturn {
"ascii-ui/ascii-ui.nvim",
opts = {},
}lux:
lux install ascii-uiluarocks install ascii-uiSave this as lua/my-counter.lua (or paste it into your config):
local ui = require("ascii-ui")
local Paragraph = ui.components.Paragraph
local Button = ui.components.Button
local useState = ui.hooks.useState
return ui.createComponent("Counter", function()
local count, setCount = useState(0)
return {
Paragraph({ content = "Count: " .. count }),
Button({
label = "+1",
on_press = function()
setCount(count + 1)
end,
}),
}
end)From anywhere in Neovim:
local Counter = require("my-counter")
require("ascii-ui").mount(Counter)A floating window opens, and pressing the button updates the count instantly.
The counter above renders in a floating window like this:
╭──────────────╮
│ Count: 0 │
│ [ +1 ] │
╰──────────────╯
Press <CR> on the button and the count updates without you touching the buffer API.
- React-like component model — functional components with props, composition, and reconciliation
- Hooks —
useState,useEffect,useReducer,useInterval,useTimeout,useConfig - Built-in components — Button, Input, Select, Slider, Checkbox, Tree, Box, Paragraph
- Layout primitives —
RowandColumnfor horizontal and vertical arrangement - Fiber-based reconciler — efficient tree diffing and minimal re-renders
- Multiple viewports — Neovim floating windows (default), terminal stdout, or custom
- Live reload — instant feedback during development with
make debug - ANSI truecolor — full color support via the
Colorclass and segment colors - Zero dependencies — pure Lua, runs on Neovim's embedded Lua 5.1
![]() |
![]() |
![]() |
![]() |
From file explorers and dashboards to animated clocks and train station boards — if it can be drawn with text, ascii-ui.nvim can render it.
See the examples/ directory for more:
| Example | What it shows |
|---|---|
analog-clock.lua |
Animated clock with useInterval + Color |
file_structure.lua |
Collapsible tree with the Tree component |
train-station-board.lua |
Scrolling text animation |
animated-bar-chart.lua |
Dynamic bar chart with state |
metro-map.lua |
ASCII art with colored segments |
text-input.lua |
Form with Input component |
select-dropdown.lua |
Selectable list with Select |
| Guide | Description |
|---|---|
| Components | Full reference for all built-in components with props and examples |
| Hooks | State management, side effects, timers — the full hooks API |
| Layout | Row and Column for arranging components |
| Advanced | Custom components, viewports, low-level rendering (Segment, BufferLine, Buffer) |
| API Reference | Full generated documentation |
require("ascii-ui").setup({
log_level = "INFO",
characters = {
top_left = "╭", top_right = "╮",
bottom_left = "╰", bottom_right = "╯",
horizontal = "─", vertical = "│",
left_tree = "├", thumb = "●",
whitespace = " ", right_triangule = "▸", down_triangule = "▾",
},
keymaps = {
quit = "q",
select = "<CR>",
},
})ascii-ui.nvim ships a live-reload debug mode. Save any .lua file and the running Neovim instance automatically tears down the current UI, unloads all modules, and re-executes your script.
Requirements: nvim on $PATH.
- Write your component in any
.luafile and return it:
-- lua/myplugin/MyComp.lua
local ui = require("ascii-ui")
local useState = ui.hooks.useState
local Paragraph = ui.components.Paragraph
local Button = ui.components.Button
return ui.createComponent("MyComp", function()
local count, setCount = useState(0)
return {
Paragraph({ content = "count: " .. count }),
Button({ label = "+1", on_press = function() setCount(count + 1) end }),
}
end)- Create a
debug.luain the repository root:
require("ascii-ui").debug("lua/myplugin/MyComp.lua")- Start the session:
make debugEvery save reloads the UI automatically. Errors are shown as notifications without crashing the session.
Works from any running Neovim session too:
:lua require("ascii-ui").debug("lua/myplugin/MyComp.lua")
Use ascii-ui.nvim with AI coding agents (OpenCode, Claude, etc.) by installing the official agent skill:
npx skills add ascii-ui/agent-skills --skill ascii-ui-nvimThe skill gives agents a mental model of the component system, hooks, and common patterns so they can generate correct ascii-ui code without hallucinating APIs. Source: ascii-ui/agent-skills.
ascii-ui.nvim is a declarative UI framework for Neovim. Instead of building UI by imperatively managing windows and buffers, you describe what the UI should look like with functional components and hooks — and the fiber-based reconciler handles diffing, state updates, and re-renders behind the scenes.
- nui.nvim — imperative UI primitives for Neovim
See CONTRIBUTING.md for development setup, commit conventions, and how to add components or hooks.
MIT




