goolord/alpha-nvim: a programmable Neovim greeter built on a data-oriented UI API

The problem alpha-nvim solves, and who it is for

Neovim opens on an empty buffer. Most people either live with that or install a dashboard plugin that draws a logo, a few shortcut keys and a recent-files list. alpha-nvim sits in that second category, but it is positioned differently from a fixed dashboard: the README describes it as "a fast and fully programmable greeter for neovim" and, in the elevator pitch, as "really a general purpose neovim ui library with some conveniences for writing a greeter ui." That sentence is the whole design thesis. The greeter is the demo; the UI library is the product.

The intended reader is someone who already edits their Neovim config in Lua and wants the startup screen to reflect their own keybindings and workflow. The README warns that the bundled themes "make some assumptions about your default keybindings," which is the polite way of saying the default buttons are placeholders you are expected to replace. If you never open a Lua file, the default output will look fine and do nothing useful.

It is not for people who want a dashboard configured through a settings table of on/off flags. alpha-nvim's configuration surface is the same as its rendering surface: you write the data the renderer consumes.

How alpha-nvim works: themes as data, not as code

The mechanism is a single setup entry point. Every documented example ends in the same call, require'alpha'.setup(...), and the argument is a config table taken from a theme module. There are three bundled themes: alpha.themes.startify, alpha.themes.dashboard and alpha.themes.theta. Each one exports a .config field, and that field is what you hand to setup.

The README says themes "are expressed entirely as data, which is what makes alpha fully programmable." In practice this means a theme is a Lua table describing what to draw, and customization is table surgery: you take the theme's config, modify the fields you care about, and pass the result to setup. That is why the README points at :h alpha-example for button customization rather than documenting a fixed set of options. The help file is the API reference; the README is the quick start.

The three themes differ in scope. startify is the vim-startify-style layout and supports file icons. dashboard is the dashboard-nvim-style layout. theta is the heaviest of the three and is the only one whose documented example lists nvim-lua/plenary.nvim as a dependency alongside the icon provider, so it pulls in more than the other two.

File icons are enabled by default in the theta and startify themes, and the default provider is mini, meaning nvim-mini/mini.icons. The README notes that if a provider is not loaded while icons are enabled, alpha will try another provider, so a missing icons plugin degrades rather than breaks. You can force nvim-tree/nvim-web-devicons by setting startify.file_icons.provider = "devicons" on the theme table before calling setup.

Installing alpha-nvim and running a first theme

There are no releases to pin, so installation means a plugin manager pulling the default branch. The README gives examples for lazy.nvim, packer and paq; the lazy.nvim path is the one reproduced here. For the startify theme, the dependency is the mini.icons provider, and the config function calls setup with the theme's config table unchanged.

{
    'goolord/alpha-nvim',
    dependencies = { 'nvim-mini/mini.icons' },
    config = function ()
        require'alpha'.setup(require'alpha.themes.startify'.config)
    end
};

After restarting Neovim with no file arguments, you should see the startify-style greeter instead of an empty buffer. The buttons it draws are the theme defaults, and the README states those defaults assume certain keybindings.

The dashboard theme needs no icon dependency in its documented example. The config function is the same shape, with a different theme module:

{
    'goolord/alpha-nvim',
    config = function ()
        require'alpha'.setup(require'alpha.themes.dashboard'.config)
    end
};

The theta theme is the one that adds plenary.nvim, and its dependency list is the place to look if you want recent files or anything that reads the filesystem:

{
    'goolord/alpha-nvim',
    dependencies = {
        'nvim-mini/mini.icons',
        'nvim-lua/plenary.nvim'
    },
    config = function ()
        require'alpha'.setup(require'alpha.themes.theta'.config)
    end
};

To switch icon providers on startify, assign the provider field on the theme table before setup, as the README's devicons example does:

local startify = require("alpha.themes.startify")
-- available: devicons, mini, default is mini
startify.file_icons.provider = "devicons"
require("alpha").setup(startify.config)

