mini.nvim/lua/mini/tabline.lua at main · krig/mini.nvim

This repository was archived by the owner on Aug 28, 2025. It is now read-only.

Repository navigation

History

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

260

261

262

263

264

265

266

267

268

269

270

271

272

273

274

275

276

277

278

279

280

281

282

283

284

285

286

287

288

289

290

291

292

293

294

295

296

297

298

299

300

301

302

303

304

305

306

307

308

309

310

311

312

313

314

315

316

317

318

319

320

321

322

323

324

325

326

327

328

329

330

331

332

333

334

335

336

337

338

339

340

341

342

343

344

345

346

347

348

349

350

351

352

353

354

355

356

357

358

359

360

361

362

363

364

365

366

367

368

369

370

371

372

373

374

375

376

377

378

379

380

381

382

383

384

385

386

387

388

389

390

391

392

393

394

395

396

397

398

399

400

401

402

403

404

405

406

407

408

409

410

411

412

413

414

415

416

417

418

419

420

421

422

423

424

425

426

427

428

429

430

431

432

433

434

435

436

437

438

439

440

441

442

443

444

445

446

447

448

449

450

451

452

453

454

455

456

457

458

459

460

461

462

463

464

465

466

467

468

469

470

471

472

473

474

475

476

477

478

479

480

481

482

483

484

485

486

487

488

489

490

491

492

493

494

495

496

497

498

499

500

501

502

503

504

505

506

507

508

509

510

511

512

513

514

515

516

517

518

519

520

521

522

523

524

525

526

527

528

529

530

531

532

533

534

535

536

537

538

539

540

541

542

543

544

545

546

547

548

549

550

551

552

553

554

555

556

557

558

559

560

561

562

--- *mini.tabline* Tabline

--- *MiniTabline*

---

--- ==============================================================================

---

--- Key idea: show all listed buffers in readable way with minimal total width.

--- Also allow showing extra information section in case of multiple vim tabpages.

---

--- Features:

--- - Buffers are listed in the order of their identifier (see |bufnr()|).

---

--- - Different highlight groups for "states" of buffer affecting 'buffer tabs'.

---

--- - Buffer names are made unique by extending paths to files or appending

--- unique identifier to buffers without name.

---

--- - Current buffer is displayed "optimally centered" (in center of screen

--- while maximizing the total number of buffers shown) when there are many

--- buffers open.

---

--- - 'Buffer tabs' are clickable if Neovim allows it.

---

--- What it doesn't do:

--- - Custom buffer order is not supported.

---

--- # Dependencies ~

---

--- Suggested dependencies (provide extra functionality, will work without them):

---

--- - Enabled |MiniIcons| module to show icons near file names.

--- Falls back to using 'nvim-tree/nvim-web-devicons' plugin or shows nothing.

---

--- # Setup ~

---

--- This module needs a setup with `require('mini.tabline').setup({})`

--- (replace `{}` with your `config` table). It will create global Lua table

--- `MiniTabline` which you can use for scripting or manually (with

--- `:lua MiniTabline.*`).

---

--- See |MiniTabline.config| for `config` structure and default values.

---

--- You can override runtime config settings locally to buffer inside

--- `vim.b.minitabline_config` which should have same structure as

--- `MiniTabline.config`. See |mini.nvim-buffer-local-config| for more details.

---

--- # Highlight groups ~

---

--- * `MiniTablineCurrent` - buffer is current (has cursor in it).

--- * `MiniTablineVisible` - buffer is visible (displayed in some window).

--- * `MiniTablineHidden` - buffer is hidden (not displayed).

--- * `MiniTablineModifiedCurrent` - buffer is modified and current.

--- * `MiniTablineModifiedVisible` - buffer is modified and visible.

--- * `MiniTablineModifiedHidden` - buffer is modified and hidden.

--- * `MiniTablineFill` - unused right space of tabline.

--- * `MiniTablineTabpagesection` - section with tabpage information.

---

--- To change any highlight group, modify it directly with |:highlight|.

---

--- # Disabling ~

---

--- To disable (show empty tabline), set `vim.g.minitabline_disable` (globally) or

--- `vim.b.minitabline_disable` (for a buffer) to `true`. Considering high number

