formatters

June 15, 2026 · View on GitHub

Formatter controls module for cosmic-ui. This module validates setup and module enable state, then executes formatter operations. Lua APIs are primary; :CosmicFormatters and :CosmicFormat are optional wrappers.

Setup

require("cosmic-ui").setup({
  formatters = {
    enabled = true,
  },
})

⚙️ Config

formatters = {
  enabled = true,
}

Types

`OpenOpts`

Field	Type	Required	Default	Description
`scope`	`"buffer"\|"global"\|nil`	No	`"buffer"`	Scope shown when UI opens.
`bufnr`	`integer\|nil`	No	current buffer (`0`)	Buffer used for discovery and local state.

`BackendOpts`

Field	Type	Required	Default	Description
`scope`	`"buffer"\|"global"\|nil`	No	`"buffer"`	Scope target for backend mutation/query.
`bufnr`	`integer\|nil`	No	current buffer (`0`)	Buffer used for local scope operations.
`backend`	`"lsp"\|"conform"\|table\|nil`	No	both backends	Backend selector.

`ItemOpts`

Field	Type	Required	Default	Description
`scope`	`"buffer"\|"global"\|nil`	No	`"buffer"`	Scope target for item mutation/query.
`bufnr`	`integer\|nil`	No	current buffer (`0`)	Buffer used for local scope operations.
`source`	`"lsp"\|"conform"`	Yes	none	Item source namespace.
`name`	`string`	Yes	none	Item name (LSP client or conform formatter).

`ResetOpts`

Field	Type	Required	Default	Description
`scope`	`"buffer"\|"global"\|nil`	No	`"buffer"`	Scope target to reset.
`bufnr`	`integer\|nil`	No	current buffer (`0`)	Buffer used for local reset scope.
`backend`	`"lsp"\|"conform"\|table\|nil`	No	both backends	Backend reset target when resetting backend state.
`source`	`"lsp"\|"conform"\|nil`	No	`nil`	Switches reset into item-reset mode.
`name`	`string\|nil`	No	`nil`	Item name to reset when `source` is set.

`FormatOpts`

Field	Type	Required	Default	Description
`scope`	`"buffer"\|"global"\|nil`	No	`"buffer"`	Scope for backend/item filtering.
`bufnr`	`integer\|nil`	No	current buffer (`0`)	Buffer to format.
`backend`	`"lsp"\|"conform"\|table\|nil`	No	both backends	Backend request selector.
`conform`	`table\|nil`	No	`{}`	Extra options for conform formatting logic.
`lsp`	`table\|nil`	No	`{}`	Extra options for `vim.lsp.buf.format`.

Module

All methods below:

warn and no-op if setup() has not run
warn and no-op if formatters is disabled
when bufnr is accepted, invalid/nonexistent handles warn and no-op
otherwise execute formatter operations immediately

`require("cosmic-ui").formatters.open(opts?)`

Opens the formatter toggle UI. Opts: OpenOpts.

`require("cosmic-ui").formatters.toggle(opts?)`

Toggles backend state (lsp/conform) for selected scope. Opts: BackendOpts.

`require("cosmic-ui").formatters.enable(opts?)`

Enables backend state for selected scope. Opts: BackendOpts.

`require("cosmic-ui").formatters.disable(opts?)`

Disables backend state for selected scope. Opts: BackendOpts.

`require("cosmic-ui").formatters.toggle_item(opts)`

Toggles one item override. Opts: ItemOpts.

`require("cosmic-ui").formatters.enable_item(opts)`

Enables one item override. Opts: ItemOpts.

`require("cosmic-ui").formatters.disable_item(opts)`

Disables one item override. Opts: ItemOpts.

`require("cosmic-ui").formatters.is_item_enabled(opts)`

Returns whether one item is enabled. Opts: ItemOpts. Returns: boolean|nil.

`require("cosmic-ui").formatters.reset(opts?)`

Clears backend and/or item overrides. Opts: ResetOpts.

`require("cosmic-ui").formatters.is_enabled(opts?)`

Returns effective backend state. Opts: BackendOpts. Returns:

boolean when a single backend is requested
{ lsp = boolean, conform = boolean } when backend is omitted or multiple

`require("cosmic-ui").formatters.status(opts?)`

Returns formatter status snapshot. Opts: OpenOpts plus optional conform.lsp_format to preview requested Conform LSP mode resolution without mutating formatter state. Returns: status table with backends, lsp_clients, and conform. Includes fallback visibility:

conform.fallback:
- requested_mode (opts.conform.lsp_format when provided)
- global_mode (from conform.default_format_opts.lsp_format)
- specific_mode + specific_filetype (from matching formatters_by_ft entry)
- display_global_mode (global Conform-config mode source for header rendering)
- display_specific_mode + display_specific_filetype (LSP header ghost text context, rendered as <specific_mode_or_global_mode>)
- mode (configured mode before backend clamp)
- effective_mode ("never"|"fallback"|"prefer"|"first"|"last")
- source (effective source: "requested"|"specific"|"global"|"default"|"clamped")
- configured_source (pre-clamp source: "requested"|"specific"|"global"|"default")
- uses_lsp, eligible_clients, total_clients, reason
lsp_clients[].conform_fallback:
- eligible, reason, mode, effective_mode, source, configured_source

`require("cosmic-ui").formatters.format(opts?)`

Runs synchronous formatting with Conform-first routing. Opts: FormatOpts. Returns: boolean|nil.

Behavior:

If Conform is installed and conform backend is enabled/requested, runs conform.format().
Else if LSP backend is enabled/requested, runs vim.lsp.buf.format().
Under Conform path:
- LSP toggle OFF forces conform.lsp_format = "never".
- LSP toggle ON uses mode precedence:
  - opts.conform.lsp_format (requested) >
  - matching Conform filetype mode (formatters_by_ft) >
  - Conform global default (default_format_opts.lsp_format) >
  - "never" default
- Supported lsp_format values:
  - "never": never use LSP
  - "fallback": use LSP only when no other formatters are available
  - "prefer": use only LSP when available
  - "first": run LSP then other formatters
  - "last": run other formatters then LSP

`require("cosmic-ui").formatters.format_async(opts?)`

Runs asynchronous formatting with the same routing rules as format. Opts: FormatOpts. Returns: boolean|nil.

Usage

local fmt = require("cosmic-ui").formatters

fmt.open()
fmt.toggle({ backend = "lsp" })
fmt.format_async({ backend = { "conform", "lsp" } })

Optional commands:

:CosmicFormatters opens the Cosmic formatter panel.
:CosmicFormat formats the current buffer.

Conform `format_on_save` example

require("conform").setup({
  format_on_save = function(bufnr)
    if not vim.g.format_on_save_enabled then
      return
    end

    local ok, cosmic = pcall(require, "cosmic-ui")
    if not (ok and cosmic.is_setup and cosmic.is_setup()) then
      return { timeout_ms = 500, lsp_format = "fallback" }
    end

    local st = cosmic.formatters.status({ scope = "buffer", bufnr = bufnr })
    local enabled = {}
    for _, f in ipairs((st and st.conform and st.conform.formatters) or {}) do
      if f.enabled then
        enabled[#enabled + 1] = f.name
      end
    end

    if #enabled == 0 then
      return nil
    end

    return {
      timeout_ms = 500,
      formatters = enabled,
      lsp_format = "never",
    }
  end,
})

Notes:

This example makes save-formatting honor CosmicUI Conform item toggles.
LSP code-action save hooks (for example ESLint fix-all) are separate from Conform formatting.