LuxDash

A highly customizable Neovim dashboard plugin with a beautiful logo, recent files, git status, and quick actions.

Features

• Customizable Logo: Display ASCII art with gradient colors
• Recent Files: Quick access to recently opened files with numeric keybindings (1-9)
• Git Integration: Real-time git status, branch info, and commit details
• Quick Actions: Configurable menu for common operations
• Floating Window: Beautiful floating dashboard with customizable borders
• Modular Sections: Easy to add, remove, or customize sections
• Performance: Efficient caching and rendering system

Requirements

• Neovim >= 0.9.0
• Git (for git status section)
• Optional: Telescope or FzfLua for enhanced file navigation

Installation

lazy.nvim

{
  'your-username/nvim-luxdash',
  dependencies = {
    'nvim-telescope/telescope.nvim', -- Optional: for enhanced file navigation
  },
  config = function()
    require('luxdash').setup()
  end,
  keys = {
    { '<leader>d', '<cmd>LuxDash<cr>', desc = 'Toggle LuxDash' },
  },
}

packer.nvim

use {
  'your-username/nvim-luxdash',
  requires = {
    'nvim-telescope/telescope.nvim', -- Optional
  },
  config = function()
    require('luxdash').setup()
  end
}

vim-plug

Plug 'nvim-telescope/telescope.nvim'  " Optional
Plug 'your-username/nvim-luxdash'

lua << EOF
require('luxdash').setup()
EOF

Basic Usage

Commands

• :LuxDash - Toggle the dashboard

Default Keybindings (in dashboard)

• 1-9 - Open recent file by number
• q - Close dashboard
• Menu action keybindings as configured

Lua API

-- Open dashboard
require('luxdash').open()

-- Toggle dashboard
require('luxdash').toggle()

Configuration

Default Configuration

require('luxdash').setup({
  -- Dashboard name
  name = 'LuxDash',

  -- Logo (ASCII art using Braille characters)
  logo = {
    '',
    '��D���...',  -- Your custom ASCII art
    '',
  },

  -- Logo gradient colors (hex format)
  logo_color = {
    -- Auto-adapt to current theme (default: true)
    auto_theme = true,

    -- Or manually specify colors:
    -- row_gradient = {
    --   start = '#ff7801',  -- Top color (orange)
    --   bottom = '#db2dee'  -- Bottom color (purple)
    -- }
  },

  -- Section configuration
  sections = {
    -- Main section (logo area)
    main = {
      type = 'logo',
      config = {
        alignment = {
          horizontal = 'center',
          vertical = 'center'
        }
      }
    },

    -- Bottom sections (horizontal layout)
    bottom = {
      {
        id = 'actions',
        type = 'menu',
        title = '� Actions',
        config = {
          show_title = true,
          show_underline = true,
          padding = { left = 2, right = 2 },
          menu_items = { 'newfile', 'backtrack', 'fzf', 'closelux' }
        }
      },
      {
        id = 'recent_files',
        type = 'recent_files',
        title = '=� Recent Files',
        config = {
          show_title = true,
          show_underline = true,
          padding = { left = 2, right = 2 },
          max_files = 8
        }
      },
      {
        id = 'git_status',
        type = 'git_status',
        title = '<? Git Status',
        config = {
          show_title = true,
          show_underline = true,
          padding = { left = 2, right = 2 }
        }
      }
    }
  },

  -- Layout configuration
  layout_config = {
    main_height_ratio = 0.8,  -- Main section takes 80% of height
    bottom_sections_equal_width = true,
    section_spacing = 4
  },

  -- Floating window settings
  float = {
    width = 0.9,   -- 90% of editor width
    height = 0.9,  -- 90% of editor height
    border = 'rounded',  -- 'none', 'single', 'double', 'rounded', 'solid', 'shadow'
    title = ' LuxDash ',
    title_pos = 'center',  -- 'left', 'center', 'right'
    hide_buffer = false
  },

  -- Dashboard padding
  padding = {
    left = 2,
    right = 2,
    top = 1,
    bottom = 1
  }
})

Customization

Custom Logo

You can use any ASCII art. Here's a simple example:

require('luxdash').setup({
  logo = {
    '',
    '  ��W     ��W   ��W��W  ��W',
    '  ��Q     ��Q   ��QZ��W��T]',
    '  ��Q     ��Q   ��Q Z���T] ',
    '  ��Q     ��Q   ��Q ��T��W ',
    '  �������WZ������T]��T] ��W',
    '  ZPPPPPP] ZPPPPP] ZP]  ZP]',
    '',
  },
  logo_color = {
    -- Option 1: Auto-adapt to your theme (recommended)
    auto_theme = true,

    -- Option 2: Manual gradient colors
    -- row_gradient = {
    --   start = '#3b82f6',  -- Blue
    --   bottom = '#8b5cf6'  -- Purple
    -- }

    -- Option 3: Regular gradient (non-row)
    -- gradient = {
    --   top = '#3b82f6',
    --   bottom = '#8b5cf6'
    -- }

    -- Option 4: Single color preset
    -- preset = 'blue'  -- 'blue', 'green', 'red', 'yellow', 'purple', 'orange', 'pink', 'cyan'
  }
})

Logo Color Options