--- of different scenarios and customization intentions, writing exact rules

--- for disabling module's functionality is left to user. See

--- |mini.nvim-disabling-recipes| for common recipes.

-- Module definition ==========================================================

local MiniTabline = {}

local H = {}

--- Module setup

---

---@param config table|nil Module config table. See |MiniTabline.config|.

---

---@usage >lua

--- require('mini.tabline').setup() -- use default config

--- -- OR

--- require('mini.tabline').setup({}) -- replace {} with your config table

--- <

MiniTabline.setup = function(config)

-- Export module

_G.MiniTabline = MiniTabline

-- Setup config

config = H.setup_config(config)

-- Apply config

H.apply_config(config)

-- Define behavior

H.create_autocommands()

-- Create default highlighting

H.create_default_hl()

-- Function to make tabs clickable

vim.api.nvim_exec(

[[function! MiniTablineSwitchBuffer(buf_id, clicks, button, mod)

execute 'buffer' a:buf_id

endfunction]],

false

)

end

--- Module config

---

--- Default values:

---@eval return MiniDoc.afterlines_to_code(MiniDoc.current.eval_section)

---@text # Format ~

---

--- `config.format` is a callable that takes buffer identifier and pre-computed

--- label as arguments and returns a string with formatted label. Output will be

--- treated strictly as text (i.e. no 'statusline' like constructs is allowed).

--- This function will be called for all displayable in tabline buffers.

--- Default: |MiniTabline.default_format()|.

---

--- Example of adding "+" suffix for modified buffers: >lua

---

--- function(buf_id, label)

--- local suffix = vim.bo[buf_id].modified and '+ ' or ''

--- return MiniTabline.default_format(buf_id, label) .. suffix

--- end

--- <

MiniTabline.config = {

-- Whether to show file icons (requires 'mini.icons')

show_icons = true,

-- Function which formats the tab label

-- By default surrounds with space and possibly prepends with icon

format = nil,

-- Whether to set Vim's settings for tabline (make it always shown and

-- allow hidden buffers)

set_vim_settings = true,

-- Where to show tabpage section in case of multiple vim tabpages.

-- One of 'left', 'right', 'none'.

tabpage_section = 'left',

}

--minidoc_afterlines_end

-- Module functionality =======================================================

--- Make string for |tabline|

MiniTabline.make_tabline_string = function()

if H.is_disabled() then return '' end

H.make_tabpage_section()

H.list_tabs()

H.finalize_labels()

H.fit_width()

return H.concat_tabs()

end

--- Default tab format

---

--- Used by default as `config.format`.

--- Prepends label with padded icon based on buffer's name (if `show_icon`

--- in |MiniTabline.config| is `true`) and surrounds label with single space.

--- Note: it is meant to be used only as part of `format` in |MiniTabline.config|.

---

---@param buf_id number Buffer identifier.

---@param label string Pre-computed label.

---

---@return string Formatted label.

MiniTabline.default_format = function(buf_id, label)

if H.get_icon == nil then return string.format(' %s ', label) end

return string.format(' %s %s ', H.get_icon(vim.api.nvim_buf_get_name(buf_id)), label)

end

-- Helper data ================================================================

-- Module default config

H.default_config = vim.deepcopy(MiniTabline.config)

-- Table to keep track of tabs

H.tabs = {}

-- Indicator of whether there is clickable support

H.tablineat = vim.fn.has('tablineat')

-- Keep track of initially unnamed buffers

H.unnamed_buffers_seq_ids = {}

-- Separator of file path

H.path_sep = package.config:sub(1, 1)

-- String with tabpage prefix

H.tabpage_section = ''

-- Buffer number of center buffer

H.center_buf_id = nil

-- Helper functionality =======================================================

-- Settings -------------------------------------------------------------------

H.setup_config = function(config)

H.check_type('config', config, 'table', true)

config = vim.tbl_deep_extend('force', vim.deepcopy(H.default_config), config or {})

H.check_type('show_icons', config.show_icons, 'boolean')

H.check_type('format', config.format, 'function', true)

H.check_type('set_vim_settings', config.set_vim_settings, 'boolean')

H.check_type('tabpage_section', config.tabpage_section, 'string')

return config

end

H.apply_config = function(config)

