# alpha-nvim: the theta examples that set up dashboard, and a speed claim with no numbers

> alpha-nvim is a Lua greeter for Neovim that ships startify, dashboard and theta themes and asks for one of three plugin managers. Its own examples contradict each other in two places: the theta packer and paq blocks call the dashboard theme, and the ranking claim under Elevator pitch arrives without a table, a version or a machine.

**goolord/alpha-nvim** — a lua powered greeter like vim-startify / dashboard-nvim

- Repository: https://github.com/goolord/alpha-nvim
- Stars: 2,407 · Forks: 130
- Language: Lua
- License: MIT
- Published: 2026-09-28 · Updated: 2026-09-28 · Language: en
- Canonical page: https://hysenlabs.com/projects/goolord-alpha-nvim

## The theta packer and paq blocks call the dashboard theme

Three themes ship in this plugin, startify, dashboard and theta, and each one gets its own pair of code blocks, nine in all. The lazy.nvim block under the theta heading calls `require'alpha.themes.theta'.config`. The packer block directly beneath it calls `require'alpha.themes.dashboard'.config`:

```lua
use {
    'goolord/alpha-nvim',
    requires = {
        'nvim-mini/mini.icons',
        'nvim-lua/plenary.nvim'
    },
    config = function ()
        require'alpha'.setup(require'alpha.themes.dashboard'.config)
    end
}
```

The paq block under the same heading makes the same substitution. Take either one and you get the dashboard greeter carrying theta's dependency list, plenary.nvim included, while the two dashboard blocks that follow ask for no extra plugin at all. Nothing fails loudly. You get a working greeter, a different set of buttons than the ones you were reading about, and a plenary install you did not ask for.

## The ranking claim arrives without a table, and the profiling note excludes drawing

The Elevator pitch section says alpha is the fastest greeter the author has benchmarked, and adds in the same sentence that this is why he daily drives it. Under it, a Profiling Results heading carries two bullets and no numbers. The first names the harness, lewis6991/impatient.nvim. The second says only config is measured and does not measure drawing, and adds that some startup plugins will not measure drawing either. So the comparison is narrowed to the config stage, and the stage where a greeter spends time putting glyphs on screen is excluded from the one line that claims a ranking. Both sentences are written in the first person, which leaves a reader choosing between greeters with no table, no Neovim version, no commit and no machine to reproduce it on.

## The dashboard examples drop the icon dependency its own paq block keeps

Icon support is optional per manager in a way the three themes do not agree on. The startify blocks declare `nvim-mini/mini.icons` as a dependency under lazy.nvim, under packer and in the paq list. The theta blocks add `nvim-lua/plenary.nvim` on top. The dashboard blocks are the odd ones out: the lazy.nvim spec has no dependencies key at all, the packer form has no requires key, and the paq form still lists mini.icons. The devicons example at the bottom of the README shows the intended swap by leaving the line in place as a comment, `-- dependencies = { 'nvim-mini/mini.icons' },`, and putting nvim-web-devicons in its place. Follow the dashboard lazy.nvim block as written and no icon plugin gets installed, even though icons are on by default.

## A missing icon provider falls back to another one instead of reporting anything

Two providers are supported, nvim-web-devicons and mini.icons, and the mini one is the default. The devicons example sets it by reaching into the required theme module before setup, with `startify.file_icons.provider = "devicons"`, and two comments above that line state the rule: available are devicons and mini, default is mini, and if the chosen provider is not loaded while icons are enabled it will try to use another provider. That fallback is the part to weigh. A configuration error in the dependency list does not surface as a missing provider or an error message; the greeter renders with a different icon set and nothing says so. If you want to know which provider actually ran, the setting you typed is not evidence, because the value in the file is not necessarily the value on screen.

## Sessions are pointed elsewhere, twice, and neither pointer is part of alpha

A greeter that shows you recent files is only half of what people use one for, and this project says plainly that the other half is elsewhere. One line under the theta examples reads if you want sessions, see, and then gives two references: the plugin Shatur/neovim-session-manager and the Neovim command `:h :mks`. So restoring a session is not something alpha does, and neither reference is wired into the setup call. For a reader comparing this with dashboard-nvim, the practical question is whether the thing you want is the greeter, the session store, or both, because the two are installed and configured separately here.