LuxDash provides several ways to color your logo:

Auto Theme (Default)

The logo automatically adapts to your current Neovim colorscheme:

logo_color = {
  auto_theme = true  -- Extracts colors from your theme
}

This is the recommended option as it ensures your dashboard always matches your theme. The logo will automatically update when you change colorschemes!

Manual Gradients

For precise control, specify exact colors:

logo_color = {
  row_gradient = {
    start = '#ff7801',  -- Top color
    bottom = '#db2dee'  -- Bottom color
  }
}

Color Presets

Use built-in color presets:

logo_color = {
  preset = 'blue'  -- 'blue', 'green', 'red', 'yellow', 'purple', 'orange', 'pink', 'cyan'
}

Custom Menu Actions

Available built-in menu actions:

• newfile - Create new file
• new - New empty buffer
• backtrack - Go back to previous buffer
• fzf - Open file finder (Telescope or FzfLua)
• recent - Browse recent files
• search - Search in files
• closelux - Close dashboard
• quit - Quit Neovim

Example custom menu:

sections = {
  bottom = {
    {
      type = 'menu',
      title = '�  Quick Actions',
      config = {
        menu_items = { 'newfile', 'fzf', 'search', 'quit' }
      }
    }
  }
}

Change Section Layout

Single Bottom Section (Full Width)

sections = {
  main = {
    type = 'logo',
  },
  bottom = {
    {
      type = 'recent_files',
      title = '=� Recent Files',
      config = {
        max_files = 10
      }
    }
  }
}

Two Sections Side-by-Side

sections = {
  main = {
    type = 'logo',
  },
  bottom = {
    {
      type = 'menu',
      title = '� Actions',
    },
    {
      type = 'recent_files',
      title = '=� Files',
    }
  }
}

Custom Colors

Customize highlight groups in your Neovim config:

vim.api.nvim_set_hl(0, 'LuxDashRecentFile', { fg = '#89b4fa' })
vim.api.nvim_set_hl(0, 'LuxDashRecentKey', { fg = '#f38ba8', bold = true })
vim.api.nvim_set_hl(0, 'LuxDashGitBranch', { fg = '#a6e3a1' })
vim.api.nvim_set_hl(0, 'LuxDashMenuKey', { fg = '#fab387', bold = true })

Available highlight groups:

• LuxDashLogo* - Logo gradient colors (auto-generated)
• LuxDashRecentFile - Recent file name
• LuxDashRecentIcon - Recent file icon
• LuxDashRecentKey - Recent file number key
• LuxDashGitBranch - Git branch name
• LuxDashGitSync - Git sync status
• LuxDashGitDiff - Git diff stats
• LuxDashGitCommit - Git commit info
• LuxDashMenuKey - Menu action key
• LuxDashMenuDesc - Menu action description
• LuxDashTitle - Section titles
• LuxDashSubSeparator - Section separator

Alignment Options

You can customize alignment for each section:

{
  type = 'recent_files',
  title = '=� Recent Files',
  config = {
    alignment = {
      title_horizontal = 'center',    -- 'left', 'center', 'right'
      content_horizontal = 'left',     -- 'left', 'center', 'right'
      vertical = 'top'                 -- 'top', 'center', 'bottom'
    }
  }
}

Tips and Tricks

Open Dashboard on Startup

vim.api.nvim_create_autocmd('VimEnter', {
  callback = function()
    -- Only open if no file was specified
    if vim.fn.argc() == 0 then
      require('luxdash').open()
    end
  end
})

Custom Keybinding

vim.keymap.set('n', '<leader>h', '<cmd>LuxDash<cr>', { desc = 'Open Dashboard' })

Auto-close on File Open

The dashboard automatically closes when you open a recent file using the number keys.

Performance

LuxDash is designed for performance:

• Caching: Layout, colors, and sections are cached
• Lazy Loading: Sections are loaded only when needed
• Efficient Rendering: Optimized highlight and buffer operations
• Debouncing: Window resize events are debounced

Troubleshooting

Dashboard doesn't show

Make sure you call setup() in your config:

require('luxdash').setup()

Git status not showing

Ensure you're in a git repository and git is installed:

git --version

Recent files not appearing

Recent files are filtered to only show files in the current working directory. Change directory with :cd if needed.

File icons not displaying

LuxDash uses built-in icons. Ensure your terminal and font support Nerd Fonts or Unicode characters.

Architecture

LuxDash is built with a modular architecture:

lua/luxdash/
�� core/          # Core rendering and caching
�� sections/      # Section implementations (logo, menu, recent files, git)
�� rendering/     # Rendering utilities and alignment
�� ui/            # UI components (floating window, buffer manager)
�� utils/         # Utility functions
�� menu/          # Menu action handlers

Contributing

Contributions are welcome! Areas for improvement:

• Additional section types
• Custom section API
• More menu actions
• Async git operations
• Unit tests
• Documentation improvements

License

MIT License - see LICENSE file for details

Acknowledgments

• Inspired by alpha-nvim and dashboard-nvim
• ASCII art logo created with love
• Built for the Neovim community

Support

If you encounter issues or have questions:

1. Check the Troubleshooting section
2. Search existing issues on GitHub
3. Create a new issue with details about your setup

---

Made with Lua for Neovim