MiniTabline.config = config

-- Set settings to ensure tabline is displayed properly

if config.set_vim_settings then

vim.o.showtabline = 2 -- Always show tabline

vim.o.hidden = true -- Allow switching buffers without saving them

end

-- Set tabline string

vim.o.tabline = '%!v:lua.MiniTabline.make_tabline_string()'

end

H.create_autocommands = function()

local gr = vim.api.nvim_create_augroup('MiniTabline', {})

vim.api.nvim_create_autocmd('ColorScheme', { group = gr, callback = H.create_default_hl, desc = 'Ensure colors' })

end

--stylua: ignore

H.create_default_hl = function()

local set_default_hl = function(name, data)

data.default = true

vim.api.nvim_set_hl(0, name, data)

end

set_default_hl('MiniTablineCurrent', { link = 'TabLineSel' })

set_default_hl('MiniTablineVisible', { link = 'TabLineSel' })

set_default_hl('MiniTablineHidden', { link = 'TabLine' })

set_default_hl('MiniTablineModifiedCurrent', { link = 'StatusLine' })

set_default_hl('MiniTablineModifiedVisible', { link = 'StatusLine' })

set_default_hl('MiniTablineModifiedHidden', { link = 'StatusLineNC' })

set_default_hl('MiniTablineTabpagesection', { link = 'Search' })

set_default_hl('MiniTablineFill', { link = 'Normal' })

end

H.is_disabled = function() return vim.g.minitabline_disable == true or vim.b.minitabline_disable == true end

H.get_config = function(config)

return vim.tbl_deep_extend('force', MiniTabline.config, vim.b.minitabline_config or {}, config or {})

end

-- Work with tabpages ---------------------------------------------------------

H.make_tabpage_section = function()

local n_tabpages = vim.fn.tabpagenr('$')

if n_tabpages == 1 or H.get_config().tabpage_section == 'none' then

H.tabpage_section = ''

return

end

local cur_tabpagenr = vim.fn.tabpagenr()

H.tabpage_section = (' Tab %s/%s '):format(cur_tabpagenr, n_tabpages)

end

-- Work with tabs -------------------------------------------------------------

-- List tabs

H.list_tabs = function()

local tabs = {}

for _, buf_id in ipairs(vim.api.nvim_list_bufs()) do

if H.is_buffer_in_minitabline(buf_id) then

local tab = { buf_id = buf_id }

tab['hl'] = H.construct_highlight(buf_id)

tab['tabfunc'] = H.construct_tabfunc(buf_id)

tab['label'], tab['label_extender'] = H.construct_label_data(buf_id)

table.insert(tabs, tab)

end

H.tabs = tabs

end

H.is_buffer_in_minitabline = function(buf_id) return vim.bo[buf_id].buflisted end

-- Tab's highlight group

H.construct_highlight = function(buf_id)

local hl_type

if buf_id == vim.api.nvim_get_current_buf() then

hl_type = 'Current'

elseif vim.fn.bufwinnr(buf_id) > 0 then

hl_type = 'Visible'

else

hl_type = 'Hidden'

end

if vim.bo[buf_id].modified then hl_type = 'Modified' .. hl_type end

return string.format('%%#MiniTabline%s#', hl_type)

end

-- Tab's clickable action (if supported)

H.construct_tabfunc = function(buf_id)

if H.tablineat > 0 then

return string.format('%%%d@MiniTablineSwitchBuffer@', buf_id)

else

return ''

end

-- Tab's label and label extender

H.construct_label_data = function(buf_id)

local label, label_extender

local bufpath = vim.api.nvim_buf_get_name(buf_id)

if bufpath ~= '' then

-- Process path buffer

label = vim.fn.fnamemodify(bufpath, ':t')

label_extender = H.make_path_extender(buf_id)

else

-- Process unnamed buffer

label = H.make_unnamed_label(buf_id)

label_extender = function(x) return x end

end

return label, label_extender

end

H.make_path_extender = function(buf_id)

-- Add parent to current label (if possible)

return function(label)

local full_path = vim.api.nvim_buf_get_name(buf_id)

-- Using `vim.pesc` prevents effect of problematic characters (like '.')