## No releases and no lockfile: ten entries at the root and main as the only reference

The repository publishes no GitHub releases, so there is no version number to depend on and no tag to pin. The default branch is main, the last push is dated 2026-08-25, and the licence is MIT. The root holds ten entries: `.editorconfig`, `.github/`, `.gitignore`, `CONTRIBUTING.md`, `LICENSE`, `README.md`, `debug/`, `doc/`, `lua/` and `stylua.toml`. There is no manifest, no lockfile and no build step in that list; the Lua code sits under `lua/` and the help pages the README points at sit under `doc/`, with `stylua.toml` recording how the code is formatted. A plugin manager spec naming the repository therefore follows main as it moves, which is the normal arrangement for a Neovim plugin and also the reason a rollback is a commit hash rather than a version.

## Themes are passed as data, so a theme is edited by mutating the module

The setup call in every one of the nine examples has the same shape: take a theme's config value and hand it to `alpha`. `require'alpha'.setup(require'alpha.themes.startify'.config)` is the whole contract, and the Elevator pitch section ties it to the design claim that themes are expressed entirely as data, which is what the project calls fully programmable. The devicons example is the one place where that shows up as code, because it does not redefine anything: it requires the theme module, changes one field on it, and passes the module's config along. That is the extension pattern the file actually demonstrates, and it is narrower than the claim, since it edits an existing theme object rather than building a new one from nothing.

## theta assumes your keybindings, and one help tag covers the buttons

One line warns that the theta theme makes some assumptions about your default keybindings, and the fix is a reference rather than an option: to customize the buttons, see `:h alpha-example`. That help tag is the only documentation offered for button layout in the whole file. Nothing in the nine examples sets a key, none of them names a mapping, and there is no table anywhere showing which keys the theme expects to find already bound. A reader who has just replaced a dashboard has to open the runtime help to find out what the greeter will press. The README does not say which keymaps theta claims, only that it claims some, and it does not say what happens to a button whose binding is taken.

## Conclusion

Pick alpha-nvim if you want a greeter you can edit as data rather than a finished dashboard, and read the three themes as a family of config values rather than as three independent plugins. Before you copy an example, check which theme the block actually calls, since two of the nine blocks in this file set up dashboard under a theta heading. If your decision depends on speed, measure it yourself with the drawing stage included, because the ranking in this file has no table behind it. And pin your install to a commit, not a tag: the project publishes no releases, so a plugin manager pointed at main is your only version.

## FAQ

### how to install alpha nvim

Use a plugin manager. With lazy.nvim the spec is `{ 'goolord/alpha-nvim', dependencies = { 'nvim-mini/mini.icons' }, config = function () require'alpha'.setup(require'alpha.themes.startify'.config) end };`, and equivalent packer and paq forms are given for each of the startify, dashboard and theta themes.

### alpha nvim alternative

The project names its own two: dashboard-nvim as inspiration and code reference, and vim-startify as inspiration. Session restore is not part of alpha, and the file points at Shatur/neovim-session-manager and `:h :mks` instead.

### What is alpha-nvim built for?

It is a Lua powered greeter for Neovim in the shape of vim-startify or dashboard-nvim. Its own description calls it a general purpose Neovim ui library with conveniences for writing a greeter ui.

### How many themes does alpha-nvim ship?

Three, named startify, dashboard and theta. Each theme is handed to setup as a config value, for example `require'alpha'.setup(require'alpha.themes.startify'.config)`.

### Which file icon providers do alpha-nvim themes accept?

The theta and startify themes support file icons, enabled by default, with the mini provider used by default. nvim-web-devicons and nvim-mini/mini.icons are the two supported providers, and if the chosen provider is not loaded it tries another.

### Does alpha-nvim restore sessions on its own?

No. The file points to Shatur/neovim-session-manager and to the `:h :mks` command for that, and neither is wired into the alpha setup call.

## Sources

- [goolord/alpha-nvim on GitHub](https://github.com/goolord/alpha-nvim)
- [Issues](https://github.com/goolord/alpha-nvim/issues)
- [License: MIT](https://github.com/goolord/alpha-nvim/blob/main/LICENSE)
- [README](https://github.com/goolord/alpha-nvim/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/goolord-alpha-nvim