The comment in that snippet is the README's own, and it is the only place the valid provider names are listed. Past this point, button customization is documented in :h alpha-example rather than in the README.

Where alpha-nvim stops being the right tool

Sessions are the clearest gap. The README does not implement session restore; it points elsewhere, listing Shatur/neovim-session-manager and the built-in :mks command. If you want a dashboard that lists and reopens your previous sessions out of the box, alpha-nvim is the wrong starting point and you will be assembling that behavior yourself.

The second limitation is documentation depth. The README covers installation and theme selection well, and then hands off to a help file for anything beyond that. There is no documented catalogue of every field a theme config accepts. That is a direct consequence of the data-oriented design: the config is an open table, so the API surface is whatever the theme modules contain, and the README does not enumerate it. Expect to read the theme source in lua/ or the help file when you want to change something the defaults do not cover.

The performance claim deserves the same caution. The README says alpha is "the fastest greeter I've benchmarked" and includes profiling results, but the note under the image states the measurement is "only config! doesn't measure drawing, some startup plugins won't measure drawing either," and the benchmark was run with lewis6991/impatient.nvim. That is a config-load measurement, not a frame-time measurement, and it is the author's own benchmark rather than an independent one. Treat the speed claim as a design goal with a caveat attached, not as a settled comparison.

Finally, the repository has no releases. The last push was on 2026-08-25, so the project is not abandoned, but there is no version tag to pin against and no changelog to read before upgrading.

alpha-nvim compared with dashboard-nvim and vim-startify

The README credits both projects directly: dashboard-nvim as "inspiration, code reference" and vim-startify as "inspiration." The two bundled themes are named after them, which tells you what the visual output is aiming at.

The difference in approach is where the configuration lives. vim-startify is a Vim plugin configured through Vimscript variables, so the layout is what the plugin decides and you adjust it through exposed settings. dashboard-nvim is a Neovim plugin in the same visual territory. alpha-nvim takes the position that the theme itself is data, so a theme can be rewritten rather than configured, and the README frames the result as a general UI library that happens to ship three greeters.

That difference cuts both ways. Rewriting a theme is more work than toggling a setting, and it requires comfort with Lua tables. In exchange, you are not limited to the options the theme author anticipated. If your greeter needs a custom section that reads from a file or runs a command, the data-oriented API is the reason that is possible without patching the plugin.

The README also links a discussion thread for sharing custom themes, which is where the community's layouts live rather than in the repository itself.

Maintenance, licence and upgrade cost

alpha-nvim is MIT licensed, and the repository contains a LICENSE file at the top level alongside CONTRIBUTING.md and a stylua.toml formatting config. MIT is permissive: it allows reuse and modification with the licence and copyright notice retained. That is a statement about the licence text, not legal advice for your situation.

The repository is not archived and the last push was on 2026-08-25, roughly a month before this writing. There are no retrieved releases, so upgrades happen by pulling the default branch. Without tags, you cannot pin a version and you cannot read a changelog to see what moved between two commits. In practice that means an upgrade is a git pull plus a restart, and if a theme's config table changed shape, the failure will show up as a Lua error at startup rather than as a documented breaking change.

For a plugin this small and this stable in scope, that cost is low. The real upgrade risk is the dependency pair: mini.icons and, for theta, plenary.nvim. Those move independently of alpha-nvim, and the README's fallback behavior for a missing icon provider only covers the icons case.

Editorial conclusion

Adopt alpha-nvim if you want a greeter whose layout you can rewrite in Lua without forking a theme, and if you are willing to read :h alpha-example to learn the API. Do not adopt it if you want a dashboard that ships with session management or a graphical settings UI; the README points session users at Shatur/neovim-session-manager and :mks instead. Before committing, verify two things: that your plugin manager loads the icon provider your theme expects (mini.icons is the default, nvim-web-devicons is the alternative), and that your Neovim version accepts the config tables you copy from the README, since the startify examples and the theta examples are not identical.

Frequently asked questions

Official sources

1. goolord/alpha-nvim on GitHub
2. Issues
3. License: MIT
4. README