local pattern = string.format('[^%s]+%s%s$', vim.pesc(H.path_sep), vim.pesc(H.path_sep), vim.pesc(label))

return string.match(full_path, pattern) or label

end

-- Work with unnamed buffers --------------------------------------------------

-- Unnamed buffers are tracked in `H.unnamed_buffers_seq_ids` for

-- disambiguation. This table is designed to store 'sequential' buffer

-- identifier. This approach allows to have the following behavior:

-- - Create three unnamed buffers.

-- - Delete second one.

-- - Tab label for third one remains the same.

H.make_unnamed_label = function(buf_id)

local label

if vim.bo[buf_id].buftype == 'quickfix' then

-- It would be great to differentiate for buffer `buf_id` between quickfix

-- and location lists but it seems there is no reliable way to do so.

-- The only one is to use `getwininfo(bufwinid(buf_id))` and look for

-- `quickfix` and `loclist` fields, but that fails if buffer `buf_id` is

-- not visible.

label = '*quickfix*'

else

label = H.is_buffer_scratch(buf_id) and '!' or '*'

end

-- Possibly add tracking id

local unnamed_id = H.get_unnamed_id(buf_id)

if unnamed_id > 1 then label = string.format('%s(%d)', label, unnamed_id) end

return label

end

H.is_buffer_scratch = function(buf_id)

local buftype = vim.bo[buf_id].buftype

return (buftype == 'acwrite') or (buftype == 'nofile')

end

H.get_unnamed_id = function(buf_id)

-- Use existing sequential id if possible

local seq_id = H.unnamed_buffers_seq_ids[buf_id]

if seq_id ~= nil then return seq_id end

-- Cache sequential id for currently unnamed buffer `buf_id`

H.unnamed_buffers_seq_ids[buf_id] = vim.tbl_count(H.unnamed_buffers_seq_ids) + 1

return H.unnamed_buffers_seq_ids[buf_id]

end

-- Work with labels -----------------------------------------------------------

H.finalize_labels = function()

-- Deduplicate

local nonunique_tab_ids = H.get_nonunique_tab_ids()

while #nonunique_tab_ids > 0 do

local nothing_changed = true

-- Extend labels

for _, buf_id in ipairs(nonunique_tab_ids) do

local tab = H.tabs[buf_id]

local old_label = tab.label

tab.label = tab.label_extender(tab.label)

if old_label ~= tab.label then nothing_changed = false end

end

if nothing_changed then break end

nonunique_tab_ids = H.get_nonunique_tab_ids()

end

-- Format labels

local config = H.get_config()

-- - Ensure cached `get_icon` for `default_format` (for better performance)

H.ensure_get_icon(config)

-- - Apply formatting

local format = config.format or MiniTabline.default_format

for _, tab in pairs(H.tabs) do

tab.label = format(tab.buf_id, tab.label)

end

---@return table Array of `H.tabs` ids which have non-unique labels.

---@private

H.get_nonunique_tab_ids = function()

-- Collect tab-array-id per label

local label_tab_ids = {}

for i, tab in ipairs(H.tabs) do

local label = tab.label

if label_tab_ids[label] == nil then

label_tab_ids[label] = { i }

else

table.insert(label_tab_ids[label], i)

end

-- Collect tab-array-ids with non-unique labels

return H.tbl_flatten(vim.tbl_filter(function(x) return #x > 1 end, label_tab_ids))

end

-- Fit tabline to maximum displayed width -------------------------------------

H.fit_width = function()

H.update_center_buf_id()

-- Compute label width data

local center_offset = 1

local tot_width = 0

for _, tab in pairs(H.tabs) do

-- Use `nvim_strwidth()` and not `:len()` to respect multibyte characters

tab.label_width = vim.api.nvim_strwidth(tab.label)

tab.chars_on_left = tot_width

tot_width = tot_width + tab.label_width

if tab.buf_id == H.center_buf_id then

-- Make right end of 'center tab' to be always displayed in center in

-- case of truncation

center_offset = tot_width

end

local display_interval = H.compute_display_interval(center_offset, tot_width)

H.truncate_tabs_display(display_interval)

end

H.update_center_buf_id = function()

local cur_buf = vim.api.nvim_get_current_buf()

if H.is_buffer_in_minitabline(cur_buf) then H.center_buf_id = cur_buf end

end

H.compute_display_interval = function(center_offset, tabline_width)

-- left - first character to be displayed (starts with 1)

-- right - last character to be displayed

-- Conditions to be satisfied:

-- 1) right - left + 1 = math.min(tot_width, tabline_width)

-- 2) 1 <= left <= tabline_width; 1 <= right <= tabline_width

