csvview.nvim

Keep header rows visible while scrolling.

Auto-detection: The plugin identifies headers by looking for the first non-comment line and checking for Type Mismatch (text vs numeric data) or Length Deviation (significant length differences between the first row and data rows).

Manual Configuration: You can specify a fixed line number or disable headers entirely.

-- Auto-detect header with sticky behavior
{
  view = {
    header_lnum = true,
    sticky_header = {
      enabled = true,
      separator = "─",
    },
  },
}

-- Manual header line
{ view = { header_lnum = 1 } }

-- Disable header
{ view = { header_lnum = false } }

The plugin can automatically detect delimiters or use fixed/dynamic rules.

Auto-detection logic:

1. Checks ft (filetype) rules first.
2. If no match, tests fallbacks in order.
3. Scores delimiters based on field consistency across lines.
4. Selects the highest scoring delimiter.

Supported Delimiters: Supports single or multi-character delimiters (e.g., ||, ::), but does not support regular expressions (e.g., \s+).

-- Auto-detection configuration
{
  parser = {
    delimiter = {
      ft = {
        csv = ",",
        tsv = "\t",
      },
      fallbacks = {
        ",",
        "\t",
        ";",
        "|",
        ":",
        " ",
      },
    },
  },
}

Control the plugin using the following commands:

• :CsvViewEnable [options]: Enable CSV view with optional settings.
• :CsvViewDisable: Disable CSV view.
• :CsvViewToggle [options]: Toggle CSV view on or off.
• :CsvViewInfo: Display buffer statistics including delimiter, header, and dimensions.

Quick Start Examples:

" Enable with automatic delimiter detection
:CsvViewToggle

" Enable with specific settings
:CsvViewToggle delimiter=, display_mode=border header_lnum=1

Customize how columns are spaced and their minimum width within the view configuration block.

{
  view = {
    min_column_width = 5,  -- Minimum width for each column
    spacing = 2,           -- Space between columns
    -- spacing = { left = 1, right = 1 }, -- Virtual spaces around delimiters
  },
}

Exclude comment lines from the table view. You can define specific comment prefixes or treat a fixed number of leading lines as metadata/comments.

-- Ignore lines starting with #, //, or --
{ parser = { comments = { "#", "//", "--" } } }

-- Treat the first 2 lines as comments (metadata)
{ parser = { comment_lines = 2 } }

The view configuration object controls the visual presentation of the tabular data.

• min_column_width: (integer) Minimum width for a column.
• spacing: (integer|table) Spacing between columns. Use a table like { left = 1, right = 1 } for virtual spaces around delimiters.
• display_mode: (string) "highlight" (highlights delimiters) or "border" (uses │ as delimiters).
• header_lnum: (integer|false|true) Defines the header row. true enables auto-detection, an integer specifies a 1-based line number, and false disables headers.
• sticky_header: (table) Settings for the sticky header feature (requires header_lnum to be set).
  • enabled: (boolean) Whether to enable the feature.
  • separator: (string|false) The character used to separate the sticky header window. Set to false to disable.

The parser configuration object controls how the plugin interprets the file content.

• async_chunksize: (integer) Number of lines processed per cycle to prevent UI freezing. Default is 50.
• delimiter: Defines the column separator. Can be:
  1. A single string: delimiter = ","
  2. A function: delimiter = function(bufnr) return "\t" end
  3. A table with ft (filetype mappings) and fallbacks (ordered list for auto-detection).
• quote_char: (string) Character used to enclose fields (e.g., ").
• comments: (string[]) List of characters that mark the start of a comment line.
• comment_lines: (integer?) Number of lines at the top of the file to treat as comments regardless of content.
• max_lookahead: (integer) Maximum lines to look ahead for closing quotes in multi-line fields. Default is 50.

You can force a specific delimiter for all files or use a Lua function to determine the delimiter dynamically based on the buffer.

-- Fixed delimiter
{ parser = { delimiter = "," } }

-- Dynamic delimiter via function
{
  parser = {
    delimiter = function(bufnr)
      local filename = vim.api.nvim_buf_get_name(bufnr)
      if filename:match("%.tsv$") then
        return "\t"
      end
      return ","
    end,
  },
}

csvview.nvim offers two visual modes for viewing data:

1. Highlight Mode (Default): Highlights delimiter characters in their original positions, preserving the file's raw structure.
2. Border Mode: Replaces delimiters with vertical borders (│) to create a clean table appearance.

You can switch modes via Vim commands or in your configuration.

-- Highlight Mode
{ view = { display_mode = "highlight" } }

-- Border Mode
{ view = { display_mode = "border" } }

Manage how quoted fields (which may contain delimiters or newlines) are parsed.

• quote_char: Defines the character used to enclose fields (e.g., " or ').
• max_lookahead: Controls how many lines the parser searches ahead to find a closing quote for multi-line fields. Increase this for files with very long multi-line entries.

-- Quote and multi-line config
{
  parser = {
    quote_char = '"',
    max_lookahead = 50,
  },
}

Customize keymaps for navigating between fields/rows and selecting field content using text objects.

{
  keymaps = {
    -- Horizontal navigation
    jump_next_field_end = { "<Tab>", mode = { "n", "v" } },
    jump_prev_field_end = { "<S-Tab>", mode = { "n", "v" } },

    -- Vertical navigation
    jump_next_row = { "<Enter>", mode = { "n", "v" } },
    jump_prev_row = { "<S-Enter>", mode = { "n", "v" } },

    -- Text objects
    textobject_field_inner = { "if", mode = { "o", "x" } },
    textobject_field_outer = { "af", mode = { "o", "x" } },
  },
}