local tot_width = vim.o.columns - vim.api.nvim_strwidth(H.tabpage_section)

-- Usage of `math.floor` is crucial to avoid non-integer values which might

-- affect total width of output tabline string.

-- Using `floor` instead of `ceil` has effect when `tot_width` is odd:

-- - `floor` makes "true center" to be between second to last and last label

-- character (usually non-space and space).

-- - `ceil` - between last character of center label and first character of

-- next label (both whitespaces).

local right = math.min(tabline_width, math.floor(center_offset + 0.5 * tot_width))

local left = math.max(1, right - tot_width + 1)

right = left + math.min(tot_width, tabline_width) - 1

return { left, right }

end

H.truncate_tabs_display = function(display_interval)

local display_left, display_right = display_interval[1], display_interval[2]

local tabs = {}

for _, tab in ipairs(H.tabs) do

local tab_left = tab.chars_on_left + 1

local tab_right = tab.chars_on_left + tab.label_width

if (display_left <= tab_right) and (tab_left <= display_right) then

-- Process tab that should be displayed (even partially)

local n_trunc_left = math.max(0, display_left - tab_left)

local n_trunc_right = math.max(0, tab_right - display_right)

-- Take desired amount of characters starting from `n_trunc_left`

tab.label = vim.fn.strcharpart(tab.label, n_trunc_left, tab.label_width - n_trunc_right)

table.insert(tabs, tab)

end

H.tabs = tabs

end

-- Concatenate tabs into single tablien string --------------------------------

H.concat_tabs = function()

-- NOTE: it is assumed that all padding is incorporated into labels

local t = {}

for _, tab in ipairs(H.tabs) do

-- Escape '%' in labels

table.insert(t, ('%s%s%s'):format(tab.hl, tab.tabfunc, tab.label:gsub('%%', '%%%%')))

end

-- Usage of `%X` makes filled space to the right 'non-clickable'

local res = ('%s%%X%%#MiniTablineFill#'):format(table.concat(t, ''))

-- Add tabpage section

local position = H.get_config().tabpage_section

if H.tabpage_section ~= '' then

if position == 'left' then res = ('%%#MiniTablineTabpagesection#%s%s'):format(H.tabpage_section, res) end

if position == 'right' then

-- Use `%=` to make it stick to right hand side

res = ('%s%%=%%#MiniTablineTabpagesection#%s'):format(res, H.tabpage_section)

end

return res

end

-- Utilities ------------------------------------------------------------------

H.error = function(msg) error('(mini.tabline) ' .. msg, 0) end

H.check_type = function(name, val, ref, allow_nil)

if type(val) == ref or (ref == 'callable' and vim.is_callable(val)) or (allow_nil and val == nil) then return end

H.error(string.format('`%s` should be %s, not %s', name, ref, type(val)))

end

H.ensure_get_icon = function(config)

if not config.show_icons then

-- Show no icon

H.get_icon = nil

elseif H.get_icon ~= nil then

-- Cache only once

return

elseif _G.MiniIcons ~= nil then

-- Prefer 'mini.icons'

H.get_icon = function(name) return (_G.MiniIcons.get('file', name)) end

else

-- Try falling back to 'nvim-web-devicons'

local has_devicons, devicons = pcall(require, 'nvim-web-devicons')

if not has_devicons then return end

-- Use basename because it makes exact file name matching work

H.get_icon = function(name) return (devicons.get_icon(vim.fn.fnamemodify(name, ':t'), nil, { default = true })) end

end

-- TODO: Remove after compatibility with Neovim=0.9 is dropped

H.tbl_flatten = vim.fn.has('nvim-0.10') == 1 and function(x) return vim.iter(x):flatten(math.huge):totable() end

or vim.tbl_flatten

return MiniTabline

FilesExpand file tree

tabline.lua

Latest commit

History

tabline.lua

File metadata and controls